incorporating initial round of feedback

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
@@ -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)
@@ -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?
@@ -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.
@@ -696,6 +696,18 @@ PodNodeSelector allows forcing pods to run on specifically labeled nodes. Also s
admission plugin, which allows preventing pods from running on specifically tainted nodes.
{{< /note >}}
### PodSecurity {#podsecurity}
{{< feature-state for_k8s_version="v1.22" state="alpha" >}}
This is the replacement for the deprecated [PodSecurityPolicy](#podsecuritypolicy) admission controller
defined in the next section. 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
[Pod Security Standards](/docs/concepts/security/pod-security-standards/).
See the [Pod Security Admission documentation](/docs/concepts/security/pod-security-admission/)
for more information.
### PodSecurityPolicy {#podsecuritypolicy}
{{< feature-state for_k8s_version="v1.21" state="deprecated" >}}
@@ -323,3 +323,87 @@ Sets this taint on a node to mark it as unusable, when kubelet is started with t
Example: `node.cloudprovider.kubernetes.io/shutdown:NoSchedule`
If a Node is in a cloud provider specified shutdown state, the Node gets tainted accordingly with `node.cloudprovider.kubernetes.io/shutdown` and the taint effect of `NoSchedule`.
## pod-security.kubernetes.io/enforce
Example: `pod-security.kubernetes.io/enforce: baseline`
Used on: Namespace
Value **must** be one of `privileged`, `baseline`, or `restricted` which correspond to
[Pod Security Standard](/docs/concepts/security/pod-security-standards) levels. Specifically,
the `enforce` label _prohibits_ the creation of any Pod in the labeled Namespace which does not meet
the requirements outlined in the indicated level.
See [Enforcing Pod Security at the Namespace Level](/docs/concepts/security/pod-security-admission)
for more information.
## pod-security.kubernetes.io/enforce-version
Example: `pod-security.kubernetes.io/enforce-version: {{< skew latestVersion >}}`
Used on: Namespace
Value **must** be `latest` or a valid Kubernetes version in the format `v<MAJOR>.<MINOR>`.
This determines the version of the [Pod Security Standard](/docs/concepts/security/pod-security-standards)
policies to apply when validating a submitted Pod.
See [Enforcing Pod Security at the Namespace Level](/docs/concepts/security/pod-security-admission)
for more information.
## pod-security.kubernetes.io/audit
Example: `pod-security.kubernetes.io/audit: baseline`
Used on: Namespace
Value **must** be one of `privileged`, `baseline`, or `restricted` which correspond to
[Pod Security Standard](/docs/concepts/security/pod-security-standards) levels. Specifically,
the `audit` label does not prevent the creation of a Pod in the labeled Namespace which does not meet
the requirements outlined in the indicated level, but adds an audit annotation to that Pod.
See [Enforcing Pod Security at the Namespace Level](/docs/concepts/security/pod-security-admission)
for more information.
## pod-security.kubernetes.io/audit-version
Example: `pod-security.kubernetes.io/audit-version: {{< skew latestVersion >}}`
Used on: Namespace
Value **must** be `latest` or a valid Kubernetes version in the format `v<MAJOR>.<MINOR>`.
This determines the version of the [Pod Security Standard](/docs/concepts/security/pod-security-standards)
policies to apply when validating a submitted Pod.
See [Enforcing Pod Security at the Namespace Level](/docs/concepts/security/pod-security-admission)
for more information.
## pod-security.kubernetes.io/warn
Example: `pod-security.kubernetes.io/warn: baseline`
Used on: Namespace
Value **must** be one of `privileged`, `baseline`, or `restricted` which correspond to
[Pod Security Standard](/docs/concepts/security/pod-security-standards) levels. Specifically,
the `warn` label does not prevent the creation of a Pod in the labeled Namespace which does not meet the
requirements outlined in the indicated level, but returns a warning to the user after doing so.
Note that warnings are also displayed when creating or updating objects that contain Pod templates,
such as Deployments, Jobs, StatefulSets, etc.
See [Enforcing Pod Security at the Namespace Level](/docs/concepts/security/pod-security-admission)
for more information.
## pod-security.kubernetes.io/warn-version
Example: `pod-security.kubernetes.io/warn-version: {{< skew latestVersion >}}`
Used on: Namespace
Value **must** be `latest` or a valid Kubernetes version in the format `v<MAJOR>.<MINOR>`.
This determines the version of the [Pod Security Standard](/docs/concepts/security/pod-security-standards)
policies to apply when validating a submitted Pod. Note that warnings are also displayed when creating
or updating objects that contain Pod templates, such as Deployments, Jobs, StatefulSets, etc.
See [Enforcing Pod Security at the Namespace Level](/docs/concepts/security/pod-security-admission)
for more information.
@@ -0,0 +1,78 @@
---
reviewers:
- tallclair
- liggitt
title: Enforcing Pod Security Standards
weight: 40
---
<!-- overview -->
This page provides an overview of best practices when it comes to enforcing
[Pod Security Standards](/docs/concepts/security/pod-security-standards).
<!-- body -->
## Using the built-in Pod Security Admission Controller
{{< feature-state for_k8s_version="v1.22" state="alpha" >}}
The [Pod Security Admission Controller](/docs/reference/access-authn-authz/admission-controllers/#podsecurity)
intends to replace the deprecated PodSecurityPolicies.
### Configure all cluster namespaces
Namespaces that lack any configuration at all should be considered significant gaps in your cluster
security model. We recommend taking the time to analyze the types of workloads occurring in each
namespace, and by referencing the Pod Security Standards, decide on an appropriate level for
each of them. Unlabeled namespaces should only indicate that they've yet to be evaluated.
In the scenario that all workloads in all namespaces have the same security requirements,
we provide an [example](/docs/concepts/security/pod-security-admission/#applying-to-all-namespaces)
that illustrates how the PodSecurity labels can be applied in bulk.
### Embrace 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, setting them to the _desired_ level
and version you would eventually like to `enforce`. The warnings and audit annotations generated in
this phase can guide you toward that state. If you expect workload authors to make changes to fit
within the desired level, enable the `warn` mode. If you expect to use audit logs to monitor/drive
changes to fit within the desired level, enable the `audit` mode.
When you have the `enforce` mode set to your desired value, these modes can still be useful in a
few different ways:
- By setting `warn` to the same level as `enforce`, clients will receive warnings when attempting
to create Pods (or resources that have Pod templates) that do not pass validation. This will help
them update those resources to become compliant.
- In Namespaces that pin `enforce` to a specific non-latest version, setting the `audit` and `warn`
modes to the same level as `enforce`, but to the `latest` version, gives visibility into settings
that were allowed by previous versions but are not allowed per current best practices.
## Third-party alternatives
{{% thirdparty-content %}}
Other alternatives for enforcing security profiles are being developed in the Kubernetes
ecosystem:
- [OPA Gatekeeper](https://github.com/open-policy-agent/gatekeeper).
The decision to go with a _built-in_ solution (e.g. PodSecurity admission controller) versus a
third-party tool is entirely dependent on your own situation. When evaluating any solution,
trust of your supply chain is crucial. Ultimately, using _any_ of the aforementioned approaches
will be better than doing nothing.
@@ -0,0 +1,54 @@
---
title: Enforce Pod Security Standards by Configuring the Built-in Admission Controller
reviewers:
- tallclair
- liggitt
content_type: task
min-kubernetes-server-version: v1.22
---
As of v1.22, Kubernetes provides a built-in [admission controller](/docs/reference/access-authn-authz/admission-controllers/#podsecurity)
to enforce the [Pod Security Standards](/docs/concepts/security/pod-security-standards).
You can configure this admission controller to set cluster-wide defaults and [exemptions](#exemptions).
## {{% heading "prerequisites" %}}
{{% version-check %}}
- Enable the `PodSecurity` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/#feature-gates-for-alpha-or-beta-features).
## Configure the Admission Controller
```yaml
apiVersion: apiserver.config.k8s.io/v1
kind: AdmissionConfiguration
plugins:
- name: PodSecurity
configuration:
apiVersion: pod-security.admission.config.k8s.io/v1alpha1
kind: PodSecurityConfiguration
# Defaults applied when a mode label is not set.
#
# Level label values must be one of:
# - "privileged" (default)
# - "baseline"
# - "restricted"
#
# Version label values must be one of:
# - "latest" (default)
# - specific version like "v{{< skew latestVersion >}}"
defaults:
enforce: "privileged"
enforce-version: "latest"
audit: "privileged"
audit-version: "latest"
warn: "privileged"
warn-version: "latest"
exemptions:
# Array of authenticated usernames to exempt.
usernames: []
# Array of runtime class names to exempt.
runtimeClassNames: []
# Array of namespaces to exempt.
namespaces: []
```
@@ -0,0 +1,81 @@
---
title: Enforce Pod Security Standards with Namespace Labels
reviewers:
- tallclair
- liggitt
content_type: task
min-kubernetes-server-version: v1.22
---
Namespaces can be labeled to enforce the [Pod Security Standards](/docs/concepts/security/pod-security-standards).
## {{% heading "prerequisites" %}}
{{% version-check %}}
- Enable the `PodSecurity` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/#feature-gates-for-alpha-or-beta-features).
## Requiring the `baseline` Pod Security Standard with namespace labels
This manifest defines a Namespace `my-baseline-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 v{{< skew latestVersion >}}.
```yaml
apiVersion: v1
kind: Namespace
metadata:
name: my-baseline-namespace
labels:
pod-security.kubernetes.io/enforce: baseline
pod-security.kubernetes.io/enforce-version: v{{< skew latestVersion >}}
# We are setting these to our _desired_ `enforce` level.
pod-security.kubernetes.io/audit: restricted
pod-security.kubernetes.io/audit-version: v{{< skew latestVersion >}}
pod-security.kubernetes.io/warn: restricted
pod-security.kubernetes.io/warn-version: v{{< skew latestVersion >}}
```
## Add 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 >}}
It is helpful to apply the `--dry-run` flag when initially evaluating security profile changes for
namespaces. The Pod Security Standard checks will still be run in _dry run_ mode, giving you
information about how the new policy would treat existing pods, without actually updating a policy.
```shell
kubectl label --dry-run=server --overwrite ns --all \
pod-security.kubernetes.io/enforce=baseline
```
### 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 v{{< skew latestVersion >}}.
```shell
kubectl label --overwrite ns my-existing-namespace \
pod-security.kubernetes.io/enforce=restricted \
pod-security.kubernetes.io/enforce-version=v{{< skew latestVersion >}}
```
@@ -0,0 +1,48 @@
---
title: Migrate from PodSecurityPolicy to the Built-In PodSecurity Admission Controller
reviewers:
- tallclair
- liggitt
content_type: task
min-kubernetes-server-version: v1.22
---
<!-- overview -->
This page describes the process of migrating from PodSecurityPolicies to the built-in PodSecurity
admission controller. This can be done effectively using a combination of dry-run and `audit` and
`warn` modes, although this becomes harder if mutating PSPs are used.
## {{% heading "prerequisites" %}}
{{% version-check %}}
- Enable the `PodSecurity` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/#feature-gates-for-alpha-or-beta-features).
<!-- body -->
## Steps
- **Eliminate mutating PodSecurityPolicies, 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.
- 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.
- In the event that a PodSecurityPolicy falls between two levels, consider:
- Selecting a _less_ permissive PodSecurity level prioritizes security, and may require adjusting
workloads to fit within the stricter policy.
- Selecting a _more_ permissive PodSecurity level prioritizes avoiding disrupting or
changing workloads, but may allow workload authors in the namespace greater permissions
than desired.
- **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/pod-security-admission#configuring-pods) until
they are in compliance with the selected profiles.
- Apply the profiles in `enforce` mode.
- Stop including `PodSecurityPolicy` in the `--enable-admission-plugins` flag.
@@ -0,0 +1,9 @@
apiVersion: v1
kind: Namespace
metadata:
name: my-baseline-namespace
labels:
pod-security.kubernetes.io/enforce: baseline
pod-security.kubernetes.io/enforce-version: latest
pod-security.kubernetes.io/warn: baseline
pod-security.kubernetes.io/warn-version: latest
@@ -0,0 +1,7 @@
apiVersion: v1
kind: Namespace
metadata:
name: my-privileged-namespace
labels:
pod-security.kubernetes.io/enforce: privileged
pod-security.kubernetes.io/enforce-version: latest
@@ -0,0 +1,9 @@
apiVersion: v1
kind: Namespace
metadata:
name: my-restricted-namespace
labels:
pod-security.kubernetes.io/enforce: restricted
pod-security.kubernetes.io/enforce-version: latest
pod-security.kubernetes.io/warn: restricted
pod-security.kubernetes.io/warn-version: latest