171 lines
8.2 KiB
Markdown
171 lines
8.2 KiB
Markdown
---
|
|
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.23" state="beta" >}}
|
|
|
|
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 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
|
|
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 `PodSecurity` admission plugin
|
|
|
|
In v1.23, the `PodSecurity` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
|
|
is a Beta feature and is enabled by default.
|
|
|
|
In v1.22, the `PodSecurity` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
|
|
is an Alpha feature and must be enabled in `kube-apiserver` in order to use the built-in admission plugin.
|
|
|
|
```shell
|
|
--feature-gates="...,PodSecurity=true"
|
|
```
|
|
|
|
## Alternative: installing the `PodSecurity` admission webhook {#webhook}
|
|
|
|
For environments where the built-in `PodSecurity` admission plugin cannot be used,
|
|
either because the cluster is older than v1.22, or the `PodSecurity` feature cannot be enabled,
|
|
the `PodSecurity` admission logic is also available as a Beta [validating admission webhook](https://git.k8s.io/pod-security-admission/webhook).
|
|
|
|
A pre-built container image, certificate generation scripts, and example manifests
|
|
are available at [https://git.k8s.io/pod-security-admission/webhook](https://git.k8s.io/pod-security-admission/webhook).
|
|
|
|
To install:
|
|
```shell
|
|
git clone git@github.com:kubernetes/pod-security-admission.git
|
|
cd pod-security-admission/webhook
|
|
make certs
|
|
kubectl apply -k .
|
|
```
|
|
|
|
{{< note >}}
|
|
The generated certificate is valid for 2 years. Before it expires,
|
|
regenerate the certificate or remove the webhook in favor of the built-in admission plugin.
|
|
{{< /note >}}
|
|
|
|
## Pod Security levels
|
|
|
|
Pod Security admission places requirements on a Pod's [Security
|
|
Context](/docs/tasks/configure-pod-container/security-context/) and other related fields according
|
|
to the three levels defined by the [Pod Security
|
|
Standards](/docs/concepts/security/pod-security-standards): `privileged`, `baseline`, and
|
|
`restricted`. Refer to 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
|
|
|
|
Once the feature is enabled or the webhook is installed, 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 to the event recorded in the [audit log](/docs/tasks/debug-application-cluster/audit/), but are otherwise allowed.
|
|
**warn** | Policy violations will trigger a user-facing warning, but are otherwise allowed.
|
|
{{< /table >}}
|
|
|
|
A namespace can configure any or all modes, or even set a different level for different modes.
|
|
|
|
For each mode, there are two labels that determine the policy used:
|
|
|
|
```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 (for example v{{< skew latestVersion >}}).
|
|
#
|
|
# MODE must be one of `enforce`, `audit`, or `warn`.
|
|
# VERSION must be a valid Kubernetes minor version, or `latest`.
|
|
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.
|
|
|
|
## Workload resources and Pod templates
|
|
|
|
Pods are often created indirectly, by creating a [workload
|
|
object](/docs/concepts/workloads/controllers/) such as a {{< glossary_tooltip
|
|
term_id="deployment" >}} or {{< glossary_tooltip term_id="job">}}. The workload object defines a
|
|
_Pod template_ and a {{< glossary_tooltip term_id="controller" text="controller" >}} for the
|
|
workload resource creates Pods based on that template. To help catch violations early, both the
|
|
audit and warning modes are applied to the workload resources. However, enforce mode is **not**
|
|
applied to workload resources, only to the resulting pod objects.
|
|
|
|
## 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](/docs/tasks/configure-pod-container/enforce-standards-admission-controller/#configure-the-admission-controller).
|
|
|
|
Exemptions must be explicitly enumerated. Requests meeting exemption criteria are _ignored_ by the
|
|
Admission Controller (all `enforce`, `audit` and `warn` behaviors are skipped). Exemption dimensions include:
|
|
|
|
- **Usernames:** requests from users with an exempt authenticated (or impersonated) username are
|
|
ignored.
|
|
- **RuntimeClassNames:** pods and [workload resources](#workload-resources-and-pod-templates) specifying an exempt runtime class name are
|
|
ignored.
|
|
- **Namespaces:** pods and [workload resources](#workload-resources-and-pod-templates) in an exempt namespace are ignored.
|
|
|
|
{{< caution >}}
|
|
|
|
Most pods are created by a controller in response to a [workload
|
|
resource](#workload-resources-and-pod-templates), meaning that exempting an end user will only
|
|
exempt them from enforcement when creating pods directly, but not when creating a workload resource.
|
|
Controller service accounts (such as `system:serviceaccount:kube-system:replicaset-controller`)
|
|
should generally not be exempted, as doing so would implicitly exempt any user that can create the
|
|
corresponding workload resource.
|
|
|
|
{{< /caution >}}
|
|
|
|
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`
|
|
|
|
## {{% 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)
|
|
- [Migrate from PodSecurityPolicy to the Built-In PodSecurity Admission Controller](/docs/tasks/configure-pod-container/migrate-from-psp)
|