Merge pull request rook#1348 from christianhuening/psp_docs

Added documentation regarding PodSecurityPolicies
bizviznavneet · Dec 30, 2017 · 5ed06b8 · 5ed06b8
2 parents 749bba5 + 951f67d
commit 5ed06b8
Show file tree

Hide file tree

Showing 2 changed files with 125 additions and 1 deletion.
diff --git a/Documentation/cluster-crd.md b/Documentation/cluster-crd.md
@@ -295,4 +295,4 @@ spec:
         requests:
           cpu: "2"
           memory: "4096Mi"
-```
+```
diff --git 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**