whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

incorporating initial round of feedback

Browse Source
This commit is contained in:
Samuel Roth
2021-07-13 02:07:24 +00:00
parent 46fe3d043c
commit e0d4b53b1c
12 changed files with 622 additions and 250 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/docs/concepts/security/pod-security-admission.md
+129
View File
@@ -0,0 +1,129 @@
---
reviewers:
- tallclair
- liggitt
title: Pod Security Admission
description: >
An overview of the Pod Security Admission Controller, which can enforce the Pod Security
Standards.
content_type: concept
weight: 20
min-kubernetes-server-version: v1.22
---
<!-- overview -->
{{< feature-state for_k8s_version="v1.22" state="alpha" >}}
The Kubernetes [Pod Security Standards](/docs/concepts/security/pod-security-standards/) define
different isolation levels for Pods. These standards let you define how you want to restrict the
behavior of pods in a clear, consistent fashion.
As an Alpha feature, Kubernetes offers a built-in _Pod Security_ admission plugin, the successor
to [PodSecurityPolicies](/docs/concepts/policy/pod-security-policy/). Pod security restrictions
are applied at the {{< glossary_tooltip text="namespace" term_id="namespace" >}} level when pods
are created.
{{< note >}}
The PodSecurityPolicy API is deprecated and will be
[removed](/docs/reference/using-api/deprecation-guide/#v1-25) from Kubernetes in v1.25.
{{< /note >}}
<!-- body -->
## Enabling the Alpha feature
Setting pod security controls by namespace is an alpha feature. You must enable the `PodSecurity`
[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) in order to use it.
```shell
--feature-gates="...,PodSecurity=true"
```
## Pod Security Admission configuration for pods
Different policy levels (e.g. `baseline`, `restricted`) have different requirements for
[Security Context](/docs/tasks/configure-pod-container/security-context/) objects and other related
fields. Check out the [Pod Security Standards](/docs/concepts/security/pod-security-standards) page
for an in-depth look at those requirements.
## Pod Security Admission labels for namespaces
Provided that you have enabled this feature, you can configure namespaces to define the admission
control mode you want to use for pod security in each namespace. Kubernetes defines a set of
{{< glossary_tooltip term_id="label" text="labels" >}} that you can set to define which of the
predefined Pod Security Standard levels you want to use for a namespace. The label you select
defines what action the {{< glossary_tooltip text="control plane" term_id="control-plane" >}}
takes if a potential violation is detected:
{{< table caption="Pod Security Admission modes" >}}
Mode | Description
:---------|:------------
**`enforce`** | Policy violations will cause the pod to be rejected.
**`audit`** | Policy violations will trigger the addition of an audit annotation, but are otherwise allowed.
**`warn`** | Policy violations will trigger a user-facing warning, but are otherwise allowed.
{{< /table >}}
For each mode, there are two labels that you can use:
```yaml
# The per-mode level label indicates which policy level to apply for the mode.
#
# MODE must be one of `enforce`, `audit`, or `warn`.
# LEVEL must be one of `privileged`, `baseline`, or `restricted`.
pod-security.kubernetes.io/<MODE>: <LEVEL>
# Optional: per-mode version label that can be used to pin the policy to the
# version that shipped with a given Kubernetes minor version (e.g. v{{< skew latestVersion >}}).
#
# MODE must be one of `enforce`, `audit`, or `warn`.
# VERSION must be a valid Kubernetes version label.
pod-security.kubernetes.io/<MODE>-version: <VERSION>
```
Check out [Enforce Pod Security Standards with Namespace Labels](/docs/tasks/configure-pod-container/enforce-standards-namespace-labels) to see example usage.
## Exemptions
You can define _exemptions_ from pod security enforcement in order allow the creation of pods that
would have otherwise been prohibited due to the policy associated with a given namespace.
Exemptions can be statically configured in the
[Admission Controller configuration](#configuring-the-admission-controller).
Exemptions must be explicitly enumerated, and do not support indirection such as label or group
selectors. Requests meeting exemption criteria are _ignored_ by the Admission Controller (all
`enforce`, `audit` and `warn` behaviors), except to record an audit annotation. Exemption
dimensions include:
- **Usernames:** requests from users with an exempt authenticated (or impersonated) username are
ignored.
- **RuntimeClassNames:** pods and templated pods specifying an exempt runtime class name are
ignored.
- **Namespaces:** pods and templated pods in an exempt namespace are ignored.
The username exemption is special in that the creating user is not persisted on the Pod object,
and the Pod may be modified by different non-exempt users in the future. Use cases for username
exemptions include:
- Trusted {{< glossary_tooltip term_id="controller" text="controllers" >}} that create pods.
- Usernames that represent break-glass operations roles, for example for debugging workloads
in a namespace that has restrictions configured. This mechanism only works with a username
match; you cannot grant exemptions based on group membership.
Updates to the following pod fields are exempt from policy checks, meaning that if a pod update request only changes these fields, it will not be denied even if the pod is in violation of the current policy level:
- Any metadata updates EXCEPT changes to the seccomp or apparmor annotations:
- `seccomp.security.alpha.kubernetes.io/pod` (deprecated)
- `container.seccomp.security.alpha.kubernetes.io/*` (deprecated)
- `container.apparmor.security.beta.kubernetes.io/*`
- Valid updates to `.spec.activeDeadlineSeconds`
- Valid updates to `.spec.tolerations`
- Valid updates to Pod resources
## {{% heading "whatsnext" %}}
- [Pod Security Standards](/docs/concepts/security/pod-security-standards)
- [Enforcing Pod Security Standards](/docs/setup/best-practices/enforcing-pod-security-standards)
- [Enforce Pod Security Standards by Configuring the Built-in Admission Controller](/docs/tasks/configure-pod-container/enforce-standards-admission-controller)
- [Enforce Pod Security Standards with Namespace Labels](/docs/tasks/configure-pod-container/enforce-standards-namespace-labels)
- [Migrating from PodSecurityPolicy to PodSecurity](/docs/tasks/secure-pods/migrate-from-psp)
content/en/docs/concepts/security/pod-security-standards.md
+111 -34
View File
@@ -10,7 +10,9 @@ weight: 10
<!-- overview -->
The Pod Security Standards define three different _policies_ to broadly cover the security spectrum. These policies are _cumulative_ and range from highly-permissive to highly-restrictive. This guide outlines the requirements of each policy.
The Pod Security Standards define three different _policies_ to broadly cover the security
spectrum. These policies are _cumulative_ and range from highly-permissive to highly-restrictive.
This guide outlines the requirements of each policy.
| Profile | Description |
| ------ | ----------- |
@@ -24,16 +26,26 @@ The Pod Security Standards define three different _policies_ to broadly cover th
### Privileged
**The _Privileged_ policy is purposely-open, and entirely unrestricted.** This type of policy is typically aimed at system- and infrastructure-level workloads managed by privileged, trusted users.
**The _Privileged_ policy is purposely-open, and entirely unrestricted.** This type of policy is
typically aimed at system- and infrastructure-level workloads managed by privileged, trusted users.
The Privileged policy is defined by an absence of restrictions. For allow-by-default enforcement mechanisms (such as gatekeeper), the Privileged policy may be an absence of applied constraints rather than an instantiated profile. In contrast, for a deny-by-default mechanism (such as Pod Security Policy) the Privileged policy should enable all controls (disable all restrictions).
The Privileged policy is defined by an absence of restrictions. For allow-by-default enforcement
mechanisms (such as gatekeeper), the Privileged policy may be an absence of applied constraints
rather than an instantiated profile. In contrast, for a deny-by-default mechanism (such as Pod
Security Policy) the Privileged policy should enable all controls (disable all restrictions).
### Baseline
**The _Baseline_ policy is aimed at ease of adoption for common containerized workloads while preventing known privilege escalations.** This policy is targeted at application operators and developers of non-critical applications. The following listed controls should be enforced/disallowed:
**The _Baseline_ policy is aimed at ease of adoption for common containerized workloads while
preventing known privilege escalations.** This policy is targeted at application operators and
developers of non-critical applications. The following listed controls should be
enforced/disallowed:
{{< note >}}
In this table, wildcards (`*`) incidate all elements in a list. For example, `spec.containers[*].securityContext` refers to the Security Context object for _all defined containers_. If any of the listed containers fails to meet the requirements, the entire pod will fail validation.
In this table, wildcards (`*`) indicate all elements in a list. For example,
`spec.containers[*].securityContext` refers to the Security Context object for _all defined
containers_. If any of the listed containers fails to meet the requirements, the entire pod will
fail validation.
{{< /note >}}
<table>
@@ -55,6 +67,7 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
</ul>
<p><strong>Allowed Values</strong></p>
<ul>
<li>Undefined/nil</li>
<li><code>false</code></li>
</ul>
</td>
@@ -67,6 +80,7 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
<ul>
<li><code>spec.containers[*].securityContext.privileged</code></li>
<li><code>spec.initContainers[*].securityContext.privileged</code></li>
<li><code>spec.ephemeralContainers[*].securityContext.privileged</code></li>
</ul>
<p><strong>Allowed Values</strong></p>
<ul>
@@ -78,11 +92,12 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
<tr>
<td style="white-space: nowrap">Capabilities</td>
<td>
<p>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.</p>
<p>Adding additional capabilities beyond those listed below must be disallowed.</p>
<p><strong>Restricted Fields</strong></p>
<ul>
<li><code>spec.containers[*].securityContext.capabilities.add</code></li>
<li><code>spec.initContainers[*].securityContext.capabilities.add</code></li>
<li><code>spec.ephemeralContainers[*].securityContext.capabilities.add</code></li>
</ul>
<p><strong>Allowed Values</strong></p>
<ul>
@@ -125,6 +140,7 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
<ul>
<li><code>spec.containers[*].ports[*].hostPort</code></li>
<li><code>spec.initContainers[*].ports[*].hostPort</code></li>
<li><code>spec.ephemeralContainers[*].ports[*].hostPort</code></li>
</ul>
<p><strong>Allowed Values</strong></p>
<ul>
@@ -146,6 +162,7 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
<ul>
<li>Undefined/nil</li>
<li><code>runtime/default</code></li>
<li><code>localhost/*</code></li>
</ul>
</td>
</tr>
@@ -158,10 +175,11 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
<li><code>spec.securityContext.seLinuxOptions.type</code></li>
<li><code>spec.containers[*].securityContext.seLinuxOptions.type</code></li>
<li><code>spec.initContainers[*].securityContext.seLinuxOptions.type</code></li>
<li><code>spec.ephemeralContainers[*].securityContext.seLinuxOptions.type</code></li>
</ul>
<p><strong>Allowed Values</strong></p>
<ul>
<li>Undefined/nil</li>
<li>Undefined/""</li>
<li><code>container_t</code></li>
<li><code>container_init_t</code></li>
<li><code>container_kvm_t</code></li>
@@ -172,13 +190,15 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
<li><code>spec.securityContext.seLinuxOptions.user</code></li>
<li><code>spec.containers[*].securityContext.seLinuxOptions.user</code></li>
<li><code>spec.initContainers[*].securityContext.seLinuxOptions.user</code></li>
<li><code>spec.ephemeralContainers[*].securityContext.seLinuxOptions.user</code></li>
<li><code>spec.securityContext.seLinuxOptions.role</code></li>
<li><code>spec.containers[*].securityContext.seLinuxOptions.role</code></li>
<li><code>spec.initContainers[*].securityContext.seLinuxOptions.role</code></li>
<li><code>spec.ephemeralContainers[*].securityContext.seLinuxOptions.role</code></li>
</ul>
<p><strong>Allowed Values</strong></p>
<ul>
<li>Undefined/nil</li>
<li>Undefined/""</li>
</ul>
</td>
</tr>
@@ -190,6 +210,7 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
<ul>
<li><code>spec.containers[*].securityContext.procMount</code></li>
<li><code>spec.initContainers[*].securityContext.procMount</code></li>
<li><code>spec.ephemeralContainers[*].securityContext.procMount</code></li>
</ul>
<p><strong>Allowed Values</strong></p>
<ul>
@@ -207,14 +228,14 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
<li><code>spec.securityContext.seccompProfile.type</code></li>
<li><code>spec.containers[*].securityContext.seccompProfile.type</code></li>
<li><code>spec.initContainers[*].securityContext.seccompProfile.type</code></li>
<li><code>spec.ephemeralContainers[*].securityContext.seccompProfile.type</code></li>
</ul>
<p><strong>Allowed Values</strong></p>
<ul>
<li>Undefined/nil</li>
<li><code>RuntimeDefault</code></li>
<li><code>Localhost</code>*</li>
<li><code>Localhost</code></li>
</ul>
<small>* must also set <code>securityContext.SeccompProfile.localhostProfile</code></small>
</td>
</tr>
<tr>
@@ -223,7 +244,7 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
<p>Sysctls can disable security mechanisms or affect all containers on a host, and should be disallowed except for an allowed "safe" subset. A sysctl is considered safe if it is namespaced in the container or the Pod, and it is isolated from other Pods or processes on the same Node.</p>
<p><strong>Restricted Fields</strong></p>
<ul>
<li><code>spec.securityContext.sysctls</code></li>
<li><code>spec.securityContext.sysctls[*].name</code></li>
</ul>
<p><strong>Allowed Values</strong></p>
<ul>
@@ -241,10 +262,16 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
### Restricted
**The _Restricted_ policy is aimed at enforcing current Pod hardening best practices, at the expense ofsome compatibility.** It is targeted at operators and developers of security-critical applications, as well as lower-trust users. The following listed controls should be enforced/disallowed:
**The _Restricted_ policy is aimed at enforcing current Pod hardening best practices, at the
expense of some compatibility.** It is targeted at operators and developers of security-critical
applications, as well as lower-trust users. The following listed controls should be
enforced/disallowed:
{{< note >}}
In this table, wildcards (`*`) incidate all elements in a list. For example, `spec.containers[*].securityContext` refers to the Security Context object for _all defined containers_. If any of the listed containers fails to meet the requirements, the entire pod will fail validation.
In this table, wildcards (`*`) indicate all elements in a list. For example,
`spec.containers[*].securityContext` refers to the Security Context object for _all defined
containers_. If any of the listed containers fails to meet the requirements, the entire pod will
fail validation.
{{< /note >}}
<table>
@@ -283,7 +310,7 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
<li><code>spec.volumes[*].portworxVolume</code></li>
<li><code>spec.volumes[*].scaleIO</code></li>
<li><code>spec.volumes[*].storageos</code></li>
<li><code>spec.volumes[*].csi</code></li>
<li><code>spec.volumes[*].photonPersistentDisk</code></li>
</ul>
<p><strong>Allowed Values</strong></p>
<ul>
@@ -292,13 +319,14 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
</td>
</tr>
<tr>
<td style="white-space: nowrap">Privilege Escalation</td>
<td style="white-space: nowrap">Privilege Escalation (v1.8+)</td>
<td>
<p>Privilege escalation (such as via set-user-ID or set-group-ID file mode) should not be allowed.</p>
<p><strong>Restricted Fields</strong></p>
<ul>
<li><code>spec.containers[*].securityContext.allowPrivilegeEscalation</code></li>
<li><code>spec.initContainers[*].securityContext.allowPrivilegeEscalation</code></li>
<li><code>spec.ephemeralContainers[*].securityContext.allowPrivilegeEscalation</code></li>
</ul>
<p><strong>Allowed Values</strong></p>
<ul>
@@ -315,11 +343,16 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
<li><code>spec.securityContext.runAsNonRoot</code></li>
<li><code>spec.containers[*].securityContext.runAsNonRoot</code></li>
<li><code>spec.initContainers[*].securityContext.runAsNonRoot</code></li>
<li><code>spec.ephemeralContainers[*].securityContext.runAsNonRoot</code></li>
</ul>
<p><strong>Allowed Values</strong></p>
<ul>
<li><code>true</code></li>
</ul>
<small>
The container fields may be undefined/<code>nil</code> if the pod-level
<code>spec.securityContext.runAsNonRoot</code> is set to <code>true</code>.
</small>
</td>
</tr>
<tr>
@@ -333,6 +366,7 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
<li><code>spec.securityContext.fsGroup</code></li>
<li><code>spec.containers[*].securityContext.runAsGroup</code></li>
<li><code>spec.initContainers[*].securityContext.runAsGroup</code></li>
<li><code>spec.ephemeralContainers[*].securityContext.runAsGroup</code></li>
</ul>
<p><strong>Allowed Values</strong></p>
<ul>
@@ -342,7 +376,7 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
</td>
</tr>
<tr>
<td>Seccomp</td>
<td style="white-space: nowrap">Seccomp (v1.19+)</td>
<td>
<p>Seccomp profile must be explicitly set to one of the allowed values. Both the <code>Unconfined</code> profile and the <em>absence</em> of a profile are prohibited.</p>
<p><strong>Restricted Fields</strong></p>
@@ -350,15 +384,52 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
<li><code>spec.securityContext.seccompProfile.type</code></li>
<li><code>spec.containers[*].securityContext.seccompProfile.type</code></li>
<li><code>spec.initContainers[*].securityContext.seccompProfile.type</code></li>
<li><code>spec.ephemeralContainers[*].securityContext.seccompProfile.type</code></li>
</ul>
<p><strong>Allowed Values</strong></p>
<ul>
<li><code>RuntimeDefault</code></li>
<li><code>Localhost</code>*</li>
<li><code>Localhost</code></li>
</ul>
<small>* must also set <code>securityContext.SeccompProfile.localhostProfile</code></small>
<small>
The container fields may be undefined/<code>nil</code> if the pod-level
<code>spec.securityContext.seccompProfile.type</code> field is set appropriately.
Conversely, the pod-level field may be undefined/<code>nil</code> if _all_ container-
level fields are set.
</small>
</td>
</tr>
<tr>
<td style="white-space: nowrap">Capabilities (v1.22+)</td>
<td>
<p>
Containers must drop <code>ALL</code> capabilities, and are only permitted to add back
the <code>NET_BIND_SERVICE</code> capability.
</p>
<p><strong>Restricted Fields</strong></p>
<ul>
<li><code>spec.containers[*].securityContext.capabilities.drop</code></li>
<li><code>spec.initContainers[*].securityContext.capabilities.drop</code></li>
<li><code>spec.ephemeralContainers[*].securityContext.capabilities.drop</code></li>
</ul>
<p><strong>Allowed Values</strong></p>
<ul>
<li>Any list of capabilities that includes <code>ALL</code></li>
</ul>
<hr />
<p><strong>Restricted Fields</strong></p>
<ul>
<li><code>spec.containers[*].securityContext.capabilities.add</code></li>
<li><code>spec.initContainers[*].securityContext.capabilities.add</code></li>
<li><code>spec.ephemeralContainers[*].securityContext.capabilities.add</code></li>
</ul>
<p><strong>Allowed Values</strong></p>
<ul>
<li>Undefined/nil</li>
<li><code>NET_BIND_SERVICE</code></li>
</ul>
</td>
</tr>
</tbody>
</table>
@@ -371,44 +442,50 @@ mechanism.
As mechanisms mature, they will be defined below on a per-policy basis. The methods of enforcement
of individual policies are not defined here.
[**PodSecurityPolicy**](/docs/concepts/profile/pod-security-profile/)
[**Pod Security Admission Controller**](/docs/concepts/security/pod-security-admission/)
- {{< example file="profile/privileged-psp.yaml" >}}Privileged{{< /example >}}
- {{< example file="profile/baseline-psp.yaml" >}}Baseline{{< /example >}}
- {{< example file="profile/restricted-psp.yaml" >}}Restricted{{< /example >}}
- {{< example file="security/podsecurity-privileged.yaml" >}}Privileged namespace{{< /example >}}
- {{< example file="security/podsecurity-baseline.yaml" >}}Baseline namespace{{< /example >}}
- {{< example file="security/podsecurity-restricted.yaml" >}}Restricted namespace{{< /example >}}
[**PodSecurityPolicy**](/docs/concepts/profile/pod-security-profile/) (Deprecated)
- {{< example file="policy/privileged-psp.yaml" >}}Privileged{{< /example >}}
- {{< example file="policy/baseline-psp.yaml" >}}Baseline{{< /example >}}
- {{< example file="policy/restricted-psp.yaml" >}}Restricted{{< /example >}}
## FAQ
### Why isn't there a policy between privileged and baseline?
### Why isn't there a profile between privileged and baseline?
The three profiles defined here have a clear linear progression from most secure (restricted) to least
secure (privileged), and cover a broad set of workloads. Privileges required above the baseline
policy are typically very application specific, so we do not offer a standard policy in this
niche. This is not to say that the privileged policy should always be used in this case, but that
policy are typically very application specific, so we do not offer a standard profile in this
niche. This is not to say that the privileged profile should always be used in this case, but that
policies in this space need to be defined on a case-by-case basis.
SIG Auth may reconsider this position in the future, should a clear need for other profiles arise.
### What's the difference between a security policy and a security context?
### What's the difference between a security profile and a security context?
[Security Contexts](/docs/tasks/configure-pod-container/security-context/) configure Pods and
Containers at runtime. Security contexts are defined as part of the Pod and container specifications
in the Pod manifest, and represent parameters to the container runtime.
Security policies are control plane mechanisms to enforce specific settings in the Security Context,
as well as other parameters outside the Security Context. As of February 2020, the current native
solution for enforcing these security policies is [Pod Security
Policy](/docs/concepts/profile/pod-security-profile/) - a mechanism for centrally enforcing security
profile on Pods across a cluster. Other alternatives for enforcing security profile are being
developed in the Kubernetes ecosystem, such as [OPA
Gatekeeper](https://github.com/open-profile-agent/gatekeeper).
Security profiles are control plane mechanisms to enforce specific settings in the Security Context,
as well as other related parameters outside the Security Context. As of July 2021,
[Pod Security Policies](/docs/concepts/profile/pod-security-profile/) are deprecated in favor of the
built-in [Pod Security Admission Controller](/docs/concepts/security/pod-security-admission/).
Other alternatives for enforcing security profiles are being developed in the Kubernetes
ecosystem, such as [OPA Gatekeeper](https://github.com/open-profile-agent/gatekeeper).
### What profiles should I apply to my Windows Pods?
Windows in Kubernetes has some limitations and differentiators from standard Linux-based
workloads. Specifically, the Pod SecurityContext fields [have no effect on
Windows](/docs/setup/production-environment/windows/intro-windows-in-kubernetes/#v1-podsecuritycontext). As
such, no standardized Pod Security profiles currently exists.
such, no standardized Pod Security profiles currently exist.
### What about sandboxed Pods?
content/en/docs/concepts/security/securing-pods.md
-216
View File
@@ -1,216 +0,0 @@
---
reviewers:
- tallclair
title: Securing Pods with the Pod Security Standards
content_type: concept
weight: 20
---
<!-- overview -->
{{< feature-state for_k8s_version="v1.22" state="alpha" >}}
Pod Security Standards enable cluster operators to restrict the permissions of pods in a clear, consistent fashion. They are the successor to [Pod Security Policies](/docs/concepts/policy/pod-security-policy), which will be removed from Kubernetes in v1.25.
<!-- body -->
## Getting Started
### Enabling the Alpha feature
Pod Security Standards are currently in Alpha and behind a [Feature Gate](/docs/reference/command-line-tools-reference/feature-gates/). This means they must be explicitly enabled before they can be used.
```shell
--feature-gates="...,PodSecurity=true"
```
### Configuring Namespaces
Once the feature is enabled, policies can then specified by adding labels to namespaces. These labels correspond to different _modes_, which determine how the admission controller will respond to violating pods.
| Mode | Description |
| ---- | ----------- |
| **`enforce`** | Policy violations will cause the pod to be rejected. |
| **`audit`** | Policy violations will trigger the addition of an audit annotation, but are otherwise allowed. |
| **`warn`** | Policy violations will trigger a user-facing warning, but are otherwise allowed. |
For each mode, there are two labels:
```yaml
# The per-mode level label indicates which policy level to apply for the mode.
#
# MODE must be one of `enforce`, `audit`, or `warn`.
# LEVEL must be one of `privileged`, `baseline`, or `restricted`.
pod-security.kubernetes.io/<MODE>: <LEVEL>
# Optional: per-mode version label that can be used to pin the policy to the
# version that shipped with a given Kubernetes minor version (e.g. v1.22).
#
# MODE must be one of `enforce`, `audit`, or `warn`.
# VERSION must be a valid Kubernetes version label.
pod-security.kubernetes.io/<MODE>-version: <VERSION>
```
Check out the [examples](/docs/concepts/security/securing-pods/#examples) to see example usage of these labels.
#### Configuring the Admission Controller
The PodSecurity Admission Controller can be statically configured to set defaults and [exemptions](/docs/concepts/security/securing-pods/#exemptions).
```yaml
apiVersion: apiserver.config.k8s.io/v1
kind: AdmissionConfiguration
plugins:
- name: PodSecurity
configuration:
defaults: # Defaults applied when a mode label is not set.
enforce: <default enforce policy level>
enforce-version: <default enforce policy version>
audit: <default audit policy level>
audit-version: <default audit policy version>
warn: <default warn policy level>
warn-version: <default warn policy version>
exemptions:
usernames: [ <array of authenticated usernames to exempt> ]
runtimeClassNames: [ <array of runtime class names to exempt> ]
namespaces: [ <array of namespaces to exempt> ]
```
#### Configuring Pods
Different policy levels (e.g. `baseline`, `restricted`) have different requirements for [Security Context](/docs/tasks/configure-pod-container/security-context/) objects and other related fields. Check out the [Pod Security Standards](/docs/concepts/security/pod-security-standards) page for an in-depth look at those requirements.
## Exemptions
Exemptions permit the creation of pods that would have otherwise been prohibited due to the policy associated with a given namespace. Exemptions can be statically configured in the [Admission Controller configuration](/docs/concepts/security/securing-pods/#configuring-the-admission-controller).
Exemptions must be explicitly enumerated, and do not support indirection such as label or group selectors. Requests meeting exemption criteria are _ignored_ by the Admission Controller (all `enforce`, `audit` and `warn` behaviors), except to record an audit annotation. Exemption dimensions include:
- **Usernames:** requests from users with an exempt authenticated (or impersonated) username are ignored.
- **RuntimeClassNames:** pods and templated pods specifying an exempt runtime class name are ignored.
- **Namespaces:** pods and templated pods in an exempt namespace are ignored.
The username exemption is special in that the creating user is not persisted on the Pod object, and the Pod may be modified by different non-exempt users in the future. See the [Updates section of the Pod Security Standards KEP](https://github.com/kubernetes/enhancements/tree/master/keps/sig-auth/2579-psp-replacement#updates) for details on how non-exempt updates of a previously exempted pod are handled. Use cases for username exemptions include:
- Trusted controllers that create pods in tenant namespaces with additional 3rd party enforcement on the privileged pods.
- Break-glass operations roles, for example for debugging workloads in a restricted namespace.
## Webhook
To enable policy enforcement on older clusters, we provide a standalone webhook implementation that utilizes the same underlying library.
TODO: Update this as instructions for setting up webhook become more clear. [See related issue.](https://github.com/kubernetes/kubernetes/issues/103559)
## Best Practices
### Configure All Cluster Namespaces
Even if the initial configurations are most permissive (i.e. everything is `privileged`), any Namespaces that lack any configuration at all will become significant gaps in your cluster security model.
We provide an [example](/docs/concepts/security/securing-pods/#applying-to-all-namespaces) that illustrates how you can do this.
### Enforce the Principle of Least Privilege
In an ideal world, every pod in every namespace would meet the requirements of the `restricted` policy. However, this is not possible nor practical, as some workloads will require elevated privileges for legitimate reasons.
- Namespaces allowing `privileged` workloads should establish and enforce appropriate access controls.
- For workloads running in those permissive namespaces, maintain documentation about their unique security requirements. If at all possible, consider how those requirements could be further constrained.
### Adopt a Multi-Mode Strategy
The `audit` and `warn` modes of the Pod Security Standards admission controller make it easy to collect important security insights about your pods without breaking existing workloads.
It is good practice to enable these modes for all namespaces, except maybe for those that will _absolutely_ always require `privileged` access or those that enforce the `restricted` policy. Further, these modes should usually be set to policies at least one level higher than the policy for the `enforce` mode.
- Namespaces enforcing the `privileged` policy (i.e. no restrictions) should set audit and warn labels to `baseline`.
- Namespaces enforcing the `baseline` policy should set audit and warn labels to `restricted`.
Monitoring these annotations and warnings over time will help you identify workloads that can be migrated to namespaces with stricter policies.
## Examples
### Adding Labels in YAML
This YAML file creates a Namespace `my-secure-namespace` that:
- Blocks any pods that don't satisfy the `baseline` policy requirements.
- Generates a user-facing warning and adds an audit annotation to any created pod that does not meet the `restricted` policy requirements.
- Pins the versions of the `baseline` and `restricted` policies to v1.22.
```yaml
apiVersion: v1
kind: Namespace
metadata:
name: my-secure-namespace
labels:
pod-security.kubernetes.io/enforce: baseline
pod-security.kubernetes.io/enforce-version: v1.22
pod-security.kubernetes.io/audit: restricted
pod-security.kubernetes.io/audit-version: v1.22
pod-security.kubernetes.io/warn: restricted
pod-security.kubernetes.io/warn-version: v1.22
```
### Adding Labels to Existing Namespaces with `kubectl label`
{{< note >}}
When an `enforce` policy (or version) label is added or changed, the admission plugin will test each pod in the namespace against the new policy. Violations are returned to the user as warnings.
{{< /note >}}
#### Applying to All Namespaces
If you're just getting started with the Pod Security Standards, a suitable first step would be to configure all namespaces as `privileged` but set up audit annotations for a stricter level such as `baseline`:
```shell
kubectl label --overwrite ns --all \
pod-security.kubernetes.io/enforce=privileged \
pod-security.kubernetes.io/audit=baseline \
pod-security.kubernetes.io/warn=baseline
```
#### Applying to a Single Namespace
You can update a specific namespace as well. This command adds the `enforce=restricted` policy to `my-existing-namespace`, pinning the restricted policy version to v1.22.
```shell
kubectl label --overwrite ns my-existing-namespace \
pod-security.kubernetes.io/enforce=restricted \
pod-security.kubernetes.io/enforce-version=v1.22
```
## Migrating from Pod Security Policies
Migrating to the replacement policy from PodSecurityPolicies can be done effectively using a combination of dry-run and `audit` and `warn` modes, although this becomes harder if mutating PSPs are used).
{{< note >}}
**We are working on tooling to automate this migration.** In the meantime, this guide should give you an idea of the general process.
{{< /note >}}
- [Enable the Pod Security Standards feature gate.](/docs/concepts/security/securing-pods#enabling-the-alpha-feature)
- **Temporarily set the default `enforce` mode to `privileged` for all Namespaces.** This can be done by [configuring the Admission Controller](/docs/concepts/security/securing-pods#configuring-the-admission-controller) or with [`kubectl label`](/docs/concepts/security/securing-pods#applying-to-all-namespaces).
- **Eliminate mutating Pod Security Policies, if your cluster has any set up.**
- Clone all mutating PSPs into a non-mutating version.
- Update all ClusterRoles authorizing use of those mutating PSPs to also authorize use of the non-mutating variant.
- Watch for Pods using the mutating PSPs and work with code owners to migrate to valid, non-mutating resources.
- Delete mutating PSPs.
- **Select a compatible policy level for each namespace.** Analyze existing resources in the namespace to drive this decision; strive for the `restricted` and `baseline` levels.
- Review the requirements of the different [Pod Security Standards](/docs/concepts/security/pod-security-standards).
- Evaluate the difference in privileges that would come from disabling the PSP controller.
- **Apply the selected profiles in `warn` and `audit` mode.** This will give you an idea of how your Pods will respond to the new policies, without breaking existing workloads. Iterate on your [Pods' configuration](/docs/concepts/security/securing-pods#configuring-pods) until they are in compliance with the selected profiles.
- Apply the profiles in enforce mode.
- Disable PodSecurityPolicy!
## FAQ
### Why were the Pod Security Policies deprecated?
There were numerous problems with Pod Security Policies, which led to the decision to deprecate them. The [KEP for Pod Security Standards](https://github.com/kubernetes/enhancements/tree/master/keps/sig-auth/2579-psp-replacement#motivation) goes into these issues in more detail.
### When should I pin a policy version?
The Pod Security Standards will continue to evolve over time, even after the feature leaves the Alpha phase. This is because the details of the policies are based on current Pod hardening best practices, which must adapt to new threats as they arise.
**Pinning policies to specific versions will prevent you from detecting and enforcing protections against future threats.** _Only_ consider pinning versions if the default value `latest` would result in your workloads drifting toward less-restrictive configurations in ways that cannot be resolved.
If you find yourself in that situation, consider refactoring workloads to isolate privileged operations as much as possible.