From 37dd90d81a9f64d3b7204bc66ec524a9bd2a8d95 Mon Sep 17 00:00:00 2001 From: Samuel Roth Date: Sun, 11 Jul 2021 19:40:09 +0000 Subject: [PATCH 1/2] feature: Pod Security Standards documentation --- content/en/docs/concepts/security/overview.md | 4 +- .../security/pod-security-standards.md | 456 +++++++++++------- .../docs/concepts/security/securing-pods.md | 216 +++++++++ 3 files changed, 492 insertions(+), 184 deletions(-) create mode 100644 content/en/docs/concepts/security/securing-pods.md diff --git a/content/en/docs/concepts/security/overview.md b/content/en/docs/concepts/security/overview.md index b23a07c79ab2d..ce75653dfddf9 100644 --- a/content/en/docs/concepts/security/overview.md +++ b/content/en/docs/concepts/security/overview.md @@ -2,8 +2,10 @@ reviewers: - zparnold title: Overview of Cloud Native Security +description: > + A model for thinking about Kubernetes security in the context of Cloud Native security. content_type: concept -weight: 10 +weight: 1 --- diff --git a/content/en/docs/concepts/security/pod-security-standards.md b/content/en/docs/concepts/security/pod-security-standards.md index 5a69cc8e6405c..944eb984f1616 100644 --- a/content/en/docs/concepts/security/pod-security-standards.md +++ b/content/en/docs/concepts/security/pod-security-standards.md @@ -2,58 +2,39 @@ reviewers: - tallclair title: Pod Security Standards +description: > + A detailed look at the different policy levels defined in the Pod Security Standards. content_type: concept weight: 10 --- -Security settings for Pods are typically applied by using [security -contexts](/docs/tasks/configure-pod-container/security-context/). Security Contexts allow for the -definition of privilege and access controls on a per-Pod basis. - -The enforcement and policy-based definition of cluster requirements of security contexts has -previously been achieved using [Pod Security Policy](/docs/concepts/policy/pod-security-policy/). A -_Pod Security Policy_ is a cluster-level resource that controls security sensitive aspects of the -Pod specification. - -However, numerous means of policy enforcement have arisen that augment or replace the use of -PodSecurityPolicy. The intent of this page is to detail recommended Pod security profiles, decoupled -from any specific instantiation. - +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 | +| ------ | ----------- | +| Privileged | Unrestricted policy, providing the widest possible level of permissions. This policy allows for known privilege escalations. | +| Baseline | Minimally restrictive policy which prevents known privilege escalations. Allows the default (minimally specified) Pod configuration. | +| Restricted | Heavily restricted policy, following current Pod hardening best practices. | -## Policy Types - -There is an immediate need for base policy definitions to broadly cover the security spectrum. These -should range from highly restricted to highly flexible: - -- **_Privileged_** - Unrestricted policy, providing the widest possible level of permissions. This - policy allows for known privilege escalations. -- **_Baseline_** - Minimally restrictive policy while preventing known privilege - escalations. Allows the default (minimally specified) Pod configuration. -- **_Restricted_** - Heavily restricted policy, following current Pod hardening best practices. - -## Policies +## Profile Details ### 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 profile may be an absence of applied constraints -rather than an instantiated policy. 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. +{{< /note >}} @@ -63,112 +44,196 @@ enforced/disallowed: - + - + - + - + - + - + - + - + - + + + + + @@ -176,10 +241,11 @@ enforced/disallowed: ### Restricted -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: +**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: +{{< 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. +{{< /note >}}
Baseline policy specification
Policy
Host NamespacesHost Namespaces - Sharing the host namespaces must be disallowed.
-
Restricted Fields:
- spec.hostNetwork
- spec.hostPID
- spec.hostIPC
-
Allowed Values: false
+

Sharing the host namespaces must be disallowed.

+

Restricted Fields

+
    +
  • spec.hostNetwork
    • +
  • spec.hostPID
    • +
  • spec.hostIPC
    • +
+

Allowed Values

+
    +
  • false
    • +
Privileged ContainersPrivileged Containers - Privileged Pods disable most security mechanisms and must be disallowed.
-
Restricted Fields:
- spec.containers[*].securityContext.privileged
- spec.initContainers[*].securityContext.privileged
-
Allowed Values: false, undefined/nil
+

Privileged Pods disable most security mechanisms and must be disallowed.

+

Restricted Fields

+
    +
  • spec.containers[*].securityContext.privileged
    • +
  • spec.initContainers[*].securityContext.privileged
    • +
+

Allowed Values

+
    +
  • Undefined/nil
    • +
  • false
    • +
CapabilitiesCapabilities - Adding additional capabilities beyond the default set must be disallowed.
-
Restricted Fields:
- spec.containers[*].securityContext.capabilities.add
- spec.initContainers[*].securityContext.capabilities.add
-
Allowed Values: empty (or restricted to a known list)
+

Adding additional capabilities beyond the default set must be disallowed.

+

Restricted Fields

+
    +
  • spec.containers[*].securityContext.capabilities.add
    • +
  • spec.initContainers[*].securityContext.capabilities.add
    • +
+

Allowed Values

+
    +
  • Undefined/nil
    • +
  • AUDIT_WRITE
    • +
  • CHOWN
    • +
  • DAC_OVERRIDE
    • +
  • FOWNER
    • +
  • FSETID
    • +
  • KILL
    • +
  • MKNOD
    • +
  • NET_BIND_SERVICE
    • +
  • SETFCAP
    • +
  • SETGID
    • +
  • SETPCAP
    • +
  • SETUID
    • +
  • SYS_CHROOT
    • +
HostPath VolumesHostPath Volumes - HostPath volumes must be forbidden.
-
Restricted Fields:
- spec.volumes[*].hostPath
-
Allowed Values: undefined/nil
+

HostPath volumes must be forbidden.

+

Restricted Fields

+
    +
  • spec.volumes[*].hostPath
    • +
+

Allowed Values

+
    +
  • Undefined/nil
    • +
Host PortsHost Ports - HostPorts should be disallowed, or at minimum restricted to a known list.
-
Restricted Fields:
- spec.containers[*].ports[*].hostPort
- spec.initContainers[*].ports[*].hostPort
-
Allowed Values: 0, undefined (or restricted to a known list)
+

HostPorts should be disallowed, or at minimum restricted to a known list.

+

Restricted Fields

+
    +
  • spec.containers[*].ports[*].hostPort
    • +
  • spec.initContainers[*].ports[*].hostPort
    • +
+

Allowed Values

+
    +
  • Undefined/nil
    • +
  • Known list
    • +
  • 0
    • +
AppArmorAppArmor - On supported hosts, the 'runtime/default' AppArmor profile is applied by default. - The baseline policy should prevent overriding or disabling the default AppArmor - profile, or restrict overrides to an allowed set of profiles.
-
Restricted Fields:
- metadata.annotations['container.apparmor.security.beta.kubernetes.io/*']
-
Allowed Values: 'runtime/default', undefined
+

On supported hosts, the runtime/default AppArmor profile is applied by default. The baseline policy should prevent overriding or disabling the default AppArmor profile, or restrict overrides to an allowed set of profiles.

+

Restricted Fields

+
    +
  • metadata.annotations["container.apparmor.security.beta.kubernetes.io/*"]
    • +
+

Allowed Values

+
    +
  • Undefined/nil
    • +
  • runtime/default
    • +
SELinuxSELinux - Setting the SELinux type is restricted, and setting a custom SELinux user or role option is forbidden.
-
Restricted Fields:
- spec.securityContext.seLinuxOptions.type
- spec.containers[*].securityContext.seLinuxOptions.type
- spec.initContainers[*].securityContext.seLinuxOptions.type
-
Allowed Values:
- undefined/empty
- container_t
- container_init_t
- container_kvm_t
-
Restricted Fields:
- spec.securityContext.seLinuxOptions.user
- spec.containers[*].securityContext.seLinuxOptions.user
- spec.initContainers[*].securityContext.seLinuxOptions.user
- spec.securityContext.seLinuxOptions.role
- spec.containers[*].securityContext.seLinuxOptions.role
- spec.initContainers[*].securityContext.seLinuxOptions.role
-
Allowed Values: undefined/empty
+

Setting the SELinux type is restricted, and setting a custom SELinux user or role option is forbidden.

+

Restricted Fields

+
    +
  • spec.securityContext.seLinuxOptions.type
    • +
  • spec.containers[*].securityContext.seLinuxOptions.type
    • +
  • spec.initContainers[*].securityContext.seLinuxOptions.type
    • +
+

Allowed Values

+
    +
  • Undefined/nil
    • +
  • container_t
    • +
  • container_init_t
    • +
  • container_kvm_t
    • +
+
+

Restricted Fields

+
    +
  • spec.securityContext.seLinuxOptions.user
    • +
  • spec.containers[*].securityContext.seLinuxOptions.user
    • +
  • spec.initContainers[*].securityContext.seLinuxOptions.user
    • +
  • spec.securityContext.seLinuxOptions.role
    • +
  • spec.containers[*].securityContext.seLinuxOptions.role
    • +
  • spec.initContainers[*].securityContext.seLinuxOptions.role
    • +
+

Allowed Values

+
    +
  • Undefined/nil
    • +
/proc Mount Type/proc Mount Type - The default /proc masks are set up to reduce attack surface, and should be required.
-
Restricted Fields:
- spec.containers[*].securityContext.procMount
- spec.initContainers[*].securityContext.procMount
-
Allowed Values: undefined/nil, 'Default'
+

The default /proc masks are set up to reduce attack surface, and should be required.

+

Restricted Fields

+
    +
  • spec.containers[*].securityContext.procMount
    • +
  • spec.initContainers[*].securityContext.procMount
    • +
+

Allowed Values

+
    +
  • Undefined/nil
    • +
  • Default
    • +
SysctlsSeccomp +

Seccomp profile must not be explicitly set to Unconfined.

+

Restricted Fields

+
    +
  • spec.securityContext.seccompProfile.type
    • +
  • spec.containers[*].securityContext.seccompProfile.type
    • +
  • spec.initContainers[*].securityContext.seccompProfile.type
    • +
+

Allowed Values

+
    +
  • Undefined/nil
    • +
  • RuntimeDefault
    • +
  • Localhost*
    • +
+ * must also set securityContext.SeccompProfile.localhostProfile +
Sysctls - 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.
-
Restricted Fields:
- spec.securityContext.sysctls
-
Allowed Values:
- kernel.shm_rmid_forced
- net.ipv4.ip_local_port_range
- net.ipv4.tcp_syncookies
- net.ipv4.ping_group_range
- undefined/empty
+

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.

+

Restricted Fields

+
    +
  • spec.securityContext.sysctls
    • +
+

Allowed Values

+
    +
  • Undefined/nil
    • +
  • kernel.shm_rmid_forced
    • +
  • net.ipv4.ip_local_port_range
    • +
  • net.ipv4.ip_unprivileged_port_start
    • +
  • net.ipv4.tcp_syncookies
    • +
  • net.ipv4.ping_group_range
    • +
@@ -192,83 +258,107 @@ well as lower-trust users.The following listed controls should be enforced/disal - + - + - + - + - - - + + +
Restricted policy specification
Everything from the baseline profile.
Volume TypesVolume Types - In addition to restricting HostPath volumes, the restricted profile limits usage of non-core volume types to those defined through PersistentVolumes.
-
Restricted Fields:
- spec.volumes[*].hostPath
- spec.volumes[*].gcePersistentDisk
- spec.volumes[*].awsElasticBlockStore
- spec.volumes[*].gitRepo
- spec.volumes[*].nfs
- spec.volumes[*].iscsi
- spec.volumes[*].glusterfs
- spec.volumes[*].rbd
- spec.volumes[*].flexVolume
- spec.volumes[*].cinder
- spec.volumes[*].cephFS
- spec.volumes[*].flocker
- spec.volumes[*].fc
- spec.volumes[*].azureFile
- spec.volumes[*].vsphereVolume
- spec.volumes[*].quobyte
- spec.volumes[*].azureDisk
- spec.volumes[*].portworxVolume
- spec.volumes[*].scaleIO
- spec.volumes[*].storageos
- spec.volumes[*].csi
-
Allowed Values: undefined/nil
+

In addition to restricting HostPath volumes, the restricted policy limits usage of non-core volume types to those defined through PersistentVolumes.

+

Restricted Fields

+
    +
  • spec.volumes[*].hostPath
    • +
  • spec.volumes[*].gcePersistentDisk
    • +
  • spec.volumes[*].awsElasticBlockStore
    • +
  • spec.volumes[*].gitRepo
    • +
  • spec.volumes[*].nfs
    • +
  • spec.volumes[*].iscsi
    • +
  • spec.volumes[*].glusterfs
    • +
  • spec.volumes[*].rbd
    • +
  • spec.volumes[*].flexVolume
    • +
  • spec.volumes[*].cinder
    • +
  • spec.volumes[*].cephfs
    • +
  • spec.volumes[*].flocker
    • +
  • spec.volumes[*].fc
    • +
  • spec.volumes[*].azureFile
    • +
  • spec.volumes[*].vsphereVolume
    • +
  • spec.volumes[*].quobyte
    • +
  • spec.volumes[*].azureDisk
    • +
  • spec.volumes[*].portworxVolume
    • +
  • spec.volumes[*].scaleIO
    • +
  • spec.volumes[*].storageos
    • +
  • spec.volumes[*].csi
    • +
+

Allowed Values

+
    +
  • Undefined/nil
    • +
Privilege EscalationPrivilege Escalation - Privilege escalation (such as via set-user-ID or set-group-ID file mode) should not be allowed.
-
Restricted Fields:
- spec.containers[*].securityContext.allowPrivilegeEscalation
- spec.initContainers[*].securityContext.allowPrivilegeEscalation
-
Allowed Values: false
+

Privilege escalation (such as via set-user-ID or set-group-ID file mode) should not be allowed.

+

Restricted Fields

+
    +
  • spec.containers[*].securityContext.allowPrivilegeEscalation
    • +
  • spec.initContainers[*].securityContext.allowPrivilegeEscalation
    • +
+

Allowed Values

+
    +
  • false
    • +
Running as Non-rootRunning as Non-root - Containers must be required to run as non-root users.
-
Restricted Fields:
- spec.securityContext.runAsNonRoot
- spec.containers[*].securityContext.runAsNonRoot
- spec.initContainers[*].securityContext.runAsNonRoot
-
Allowed Values: true
+

Containers must be required to run as non-root users.

+

Restricted Fields

+
    +
  • spec.securityContext.runAsNonRoot
    • +
  • spec.containers[*].securityContext.runAsNonRoot
    • +
  • spec.initContainers[*].securityContext.runAsNonRoot
    • +
+

Allowed Values

+
    +
  • true
    • +
Non-root groups (optional)Non-root groups (optional) - Containers should be forbidden from running with a root primary or supplementary GID.
-
Restricted Fields:
- spec.securityContext.runAsGroup
- spec.securityContext.supplementalGroups[*]
- spec.securityContext.fsGroup
- spec.containers[*].securityContext.runAsGroup
- spec.initContainers[*].securityContext.runAsGroup
-
Allowed Values:
- non-zero
- undefined / nil (except for `*.runAsGroup`)
+

Containers should be forbidden from running with a root primary or supplementary GID.

+

Restricted Fields

+
    +
  • spec.securityContext.runAsGroup
    • +
  • spec.securityContext.supplementalGroups[*]
    • +
  • spec.securityContext.fsGroup
    • +
  • spec.containers[*].securityContext.runAsGroup
    • +
  • spec.initContainers[*].securityContext.runAsGroup
    • +
+

Allowed Values

+
    +
  • Undefined/nil (except for *.runAsGroup)
    • +
  • Non-zero
    • +
Seccomp - The RuntimeDefault seccomp profile must be required, or allow specific additional profiles.
-
Restricted Fields:
- spec.securityContext.seccompProfile.type
- spec.containers[*].securityContext.seccompProfile
- spec.initContainers[*].securityContext.seccompProfile
-
Allowed Values:
- 'runtime/default'
- undefined / nil
-
Seccomp +

Seccomp profile must be explicitly set to one of the allowed values. Both the Unconfined profile and the absence of a profile are prohibited.

+

Restricted Fields

+
    +
  • spec.securityContext.seccompProfile.type
    • +
  • spec.containers[*].securityContext.seccompProfile.type
    • +
  • spec.initContainers[*].securityContext.seccompProfile.type
    • +
+

Allowed Values

+
    +
  • RuntimeDefault
    • +
  • Localhost*
    • +
+ * must also set securityContext.SeccompProfile.localhostProfile +
@@ -281,20 +371,20 @@ 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/policy/pod-security-policy/) +[**PodSecurityPolicy**](/docs/concepts/profile/pod-security-profile/) -- {{< example file="policy/privileged-psp.yaml" >}}Privileged{{< /example >}} -- {{< example file="policy/baseline-psp.yaml" >}}Baseline{{< /example >}} -- {{< example file="policy/restricted-psp.yaml" >}}Restricted{{< /example >}} +- {{< example file="profile/privileged-psp.yaml" >}}Privileged{{< /example >}} +- {{< example file="profile/baseline-psp.yaml" >}}Baseline{{< /example >}} +- {{< example file="profile/restricted-psp.yaml" >}}Restricted{{< /example >}} ## FAQ -### Why isn't there a profile between privileged and baseline? +### Why isn't there a policy 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 profile in this -niche. This is not to say that the privileged profile should always be used in this case, but that +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 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. @@ -308,10 +398,10 @@ 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/policy/pod-security-policy/) - a mechanism for centrally enforcing security -policy on Pods across a cluster. Other alternatives for enforcing security policy are being +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-policy-agent/gatekeeper). +Gatekeeper](https://github.com/open-profile-agent/gatekeeper). ### What profiles should I apply to my Windows Pods? @@ -331,6 +421,6 @@ restrict privileged permissions is lessened when the workload is isolated from t kernel. This allows for workloads requiring heightened permissions to still be isolated. Additionally, the protection of sandboxed workloads is highly dependent on the method of -sandboxing. As such, no single recommended policy is recommended for all sandboxed workloads. +sandboxing. As such, no single recommended profile is recommended for all sandboxed workloads. diff --git a/content/en/docs/concepts/security/securing-pods.md b/content/en/docs/concepts/security/securing-pods.md new file mode 100644 index 0000000000000..3a6e087cf48f8 --- /dev/null +++ b/content/en/docs/concepts/security/securing-pods.md @@ -0,0 +1,216 @@ +--- +reviewers: +- tallclair +title: Securing Pods with the Pod Security Standards +content_type: concept +weight: 20 +--- + + + +{{< 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. + + + +## 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/: + +# 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/-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: + enforce-version: + audit: + audit-version: + warn: + warn-version: + exemptions: + usernames: [ ] + runtimeClassNames: [ ] + namespaces: [ ] +``` + +#### 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. \ No newline at end of file From e0d4b53b1c4a5b6e4b4dd158f410c1c5ac789325 Mon Sep 17 00:00:00 2001 From: Samuel Roth Date: Tue, 13 Jul 2021 02:07:24 +0000 Subject: [PATCH 2/2] incorporating initial round of feedback --- .../security/pod-security-admission.md | 129 +++++++++++ .../security/pod-security-standards.md | 147 +++++++++--- .../docs/concepts/security/securing-pods.md | 216 ------------------ .../admission-controllers.md | 12 + .../reference/labels-annotations-taints.md | 84 +++++++ .../enforcing-pod-security-standards.md | 78 +++++++ .../enforce-standards-admission-controller.md | 54 +++++ .../enforce-standards-namespace-labels.md | 81 +++++++ .../migrate-from-psp.md | 48 ++++ .../security/podsecurity-baseline.yaml | 9 + .../security/podsecurity-privileged.yaml | 7 + .../security/podsecurity-restricted.yaml | 9 + 12 files changed, 623 insertions(+), 251 deletions(-) create mode 100644 content/en/docs/concepts/security/pod-security-admission.md delete mode 100644 content/en/docs/concepts/security/securing-pods.md create mode 100644 content/en/docs/setup/best-practices/enforcing-pod-security-standards.md create mode 100644 content/en/docs/tasks/configure-pod-container/enforce-standards-admission-controller.md create mode 100644 content/en/docs/tasks/configure-pod-container/enforce-standards-namespace-labels.md create mode 100644 content/en/docs/tasks/configure-pod-container/migrate-from-psp.md create mode 100644 content/en/examples/security/podsecurity-baseline.yaml create mode 100644 content/en/examples/security/podsecurity-privileged.yaml create mode 100644 content/en/examples/security/podsecurity-restricted.yaml diff --git a/content/en/docs/concepts/security/pod-security-admission.md b/content/en/docs/concepts/security/pod-security-admission.md new file mode 100644 index 0000000000000..634f85fc9ffc0 --- /dev/null +++ b/content/en/docs/concepts/security/pod-security-admission.md @@ -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 +--- + + + +{{< 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 >}} + + + +## 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/: + +# 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/-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) \ No newline at end of file diff --git a/content/en/docs/concepts/security/pod-security-standards.md b/content/en/docs/concepts/security/pod-security-standards.md index 944eb984f1616..39fccb4230323 100644 --- a/content/en/docs/concepts/security/pod-security-standards.md +++ b/content/en/docs/concepts/security/pod-security-standards.md @@ -10,7 +10,9 @@ weight: 10 -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 >}} @@ -55,6 +67,7 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp

Allowed Values

    +
  • Undefined/nil
  • false
@@ -67,6 +80,7 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
  • spec.containers[*].securityContext.privileged
  • spec.initContainers[*].securityContext.privileged
    • +
  • spec.ephemeralContainers[*].securityContext.privileged

Allowed Values

    @@ -78,11 +92,12 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
@@ -158,10 +175,11 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
  • spec.securityContext.seLinuxOptions.type
  • spec.containers[*].securityContext.seLinuxOptions.type
  • spec.initContainers[*].securityContext.seLinuxOptions.type
    • +
  • spec.ephemeralContainers[*].securityContext.seLinuxOptions.type

    • Allowed Values

      -
    • Undefined/nil
      • +
    • Undefined/""
    • container_t
    • container_init_t
    • container_kvm_t
      • @@ -172,13 +190,15 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
    • spec.securityContext.seLinuxOptions.user
    • spec.containers[*].securityContext.seLinuxOptions.user
    • spec.initContainers[*].securityContext.seLinuxOptions.user
      • +
    • spec.ephemeralContainers[*].securityContext.seLinuxOptions.user
    • spec.securityContext.seLinuxOptions.role
    • spec.containers[*].securityContext.seLinuxOptions.role
    • spec.initContainers[*].securityContext.seLinuxOptions.role
      • +
    • spec.ephemeralContainers[*].securityContext.seLinuxOptions.role

    Allowed Values

      -
    • Undefined/nil
      • +
    • Undefined/""
    @@ -190,6 +210,7 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
    • spec.containers[*].securityContext.procMount
    • spec.initContainers[*].securityContext.procMount
      • +
    • spec.ephemeralContainers[*].securityContext.procMount

    Allowed Values

      @@ -207,14 +228,14 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
    • spec.securityContext.seccompProfile.type
    • spec.containers[*].securityContext.seccompProfile.type
    • spec.initContainers[*].securityContext.seccompProfile.type
      • +
    • spec.ephemeralContainers[*].securityContext.seccompProfile.type

    Allowed Values

    • Undefined/nil
    • RuntimeDefault
      • -
    • Localhost*
      • +
    • Localhost
    - * must also set securityContext.SeccompProfile.localhostProfile @@ -223,7 +244,7 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp

    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.

    Restricted Fields

      -
    • spec.securityContext.sysctls
      • +
    • spec.securityContext.sysctls[*].name

    Allowed Values

      @@ -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 >}}
    Capabilities -

    Adding additional capabilities beyond the default set must be disallowed.

    +

    Adding additional capabilities beyond those listed below must be disallowed.

    Restricted Fields

    • spec.containers[*].securityContext.capabilities.add
    • spec.initContainers[*].securityContext.capabilities.add
      • +
    • spec.ephemeralContainers[*].securityContext.capabilities.add

    Allowed Values

      @@ -125,6 +140,7 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
      • spec.containers[*].ports[*].hostPort
      • spec.initContainers[*].ports[*].hostPort
        • +
      • spec.ephemeralContainers[*].ports[*].hostPort

      Allowed Values

        @@ -146,6 +162,7 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
        • Undefined/nil
        • runtime/default
          • +
        • localhost/*
    @@ -283,7 +310,7 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
  • spec.volumes[*].portworxVolume
  • spec.volumes[*].scaleIO
  • spec.volumes[*].storageos
    • -
  • spec.volumes[*].csi
    • +
  • spec.volumes[*].photonPersistentDisk

    • Allowed Values

      @@ -292,13 +319,14 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
    - + @@ -333,6 +366,7 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
  • spec.securityContext.fsGroup
  • spec.containers[*].securityContext.runAsGroup
  • spec.initContainers[*].securityContext.runAsGroup
    • +
  • spec.ephemeralContainers[*].securityContext.runAsGroup

    • Allowed Values

      @@ -342,7 +376,7 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
    - + + + + +
    Privilege EscalationPrivilege Escalation (v1.8+)

    Privilege escalation (such as via set-user-ID or set-group-ID file mode) should not be allowed.

    Restricted Fields

    • spec.containers[*].securityContext.allowPrivilegeEscalation
    • spec.initContainers[*].securityContext.allowPrivilegeEscalation
      • +
    • spec.ephemeralContainers[*].securityContext.allowPrivilegeEscalation

    Allowed Values

      @@ -315,11 +343,16 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
    • spec.securityContext.runAsNonRoot
    • spec.containers[*].securityContext.runAsNonRoot
    • spec.initContainers[*].securityContext.runAsNonRoot
      • +
    • spec.ephemeralContainers[*].securityContext.runAsNonRoot

    Allowed Values

    • true
    + + The container fields may be undefined/nil if the pod-level + spec.securityContext.runAsNonRoot is set to true. +
    SeccompSeccomp (v1.19+)

    Seccomp profile must be explicitly set to one of the allowed values. Both the Unconfined profile and the absence of a profile are prohibited.

    Restricted Fields

    @@ -350,15 +384,52 @@ In this table, wildcards (`*`) incidate all elements in a list. For example, `sp
  • spec.securityContext.seccompProfile.type
  • spec.containers[*].securityContext.seccompProfile.type
  • spec.initContainers[*].securityContext.seccompProfile.type
    • +
  • spec.ephemeralContainers[*].securityContext.seccompProfile.type

    • Allowed Values

    • RuntimeDefault
      • -
    • Localhost*
      • -
    - * must also set securityContext.SeccompProfile.localhostProfile +
  • Localhost
    • + + + The container fields may be undefined/nil if the pod-level + spec.securityContext.seccompProfile.type field is set appropriately. + Conversely, the pod-level field may be undefined/nil if _all_ container- + level fields are set. +
    Capabilities (v1.22+) +

    + Containers must drop ALL capabilities, and are only permitted to add back + the NET_BIND_SERVICE capability. +

    +

    Restricted Fields

    +
      +
    • spec.containers[*].securityContext.capabilities.drop
      • +
    • spec.initContainers[*].securityContext.capabilities.drop
      • +
    • spec.ephemeralContainers[*].securityContext.capabilities.drop
      • +
    +

    Allowed Values

    +
      +
    • Any list of capabilities that includes ALL
      • +
    +
    +

    Restricted Fields

    +
      +
    • spec.containers[*].securityContext.capabilities.add
      • +
    • spec.initContainers[*].securityContext.capabilities.add
      • +
    • spec.ephemeralContainers[*].securityContext.capabilities.add
      • +
    +

    Allowed Values

    +
      +
    • Undefined/nil
      • +
    • NET_BIND_SERVICE
      • +
    +
    @@ -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? diff --git a/content/en/docs/concepts/security/securing-pods.md b/content/en/docs/concepts/security/securing-pods.md deleted file mode 100644 index 3a6e087cf48f8..0000000000000 --- a/content/en/docs/concepts/security/securing-pods.md +++ /dev/null @@ -1,216 +0,0 @@ ---- -reviewers: -- tallclair -title: Securing Pods with the Pod Security Standards -content_type: concept -weight: 20 ---- - - - -{{< 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. - - - -## 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/: - -# 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/-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: - enforce-version: - audit: - audit-version: - warn: - warn-version: - exemptions: - usernames: [ ] - runtimeClassNames: [ ] - namespaces: [ ] -``` - -#### 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. \ No newline at end of file diff --git a/content/en/docs/reference/access-authn-authz/admission-controllers.md b/content/en/docs/reference/access-authn-authz/admission-controllers.md index ddb10b988b520..0461c09f53229 100644 --- a/content/en/docs/reference/access-authn-authz/admission-controllers.md +++ b/content/en/docs/reference/access-authn-authz/admission-controllers.md @@ -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" >}} diff --git a/content/en/docs/reference/labels-annotations-taints.md b/content/en/docs/reference/labels-annotations-taints.md index 29f3a63a8c051..fcef50e97ce52 100644 --- a/content/en/docs/reference/labels-annotations-taints.md +++ b/content/en/docs/reference/labels-annotations-taints.md @@ -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.`. +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.`. +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.`. +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. \ No newline at end of file diff --git a/content/en/docs/setup/best-practices/enforcing-pod-security-standards.md b/content/en/docs/setup/best-practices/enforcing-pod-security-standards.md new file mode 100644 index 0000000000000..2b7ca6144e5d5 --- /dev/null +++ b/content/en/docs/setup/best-practices/enforcing-pod-security-standards.md @@ -0,0 +1,78 @@ +--- +reviewers: +- tallclair +- liggitt +title: Enforcing Pod Security Standards +weight: 40 +--- + + + +This page provides an overview of best practices when it comes to enforcing +[Pod Security Standards](/docs/concepts/security/pod-security-standards). + + + +## 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. \ No newline at end of file diff --git a/content/en/docs/tasks/configure-pod-container/enforce-standards-admission-controller.md b/content/en/docs/tasks/configure-pod-container/enforce-standards-admission-controller.md new file mode 100644 index 0000000000000..c3dcb0e9957cf --- /dev/null +++ b/content/en/docs/tasks/configure-pod-container/enforce-standards-admission-controller.md @@ -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: [] +``` \ No newline at end of file diff --git a/content/en/docs/tasks/configure-pod-container/enforce-standards-namespace-labels.md b/content/en/docs/tasks/configure-pod-container/enforce-standards-namespace-labels.md new file mode 100644 index 0000000000000..27cd0c3aada8e --- /dev/null +++ b/content/en/docs/tasks/configure-pod-container/enforce-standards-namespace-labels.md @@ -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 >}} +``` \ No newline at end of file diff --git a/content/en/docs/tasks/configure-pod-container/migrate-from-psp.md b/content/en/docs/tasks/configure-pod-container/migrate-from-psp.md new file mode 100644 index 0000000000000..f0ea2d02dfb02 --- /dev/null +++ b/content/en/docs/tasks/configure-pod-container/migrate-from-psp.md @@ -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 +--- + + + +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). + + + +## 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. \ No newline at end of file diff --git a/content/en/examples/security/podsecurity-baseline.yaml b/content/en/examples/security/podsecurity-baseline.yaml new file mode 100644 index 0000000000000..6251af5d2f15e --- /dev/null +++ b/content/en/examples/security/podsecurity-baseline.yaml @@ -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 \ No newline at end of file diff --git a/content/en/examples/security/podsecurity-privileged.yaml b/content/en/examples/security/podsecurity-privileged.yaml new file mode 100644 index 0000000000000..12471cce282f0 --- /dev/null +++ b/content/en/examples/security/podsecurity-privileged.yaml @@ -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 \ No newline at end of file diff --git a/content/en/examples/security/podsecurity-restricted.yaml b/content/en/examples/security/podsecurity-restricted.yaml new file mode 100644 index 0000000000000..8b9c30886d8ee --- /dev/null +++ b/content/en/examples/security/podsecurity-restricted.yaml @@ -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 \ No newline at end of file