From 951f67d00b8d408d9893473d3111d7f369726629 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Christian=20H=C3=BCning?= <christian.huening@haw-hamburg.de>
Date: Thu, 21 Dec 2017 23:42:15 +0100
Subject: [PATCH] Added documentation regarding PodSecurityPolicies

Updated according to review

removed remark towards "yaml below" as it wasn't clear in the context

removed two empty lines and added comment and example for hostPorts

More changes as per latest review

Specified port range for the PodSecurityPolicy

added inline comments for ports

clarified text about required PSP

updated header section
---
 Documentation/cluster-crd.md |   2 +-
 Documentation/kubernetes.md  | 124 +++++++++++++++++++++++++++++++++++
 2 files changed, 125 insertions(+), 1 deletion(-)

diff --git a/Documentation/cluster-crd.md b/Documentation/cluster-crd.md
index b312f4e14..8415ee746 100644
--- a/Documentation/cluster-crd.md
+++ b/Documentation/cluster-crd.md
@@ -295,4 +295,4 @@ spec:
         requests:
           cpu: "2"
           memory: "4096Mi"
-```
+```
\ No newline at end of file
diff --git a/Documentation/kubernetes.md b/Documentation/kubernetes.md
index 3067706c4..373be4765 100644
--- a/Documentation/kubernetes.md
+++ b/Documentation/kubernetes.md
@@ -36,6 +36,130 @@ kubectl create -f rook-operator.yaml
 # verify the rook-operator and rook-agents pods are in the `Running` state before proceeding
 kubectl -n rook-system get pod
 ```
+## RBAC for PodSecurityPolicies
+
+If you have activated the [PodSecurityPolicy Admission Controller](https://kubernetes.io/docs/admin/admission-controllers/#podsecuritypolicy) and thus are
+using [PodSecurityPolicies](https://kubernetes.io/docs/concepts/policy/pod-security-policy/), you will require additional `(Cluster)RoleBindings` 
+for the different `ServiceAccounts` Rook uses to start the Rook Storage Pods.
+ 
+**Note**: You do not have to perform these steps if you do not have the `PodSecurityPolicy` Admission Controller activated!  
+
+##### PodSecurityPolicy 
+
+You need one `PodSecurityPolicy` that allows privileged `Pod` execution. Here is an example:
+
+```yaml
+apiVersion: extensions/v1beta1
+kind: PodSecurityPolicy
+metadata:
+  name: privileged
+spec:
+  fsGroup:
+    rule: RunAsAny
+  privileged: true
+  runAsUser:
+    rule: RunAsAny
+  seLinux:
+    rule: RunAsAny
+  supplementalGroups:
+    rule: RunAsAny
+  volumes:
+  - '*'
+  allowedCapabilities:
+  - '*'
+  hostPID: true
+  hostIPC: true
+  hostNetwork: false
+```
+
+**Hint**: Allowing `hostNetwork` usage is required when using `hostNetwork: true` in the Cluster `CustomResourceDefinition`!
+You are then also required to allow the usage of `hostPorts` in the `PodSecurityPolicy`. The given port range is a minimal 
+working recommendation for rook:
+ ```yaml
+ hostPorts:
+   # CEPH ports
+   - min: 6789
+     max: 7300
+   # rook-api port
+   - min: 8124
+     max: 8124
+```
+
+##### ClusterRole and ClusterRoleBinding
+
+Next up you require a `ClusterRole` and a corresponding `ClusterRoleBinding`, which enables the Rook Agent `ServiceAccount` to run the rook-agent `Pods` on all nodes
+with privileged rights. Here are the definitions:
+
+```yaml
+# privilegedPSP grants access to use the privileged PSP.
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: privileged-psp-user
+rules:
+- apiGroups:
+  - extensions
+  resources:
+  - podsecuritypolicies
+  resourceNames:
+  - privileged
+  verbs:
+  - use
+  
+```
+and 
+```yaml
+# Allow the rook-agent serviceAccount to use the privileged PSP
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: rook-agent-psp
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: privileged-psp-user
+subjects:
+- kind: ServiceAccount
+  name: rook-agent
+  namespace: rook-system
+``` 
+
+Save these definitions to one or multiple yaml files and create them by executing `kubectl apply -f <nameOfYourFile>.yaml`
+
+You will also require two more `RoleBindings` for each Rook Cluster you deploy:
+Create these two `RoleBindings` in the Namespace you plan to deploy your Rook Cluster into (default is "rook" namespace):
+ 
+```yaml
+# Allow the default serviceAccount to use the priviliged PSP
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: rook-default-psp
+  namespace: rook
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: privileged-psp-user
+subjects:
+- kind: ServiceAccount
+  name: default
+  namespace: rook
+---
+# Allow the rook-ceph-osd serviceAccount to use the priviliged PSP
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: rook-ceph-osd-psp
+  namespace: rook
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: privileged-psp-user
+subjects:
+- kind: ServiceAccount
+  name: rook-ceph-osd
+  namespace: rook
+``` 
 
 ---
 #### **Restart Kubelet**