Move PSP into Security concepts section

Tim Bannister · reylejano · Tim Bannister · commit 672813f3e782 · 2022-03-30T17:30:35.000+01:00
The logical navigation definitely works better if Pod Security admission
and PodSecurityPolicy are pages in the same section. Make It So.

Co-authored-by: Rey Lejano &lt;rlejano@gmail.com&gt;
diff --git a/content/en/blog/_posts/2020-11-18-cloud-native-security-for-your-cluster/index.md b/content/en/blog/_posts/2020-11-18-cloud-native-security-for-your-cluster/index.md
@@ -18,7 +18,7 @@ The paper attempts to _not_ focus on any specific [cloud native project](https:/
 
 ## Kubernetes native security controls
 When using Kubernetes as a workload orchestrator, some of the security controls this version of the whitepaper recommends are:
-* [Pod Security Policies](/docs/concepts/policy/pod-security-policy/): Implement a single source of truth for “least privilege” workloads across the entire cluster
+* [Pod Security Policies](/docs/concepts/security/pod-security-policy/): Implement a single source of truth for “least privilege” workloads across the entire cluster
 * [Resource requests and limits](/docs/concepts/configuration/manage-resources-containers/#requests-and-limits): Apply requests (soft constraint) and limits (hard constraint) for shared resources such as memory and CPU
 * [Audit log analysis](/docs/tasks/debug-application-cluster/audit/): Enable Kubernetes API auditing and filtering for security relevant events
 * [Control plane authentication and certificate root of trust](/docs/concepts/architecture/control-plane-node-communication/): Enable mutual TLS authentication with a trusted CA for communication within the cluster
diff --git a/content/en/blog/_posts/2021-04-06-PodSecurityPolicy-Past-Present-and-Future.md b/content/en/blog/_posts/2021-04-06-PodSecurityPolicy-Past-Present-and-Future.md
@@ -21,7 +21,7 @@ Until then, PSP is still PSP. There will be at least a year during which the new
 
 ## What is PodSecurityPolicy?
 
-[PodSecurityPolicy](/docs/concepts/policy/pod-security-policy/) is a built-in [admission controller](/blog/2019/03/21/a-guide-to-kubernetes-admission-controllers/) that allows a cluster administrator to control security-sensitive aspects of the Pod specification. 
+[PodSecurityPolicy](/docs/concepts/security/pod-security-policy/) is a built-in [admission controller](/blog/2019/03/21/a-guide-to-kubernetes-admission-controllers/) that allows a cluster administrator to control security-sensitive aspects of the Pod specification. 
 
 First, one or more PodSecurityPolicy resources are created in a cluster to define the requirements Pods must meet. Then, RBAC rules are created to control which PodSecurityPolicy applies to a given pod. If a pod meets the requirements of its PSP, it will be admitted to the cluster as usual. In some cases, PSP can also modify Pod fields, effectively creating new defaults for those fields. If a Pod does not meet the PSP requirements, it is rejected, and cannot run. 
 
diff --git a/content/en/blog/_posts/2021-10-05-nsa-cisa-hardening.md b/content/en/blog/_posts/2021-10-05-nsa-cisa-hardening.md
@@ -175,7 +175,7 @@ require internet access to update the vulnerability database.
 
 ### Pod Security Policies
 
-Since Kubernetes v1.21, the [PodSecurityPolicy](/docs/concepts/policy/pod-security-policy/) 
+Since Kubernetes v1.21, the [PodSecurityPolicy](/docs/concepts/security/pod-security-policy/) 
 API and related features are [deprecated](/blog/2021/04/06/podsecuritypolicy-deprecation-past-present-and-future/),
 but some of the guidance in this section will still apply for the next few years, until cluster operators
 upgrade their clusters to newer Kubernetes versions.
diff --git a/content/en/blog/_posts/2021-11-09-non-root-containers-and-devices.md b/content/en/blog/_posts/2021-11-09-non-root-containers-and-devices.md
@@ -18,7 +18,7 @@ One of the key security principles for running containers in Kubernetes is the
 principle of least privilege. The Pod/container `securityContext` specifies the config
 options to set, e.g., Linux capabilities, MAC policies, and user/group ID values to achieve this.
 
-Furthermore, the cluster admins are supported with tools like [PodSecurityPolicy](/docs/concepts/policy/pod-security-policy/) (deprecated) or
+Furthermore, the cluster admins are supported with tools like [PodSecurityPolicy](/docs/concepts/security/pod-security-policy/) (deprecated) or
 [Pod Security Admission](/docs/concepts/security/pod-security-admission/) (alpha) to enforce the desired security settings for pods that are being deployed in
 the cluster. These settings could, for instance, require that containers must be `runAsNonRoot` or
 that they are forbidden from running with root's group ID in `runAsGroup` or `supplementalGroups`.
diff --git a/content/en/blog/_posts/2021-12-09-pod-security-admission-beta.md b/content/en/blog/_posts/2021-12-09-pod-security-admission-beta.md
@@ -9,7 +9,7 @@ slug: pod-security-admission-beta
 
 With the release of Kubernetes v1.23, [Pod Security admission](/docs/concepts/security/pod-security-admission/) has now entered beta. Pod Security is a [built-in](/docs/reference/access-authn-authz/admission-controllers/) admission controller that evaluates pod specifications against a predefined set of [Pod Security Standards](/docs/concepts/security/pod-security-standards/) and determines whether to `admit` or `deny` the pod from running.
 
-Pod Security is the successor to [PodSecurityPolicy](/docs/concepts/policy/pod-security-policy/) which was deprecated in the v1.21 release, and will be removed in Kubernetes v1.25. In this article, we cover the key concepts of Pod Security along with how to use it. We hope that cluster administrators and developers alike will use this new mechanism to enforce secure defaults for their workloads.
+Pod Security is the successor to [PodSecurityPolicy](/docs/concepts/security/pod-security-policy/) which was deprecated in the v1.21 release, and will be removed in Kubernetes v1.25. In this article, we cover the key concepts of Pod Security along with how to use it. We hope that cluster administrators and developers alike will use this new mechanism to enforce secure defaults for their workloads.
 
 ## Why Pod Security
 
diff --git a/content/en/docs/concepts/extend-kubernetes/_index.md b/content/en/docs/concepts/extend-kubernetes/_index.md
@@ -46,7 +46,7 @@ Customization approaches can be broadly divided into *configuration*, which only
 
 Flags and configuration files may not always be changeable in a hosted Kubernetes service or a distribution with managed installation. When they are changeable, they are usually only changeable by the cluster administrator. Also, they are subject to change in future Kubernetes versions, and setting them may require restarting processes. For those reasons, they should be used only when there are no other options.
 
-*Built-in Policy APIs*, such as [ResourceQuota](/docs/concepts/policy/resource-quotas/), [PodSecurityPolicies](/docs/concepts/policy/pod-security-policy/), [NetworkPolicy](/docs/concepts/services-networking/network-policies/) and Role-based Access Control ([RBAC](/docs/reference/access-authn-authz/rbac/)), are built-in Kubernetes APIs. APIs are typically used with hosted Kubernetes services and with managed Kubernetes installations. They are declarative and use the same conventions as other Kubernetes resources like pods, so new cluster configuration can be repeatable and be managed the same way as applications. And, where they are stable, they enjoy a [defined support policy](/docs/reference/using-api/deprecation-policy/) like other Kubernetes APIs. For these reasons, they are preferred over *configuration files* and *flags* where suitable.
+*Built-in Policy APIs*, such as [ResourceQuota](/docs/concepts/policy/resource-quotas/), [PodSecurityPolicies](/docs/concepts/security/pod-security-policy/), [NetworkPolicy](/docs/concepts/services-networking/network-policies/) and Role-based Access Control ([RBAC](/docs/reference/access-authn-authz/rbac/)), are built-in Kubernetes APIs. APIs are typically used with hosted Kubernetes services and with managed Kubernetes installations. They are declarative and use the same conventions as other Kubernetes resources like pods, so new cluster configuration can be repeatable and be managed the same way as applications. And, where they are stable, they enjoy a [defined support policy](/docs/reference/using-api/deprecation-policy/) like other Kubernetes APIs. For these reasons, they are preferred over *configuration files* and *flags* where suitable.
 
 ## Extensions
 
diff --git a/content/en/docs/concepts/security/pod-security-admission.md b/content/en/docs/concepts/security/pod-security-admission.md
@@ -21,7 +21,7 @@ behavior of pods in a clear, consistent fashion.
 
 As a Beta feature, Kubernetes offers a built-in _Pod Security_ {{< glossary_tooltip
 text="admission controller" term_id="admission-controller" >}}, the successor
-to [PodSecurityPolicies](/docs/concepts/policy/pod-security-policy/). Pod security restrictions
+to [PodSecurityPolicies](/docs/concepts/security/pod-security-policy/). Pod security restrictions
 are applied at the {{< glossary_tooltip text="namespace" term_id="namespace" >}} level when pods
 are created.
 
diff --git a/content/en/docs/concepts/security/pod-security-policy.md b/content/en/docs/concepts/security/pod-security-policy.md
diff --git a/content/en/docs/concepts/security/pod-security-standards.md b/content/en/docs/concepts/security/pod-security-standards.md
@@ -452,7 +452,7 @@ of individual policies are not defined here.
 - {{< example file="security/podsecurity-baseline.yaml" >}}Baseline namespace{{< /example >}}
 - {{< example file="security/podsecurity-restricted.yaml" >}}Restricted namespace{{< /example >}}
 
-[**PodSecurityPolicy**](/docs/concepts/policy/pod-security-policy/) (Deprecated)
+[**PodSecurityPolicy**](/docs/concepts/security/pod-security-policy/) (Deprecated)
 
 - {{< example file="policy/privileged-psp.yaml" >}}Privileged{{< /example >}}
 - {{< example file="policy/baseline-psp.yaml" >}}Baseline{{< /example >}}
diff --git a/content/en/docs/concepts/storage/ephemeral-volumes.md b/content/en/docs/concepts/storage/ephemeral-volumes.md
@@ -126,10 +126,10 @@ standardized. See the documentation of each CSI driver for further
 instructions.
 
 ### CSI driver restrictions
- 
+
 {{< feature-state for_k8s_version="v1.21" state="deprecated" >}}
 
-As a cluster administrator, you can use a [PodSecurityPolicy](/docs/concepts/policy/pod-security-policy/) to control which CSI drivers can be used in a Pod, specified with the
+As a cluster administrator, you can use a [PodSecurityPolicy](/docs/concepts/security/pod-security-policy/) to control which CSI drivers can be used in a Pod, specified with the
 [`allowedCSIDrivers` field](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podsecuritypolicyspec-v1beta1-policy).
 
 {{< note >}}
@@ -250,13 +250,12 @@ PVCs indirectly if they can create Pods, even if they do not have
 permission to create PVCs directly. Cluster administrators must be
 aware of this. If this does not fit their security model, they have
 two choices:
-- Use a [Pod Security
-  Policy](/docs/concepts/policy/pod-security-policy/) where the
-  `volumes` list does not contain the `ephemeral` volume type
-  (deprecated in Kubernetes 1.21).
 - Use an [admission webhook](/docs/reference/access-authn-authz/extensible-admission-controllers/)
-  which rejects objects like Pods that have a generic ephemeral
+  that rejects objects like Pods that have a generic ephemeral
   volume.
+- Use a [Pod Security Policy](/docs/concepts/security/pod-security-policy/)
+  where the `volumes` list does not contain the `ephemeral` volume type
+  (deprecated since Kubernetes 1.21).
 
 The normal [namespace quota for PVCs](/docs/concepts/policy/resource-quotas/#storage-resource-quota) still applies, so
 even if users are allowed to use this new mechanism, they cannot use
diff --git a/content/en/docs/concepts/workloads/pods/_index.md b/content/en/docs/concepts/workloads/pods/_index.md
@@ -261,8 +261,7 @@ Within a Pod, containers share an IP address and port space, and
 can find each other via `localhost`. The containers in a Pod can also communicate
 with each other using standard inter-process communications like SystemV semaphores
 or POSIX shared memory.  Containers in different Pods have distinct IP addresses
-and can not communicate by IPC without
-[special configuration](/docs/concepts/policy/pod-security-policy/).
+and can not communicate by OS-level IPC without special configuration.
 Containers that want to interact with a container running in a different Pod can
 use IP networking to communicate.
 
diff --git a/content/en/docs/reference/access-authn-authz/admission-controllers.md b/content/en/docs/reference/access-authn-authz/admission-controllers.md
@@ -716,7 +716,7 @@ for more information.
 This admission controller acts on creation and modification of the pod and determines if it should be admitted
 based on the requested security context and the available Pod Security Policies.
 
-See also [Pod Security Policy documentation](/docs/concepts/policy/pod-security-policy/)
+See also the [PodSecurityPolicy](/docs/concepts/security/pod-security-policy/) documentation
 for more information.
 
 ### PodTolerationRestriction {#podtolerationrestriction}
@@ -777,14 +777,17 @@ for more information.
 
 ### SecurityContextDeny {#securitycontextdeny}
 
-This admission controller will deny any pod that attempts to set certain escalating
+This admission controller will deny any Pod that attempts to set certain escalating
 [SecurityContext](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#securitycontext-v1-core)
 fields, as shown in the
 [Configure a Security Context for a Pod or Container](/docs/tasks/configure-pod-container/security-context/)
 task.
-This should be enabled if a cluster doesn't utilize 
-[pod security policies](/docs/concepts/policy/pod-security-policy/)
-to restrict the set of values a security context can take.
+If you don't use [Pod Security admission]((/docs/concepts/security/pod-security-admission/),
+[PodSecurityPolicies](/docs/concepts/security/pod-security-policy/), nor any external enforcement mechanism,
+then you could use this admission controller to restrict the set of values a security context can take.
+
+See [Pod Security Standards](/docs/concepts/security/pod-security-standards/) for more context on restricting
+pod privileges.
 
 ### ServiceAccount {#serviceaccount}
 
diff --git a/content/en/docs/reference/access-authn-authz/authorization.md b/content/en/docs/reference/access-authn-authz/authorization.md
@@ -76,7 +76,7 @@ DELETE    | delete (for individual resources), deletecollection (for collections
 
 Kubernetes sometimes checks authorization for additional permissions using specialized verbs. For example:
 
-* [PodSecurityPolicy](/docs/concepts/policy/pod-security-policy/)
+* [PodSecurityPolicy](/docs/concepts/security/pod-security-policy/)
   * `use` verb on `podsecuritypolicies` resources in the `policy` API group.
 * [RBAC](/docs/reference/access-authn-authz/rbac/#privilege-escalation-prevention-and-bootstrapping)
   * `bind` and `escalate` verbs on `roles` and `clusterroles` resources in the `rbac.authorization.k8s.io` API group.
diff --git a/content/en/docs/reference/glossary/pod-security-policy.md b/content/en/docs/reference/glossary/pod-security-policy.md
@@ -2,7 +2,7 @@
 title: Pod Security Policy
 id: pod-security-policy
 date: 2018-04-12
-full_link: /docs/concepts/policy/pod-security-policy/
+full_link: /docs/concepts/security/pod-security-policy/
 short_description: >
   Enables fine-grained authorization of pod creation and updates.
 
diff --git a/content/en/docs/setup/production-environment/windows/intro-windows-in-kubernetes.md b/content/en/docs/setup/production-environment/windows/intro-windows-in-kubernetes.md
@@ -696,7 +696,7 @@ operator, you should take both of the following additional measures:
 [RunAsUsername](/docs/tasks/configure-pod-container/configure-runasusername)
 can be specified for Windows Pods or containers to execute the container
 processes as a node-default user. This is roughly equivalent to
-[RunAsUser](/docs/concepts/policy/pod-security-policy/#users-and-groups).
+[RunAsUser](/docs/concepts/security/pod-security-policy/#users-and-groups).
 
 Linux-specific pod security context privileges such as SELinux, AppArmor, Seccomp, or capabilities (POSIX capabilities), and others are not supported.
 
diff --git a/content/en/docs/tasks/administer-cluster/securing-a-cluster.md b/content/en/docs/tasks/administer-cluster/securing-a-cluster.md
@@ -63,7 +63,7 @@ actions a client might want to perform. It is recommended that you use the
 
 As with authentication, simple and broad roles may be appropriate for smaller clusters, but as
 more users interact with the cluster, it may become necessary to separate teams into separate
-namespaces with more limited roles.
+{{< glossary_tooltip text="namespaces" term_id="namespace" >}} with more limited roles.
 
 With authorization, it is important to understand how updates on one object may cause actions in
 other places. For instance, a user may not be able to create pods directly, but allowing them to
@@ -106,15 +106,18 @@ reserved resources like memory, or to provide default limits when none are speci
 A pod definition contains a [security context](/docs/tasks/configure-pod-container/security-context/)
 that allows it to request access to run as a specific Linux user on a node (like root),
 access to run privileged or access the host network, and other controls that would otherwise
-allow it to run unfettered on a hosting node. [Pod security policies](/docs/concepts/policy/pod-security-policy/)
-can limit which users or service accounts can provide dangerous security context settings. For example, pod security policies can limit volume mounts, especially `hostPath`, which are aspects of a pod that should be controlled.
+allow it to run unfettered on a hosting node.
+
+You can configure [Pod security admission](/docs/concepts/security/pod-security-admission/)
+to enforce use of a particular [Pod Security Standard](/docs/concepts/security/pod-security-standards/)
+in a {{< glossary_tooltip text="namespace" term_id="namespace" >}}, or to detect breaches.
 
 Generally, most application workloads need limited access to host resources so they can
 successfully run as a root process (uid 0) without access to host information. However,
 considering the privileges associated with the root user, you should write application
 containers to run as a non-root user. Similarly, administrators who wish to prevent
-client applications from escaping their containers should use a restrictive pod security
-policy.
+client applications from escaping their containers should apply the **Baseline**
+or **Restricted** Pod Security Standard.
 
 
 ### Preventing containers from loading unwanted kernel modules
@@ -238,7 +241,15 @@ restrict the integration to functioning in a single namespace if possible.
 Components that create pods may also be unexpectedly powerful if they can do so inside namespaces
 like the `kube-system` namespace, because those pods can gain access to service account secrets
 or run with elevated permissions if those service accounts are granted access to permissive
-[pod security policies](/docs/concepts/policy/pod-security-policy/).
+[PodSecurityPolicies](/docs/concepts/security/pod-security-policy/).
+
+If you use [Pod Security admission]((/docs/concepts/security/pod-security-admission/) and allow
+any component to create Pods within a namespace that permits privileged Pods, those Pods may
+be able to escape their containers and use this widened access to elevate their privileges.
+
+You should not allow untrusted components to create Pods in any system namespace (those with
+names that start with `kube-`) nor in any namespace where that access grant allows the possibility
+of privilege escalation.
 
 ### Encrypt secrets at rest
 
diff --git a/content/en/docs/tasks/configure-pod-container/security-context.md b/content/en/docs/tasks/configure-pod-container/security-context.md
@@ -487,6 +487,6 @@ kubectl delete pod security-context-demo-4
 * [Tuning Docker with the newest security enhancements](https://github.com/containerd/containerd/blob/main/docs/cri/config.md)
 * [Security Contexts design document](https://git.k8s.io/community/contributors/design-proposals/auth/security_context.md)
 * [Ownership Management design document](https://git.k8s.io/community/contributors/design-proposals/storage/volume-ownership-management.md)
-* [Pod Security Policies](/docs/concepts/policy/pod-security-policy/)
+* [PodSecurityPolicy](/docs/concepts/security/pod-security-policy/)
 * [AllowPrivilegeEscalation design
   document](https://git.k8s.io/community/contributors/design-proposals/auth/no-new-privs.md)
diff --git a/content/en/docs/tasks/configure-pod-container/static-pod.md b/content/en/docs/tasks/configure-pod-container/static-pod.md
@@ -182,8 +182,7 @@ static-web   1/1     Running   0               2m
 ```
 
 {{< note >}}
-Make sure the kubelet has permission to create the mirror Pod in the API server. If not, the creation request is rejected by the API server. See
-[PodSecurityPolicy](/docs/concepts/policy/pod-security-policy/).
+Make sure the kubelet has permission to create the mirror Pod in the API server. If not, the creation request is rejected by the API server. See [Pod Security admission](/docs/concepts/security/pod-security-admission) and [PodSecurityPolicy](/docs/concepts/security/pod-security-policy/).
 {{< /note >}}
 
 {{< glossary_tooltip term_id="label" text="Labels" >}} from the static Pod are
diff --git a/content/en/docs/tutorials/security/apparmor.md b/content/en/docs/tutorials/security/apparmor.md
@@ -350,7 +350,7 @@ node with the required profile.
 
 {{< note >}}
 PodSecurityPolicy is deprecated in Kubernetes v1.21, and will be removed in v1.25.
-See [PodSecurityPolicy documentation](/docs/concepts/policy/pod-security-policy/) for more information.
+See [PodSecurityPolicy](/docs/concepts/security/pod-security-policy/) documentation for more information.
 {{< /note >}}
 
 If the PodSecurityPolicy extension is enabled, cluster-wide AppArmor restrictions can be applied. To
diff --git a/static/_redirects b/static/_redirects
