Address PR feedback

Author: tallclair

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

@@ -115,7 +115,7 @@ subjects:
 - kind: Group
   apiGroup: rbac.authorization.k8s.io
   name: system:serviceaccounts:<authorized namespace>
-# Authorize specific service accounts:
+# Authorize specific service accounts (not recommended):
 - kind: ServiceAccount
   name: <authorized service account name>
   namespace: <authorized pod namespace>
@@ -144,20 +144,21 @@ Examples](/docs/reference/access-authn-authz/rbac#role-binding-examples).
 For a complete example of authorizing a PodSecurityPolicy, see
 [below](#example).
 
-### Best Practices
+### Recommended Practice
 
-PodSecurityPolicy is being replaced by a new, simplified PodSecurity admission controller. The
-following recommended best-practices will make the migration to the new PodSecurity admission
-controller much simpler. For more details on this change, see
-[PodSecurityPolicy Deprecation: Past, Present, and Future](/blog/2021/04/06/podsecuritypolicy-deprecation-past-present-and-future/).
+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):
-    - [Privileged](https://raw.githubusercontent.com/kubernetes/website/master/content/en/examples/policy/privileged-psp.yaml)
-    - [Baseline](https://raw.githubusercontent.com/kubernetes/website/master/content/en/examples/policy/baseline-psp.yaml)
-    - [Restricted](https://raw.githubusercontent.com/kubernetes/website/master/content/en/examples/policy/restricted-psp.yaml)
+    - {{< 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 namespaces, by using the `system:serviceaccounts:<namespace>` group (where
-   `<namespace>` is the target namespace). For 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
@@ -699,6 +700,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 (excluding NET_RAW)</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>

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

@@ -6,9 +6,7 @@ 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: 'docker/default,runtime/default,unconfined'
-    seccomp.security.alpha.kubernetes.io/defaultProfileName:  'unconfined'
+    seccomp.security.alpha.kubernetes.io/allowedProfileNames: '*'
 spec:
   privileged: false
   # The moby default capability set, minus NET_RAW
@@ -34,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'

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,9 +19,10 @@ spec:
     - 'projected'
     - 'secret'
     - 'downwardAPI'
-    # Assume that CSI drivers & persistentVolumes set up by the cluster admin are safe to use.
-    - 'persistentVolumeClaim'
+    # 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