diff --git a/_data/toc.yaml b/_data/toc.yaml index c3b81c54c0..9981ed3246 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -1601,6 +1601,8 @@ manuals: path: /ee/ucp/kubernetes/ - title: Deploy a Compose-based app path: /ee/ucp/kubernetes/deploy-with-compose/ + - title: Using Pod Security Policies + path: /ee/ucp/kubernetes/pod-security-policies/ - title: Deploy an ingress controller path: /ee/ucp/kubernetes/layer-7-routing/ - title: Create a service account for a Kubernetes app diff --git a/ee/ucp/kubernetes/pod-security-policies.md b/ee/ucp/kubernetes/pod-security-policies.md new file mode 100644 index 0000000000..887bf424a4 --- /dev/null +++ b/ee/ucp/kubernetes/pod-security-policies.md @@ -0,0 +1,467 @@ +--- +title: Use Pod Security Policies in UCP +description: Learn how to use Pod Security Policies to lock down Kubernetes as part of Universal Control Plane. +keywords: UCP, Kubernetes, psps, pod security policies +redirect_from: +--- +Pod Security Policies (PSPs) are cluster-level resources which are enabled by default in Docker Universal Control Plane (UCP) 3.2. See [Pod Security Policy](https://kubernetes.io/docs/concepts/policy/pod-security-policy/) for an explanation of this Kubernetes concept. + + +There are two default PSPs in UCP: a `privileged` policy +and an `unprivileged` policy. Administrators of the cluster can enforce additional +policies and apply them to users and teams for further control of what runs in the +Kubernetes cluster. This guide describes the two default policies, and +provides two example use cases for custom policies. + +## Kubernetes Role Based Access Control (RBAC) + +To interact with PSPs, a user will need to be granted access to +the `PodSecurityPolicy` object in Kubernetes RBAC. If the user is a `UCP Admin`, +or has been granted the `ClusterRole`: `cluster-admin` for all namespaces, then +the user can already manipulate PSPs. Additionally, a normal +user can interact with policies if a UCP admin creates the following +`ClusterRole` and `ClusterRoleBinding`: + +``` +$ cat < Note: PSPs do not override security defaults built into the +> UCP RBAC engine for Kubernetes pods. These [Security +> defaults](https://docs.docker.com/ee/ucp/authorization/) prevent non-admin +> users from mounting host paths into pods or starting privileged pods. + +```bash +$ kubectl get podsecuritypolicies +NAME PRIV CAPS SELINUX RUNASUSER FSGROUP SUPGROUP READONLYROOTFS VOLUMES +privileged true * RunAsAny RunAsAny RunAsAny RunAsAny false * +unprivileged false RunAsAny RunAsAny RunAsAny RunAsAny false * +``` + +The specification for the `privileged` policy is as follows: + +``` + allowPrivilegeEscalation: true + allowedCapabilities: + - '*' + fsGroup: + rule: RunAsAny + hostIPC: true + hostNetwork: true + hostPID: true + hostPorts: + - max: 65535 + min: 0 + privileged: true + runAsUser: + rule: RunAsAny + seLinux: + rule: RunAsAny + supplementalGroups: + rule: RunAsAny + volumes: + - '*' +``` + +The specification for the `unprivileged` policy is as follows: + +``` + allowPrivilegeEscalation: false + allowedHostPaths: + - pathPrefix: /dev/null + readOnly: true + fsGroup: + rule: RunAsAny + hostPorts: + - max: 65535 + min: 0 + runAsUser: + rule: RunAsAny + seLinux: + rule: RunAsAny + supplementalGroups: + rule: RunAsAny + volumes: + - '*' +``` + +## Use the unprivileged policy + +> Note: When following this guide, if the prompt `$` follows `admin`, the action +> needs to be performed by a user with access to create pod security policies as +> discussed in [the Kubernetes RBAC section](#kubernetes-role-based-access-control). If the prompt `$` +> follows `user`, the UCP account does not need access to the PSP +> object in Kubernetes. The user only needs the ability to create Kubernetes pods. +> + +To switch users from the `privileged` policy to the `unprivileged` policy (or +any custom policy), an admin must first remove the `ClusterRoleBinding` that +links all users and service accounts to the `privileged` policy. + +``` +admin $ kubectl delete clusterrolebindings ucp:all:privileged-psp-role +``` + +When the `ClusterRoleBinding` is removed, cluster admins can still deploy pods, +and these pods are deployed with the `privileged` policy. But users or service +accounts are unable to deploy pods, because Kubernetes does not know what pod +security policy to apply. + +```bash +user $ kubectl apply -f pod.yaml +Error from server (Forbidden): error when creating "pod.yaml": pods "demopod" is forbidden: unable to validate against any pod security policy: [] +``` + +Therefore, to allow a user or a service account to use the `unprivileged` policy +(or any custom policy), you must create a `RoleBinding` to link that user or +team with the alternative policy. For the `unprivileged` policy, a `ClusterRole` +has already been defined, but has not been attached to a user. + +```bash +# List Existing Cluster Roles +admin $ kubectl get clusterrole | grep psp +privileged-psp-role 3h47m +unprivileged-psp-role 3h47m + +# Define which user to apply the ClusterRole too +admin $ USER=jeff + +# Create a RoleBinding linking the ClusterRole to the User +admin $ cat < + Error: container has runAsNonRoot and image will run as root +``` + +### Example 2: Use a PSP to apply seccomp policies + +A second use case for PSPs is to prevent a user from deploying +containers without a [seccomp +policy](https://docs.docker.com/engine/security/seccomp/). By default, +Kubernetes does not apply a seccomp policy to pods, so a default seccomp policy +could be applied for all pods by a PSP. + +```bash +admin $ cat <