Merge pull request #28587 from tallclair/psp-migration

PodSecurity Standards & PSP Best Practices

content/en/docs/concepts/policy/pod-security-policy.md

@@ -11,7 +11,8 @@ weight: 30
 
 {{< feature-state for_k8s_version="v1.21" state="deprecated" >}}
 
-PodSecurityPolicy is deprecated as of Kubernetes v1.21, and will be removed in v1.25.
+PodSecurityPolicy is deprecated as of Kubernetes v1.21, and will be removed in v1.25. For more information on the deprecation,
+see [PodSecurityPolicy Deprecation: Past, Present, and Future](/blog/2021/04/06/podsecuritypolicy-deprecation-past-present-and-future/).
 
 Pod Security Policies enable fine-grained authorization of pod creation and
 updates.
@@ -48,13 +49,12 @@ administrator to control the following:
 
 ## Enabling Pod Security Policies
 
-Pod security policy control is implemented as an optional (but recommended)
+Pod security policy control is implemented as an optional [admission
-[admission
+controller](/docs/reference/access-authn-authz/admission-controllers/#podsecuritypolicy).
-controller](/docs/reference/access-authn-authz/admission-controllers/#podsecuritypolicy). PodSecurityPolicies
+PodSecurityPolicies are enforced by [enabling the admission
-are enforced by [enabling the admission
 controller](/docs/reference/access-authn-authz/admission-controllers/#how-do-i-turn-on-an-admission-control-plug-in),
-but doing so without authorizing any policies **will prevent any pods from being
+but doing so without authorizing any policies **will prevent any pods from being created** in the
-created** in the cluster.
+cluster.
 
 Since the pod security policy API (`policy/v1beta1/podsecuritypolicy`) is
 enabled independently of the admission controller, for existing clusters it is
@@ -110,7 +110,11 @@ roleRef:
   name: <role name>
   apiGroup: rbac.authorization.k8s.io
 subjects:
-# Authorize specific service accounts:
+# Authorize all service accounts in a namespace (recommended):
+- kind: Group
+  apiGroup: rbac.authorization.k8s.io
+  name: system:serviceaccounts:<authorized namespace>
+# Authorize specific service accounts (not recommended):
 - kind: ServiceAccount
   name: <authorized service account name>
   namespace: <authorized pod namespace>
@@ -139,6 +143,40 @@ Examples](/docs/reference/access-authn-authz/rbac#role-binding-examples).
 For a complete example of authorizing a PodSecurityPolicy, see
 [below](#example).
 
+### Recommended Practice
+
+PodSecurityPolicy is being replaced by a new, simplified `PodSecurity` {{< glossary_tooltip
+text="admission controller" term_id="admission-controller" >}}. For more details on this change, see
+[PodSecurityPolicy Deprecation: Past, Present, and
+Future](/blog/2021/04/06/podsecuritypolicy-deprecation-past-present-and-future/). Follow these
+guidelines to simplify migration from PodSecurityPolicy to the new admission controller:
+
+1. Limit your PodSecurityPolicies to the policies defined by the [Pod Security Standards](/docs/concepts/security/pod-security-standards):
+    - {{< example file="policy/privileged-psp.yaml" >}}Privileged{{< /example >}}
+    - {{< example file="policy/baseline-psp.yaml" >}}Baseline{{< /example >}}
+    - {{< example file="policy/restricted-psp.yaml" >}}Restricted{{< /example >}}
+
+2. Only bind PSPs to entire namespaces, by using the `system:serviceaccounts:<namespace>` group
+   (where `<namespace>` is the target namespace). For example:
+
+    ```yaml
+    apiVersion: rbac.authorization.k8s.io/v1
+    # This cluster role binding allows all pods in the "development" namespace to use the baseline PSP.
+    kind: ClusterRoleBinding
+    metadata:
+      name: psp-baseline-namespaces
+    roleRef:
+      kind: ClusterRole
+      name: psp-baseline
+      apiGroup: rbac.authorization.k8s.io
+    subjects:
+    - kind: Group
+      name: system:serviceaccounts:development
+      apiGroup: rbac.authorization.k8s.io
+    - kind: Group
+      name: system:serviceaccounts:canary
+      apiGroup: rbac.authorization.k8s.io
+    ```
 
 ### Troubleshooting
 
@@ -661,8 +699,10 @@ Refer to the [Sysctl documentation](
 
 ## {{% heading "whatsnext" %}}
 
+- See [PodSecurityPolicy Deprecation: Past, Present, and
+  Future](/blog/2021/04/06/podsecuritypolicy-deprecation-past-present-and-future/) to learn about
+  the future of pod security policy.
+
 - See [Pod Security Standards](/docs/concepts/security/pod-security-standards/) for policy recommendations.
 
 - Refer to [Pod Security Policy Reference](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podsecuritypolicy-v1beta1-policy) for the api details.
-
-

content/en/docs/concepts/security/pod-security-standards.md

@@ -86,7 +86,7 @@ enforced/disallowed:
 		<tr>
 			<td>Capabilities</td>
 			<td>
-				Adding additional capabilities beyond the <a href="https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities">default set</a> must be disallowed.<br>
+				Adding <tt>NET_RAW</tt> or capabilities beyond the <a href="https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities">default set</a> must be disallowed.<br>
 				<br><b>Restricted Fields:</b><br>
 				spec.containers[*].securityContext.capabilities.add<br>
 				spec.initContainers[*].securityContext.capabilities.add<br>
@@ -194,7 +194,7 @@ well as lower-trust users.The following listed controls should be enforced/disal
 		<tr>
 			<td>Volume Types</td>
 			<td>
-				In addition to restricting HostPath volumes, the restricted profile limits usage of non-core volume types to those defined through PersistentVolumes.<br>
+				In addition to restricting HostPath volumes, the restricted profile limits usage of non-ephemeral volume types to those defined through PersistentVolumes.<br>
 				<br><b>Restricted Fields:</b><br>
 				spec.volumes[*].hostPath<br>
 				spec.volumes[*].gcePersistentDisk<br>
@@ -216,7 +216,6 @@ well as lower-trust users.The following listed controls should be enforced/disal
 				spec.volumes[*].portworxVolume<br>
 				spec.volumes[*].scaleIO<br>
 				spec.volumes[*].storageos<br>
-				spec.volumes[*].csi<br>
 				<br><b>Allowed Values:</b> undefined/nil<br>
 			</td>
 		</tr>

content/en/examples/policy/baseline-psp.yaml

@@ -6,20 +6,16 @@ metadata:
     # Optional: Allow the default AppArmor profile, requires setting the default.
     apparmor.security.beta.kubernetes.io/allowedProfileNames: 'runtime/default'
     apparmor.security.beta.kubernetes.io/defaultProfileName:  'runtime/default'
-    # Optional: Allow the default seccomp profile, requires setting the default.
+    seccomp.security.alpha.kubernetes.io/allowedProfileNames: '*'
-    seccomp.security.alpha.kubernetes.io/allowedProfileNames: 'docker/default,runtime/default,unconfined'
-    seccomp.security.alpha.kubernetes.io/defaultProfileName:  'unconfined'
 spec:
   privileged: false
-  # The moby default capability set, defined here:
+  # The moby default capability set, minus NET_RAW
-  # https://github.com/moby/moby/blob/0a5cec2833f82a6ad797d70acbf9cbbaf8956017/oci/caps/defaults.go#L6-L19
   allowedCapabilities:
     - 'CHOWN'
     - 'DAC_OVERRIDE'
     - 'FSETID'
     - 'FOWNER'
     - 'MKNOD'
-    - 'NET_RAW'
     - 'SETGID'
     - 'SETUID'
     - 'SETFCAP'
@@ -36,15 +32,16 @@ spec:
     - 'projected'
     - 'secret'
     - 'downwardAPI'
-    # Assume that persistentVolumes set up by the cluster admin are safe to use.
+    # Assume that ephemeral CSI drivers & persistentVolumes set up by the cluster admin are safe to use.
+    - 'csi'
     - 'persistentVolumeClaim'
+    - 'ephemeral'
     # Allow all other non-hostpath volume types.
     - 'awsElasticBlockStore'
     - 'azureDisk'
     - 'azureFile'
     - 'cephFS'
     - 'cinder'
-    - 'csi'
     - 'fc'
     - 'flexVolume'
     - 'flocker'
@@ -67,6 +64,9 @@ spec:
   runAsUser:
     rule: 'RunAsAny'
   seLinux:
+    # This policy assumes the nodes are using AppArmor rather than SELinux.
+    # The PSP SELinux API cannot express the SELinux Pod Security Standards,
+    # so if using SELinux, you must choose a more restrictive default.
     rule: 'RunAsAny'
   supplementalGroups:
     rule: 'RunAsAny'

content/en/examples/policy/restricted-psp.yaml

@@ -5,14 +5,11 @@ metadata:
   annotations:
     seccomp.security.alpha.kubernetes.io/allowedProfileNames: 'docker/default,runtime/default'
     apparmor.security.beta.kubernetes.io/allowedProfileNames: 'runtime/default'
-    seccomp.security.alpha.kubernetes.io/defaultProfileName:  'runtime/default'
     apparmor.security.beta.kubernetes.io/defaultProfileName:  'runtime/default'
 spec:
   privileged: false
   # Required to prevent escalations to root.
   allowPrivilegeEscalation: false
-  # This is redundant with non-root + disallow privilege escalation,
-  # but we can provide it for defense in depth.
   requiredDropCapabilities:
     - ALL
   # Allow core volume types.
@@ -22,8 +19,10 @@ spec:
     - 'projected'
     - 'secret'
     - 'downwardAPI'
-    # Assume that persistentVolumes set up by the cluster admin are safe to use.
+    # Assume that ephemeral CSI drivers & persistentVolumes set up by the cluster admin are safe to use.
+    - 'csi'
     - 'persistentVolumeClaim'
+    - 'ephemeral'
   hostNetwork: false
   hostIPC: false
   hostPID: false