Merge pull request #28903 from sejr/feat/podsecurity

Add Pod Security Standards documentation
2021-07-22 01:57:52 -07:00
parent b017081952 e0d4b53b1c
commit f92e3ec2ba
12 changed files with 859 additions and 178 deletions
@@ -0,0 +1,54 @@
+---
+title: Enforce Pod Security Standards by Configuring the Built-in Admission Controller
+reviewers:
+- tallclair
+- liggitt
+content_type: task
+min-kubernetes-server-version: v1.22
+---
+
+As of v1.22, Kubernetes provides a built-in [admission controller](/docs/reference/access-authn-authz/admission-controllers/#podsecurity)
+to enforce the [Pod Security Standards](/docs/concepts/security/pod-security-standards).
+You can configure this admission controller to set cluster-wide defaults and [exemptions](#exemptions).
+
+## {{% heading "prerequisites" %}}
+
+{{% version-check %}}
+
+- Enable the `PodSecurity` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/#feature-gates-for-alpha-or-beta-features).
+
+## Configure the Admission Controller
+
+```yaml
+apiVersion: apiserver.config.k8s.io/v1
+kind: AdmissionConfiguration
+plugins:
+- name: PodSecurity
+  configuration:
+    apiVersion: pod-security.admission.config.k8s.io/v1alpha1
+    kind: PodSecurityConfiguration
+    # Defaults applied when a mode label is not set.
+    #
+    # Level label values must be one of:
+    # - "privileged" (default)
+    # - "baseline"
+    # - "restricted"
+    #
+    # Version label values must be one of:
+    # - "latest" (default) 
+    # - specific version like "v{{< skew latestVersion >}}"
+    defaults:
+      enforce: "privileged"
+      enforce-version: "latest"
+      audit: "privileged"
+      audit-version: "latest"
+      warn: "privileged"
+      warn-version: "latest"
+    exemptions:
+      # Array of authenticated usernames to exempt.
+      usernames: []
+      # Array of runtime class names to exempt.
+      runtimeClassNames: []
+      # Array of namespaces to exempt.
+      namespaces: []
+```
@@ -0,0 +1,81 @@
+---
+title: Enforce Pod Security Standards with Namespace Labels
+reviewers:
+- tallclair
+- liggitt
+content_type: task
+min-kubernetes-server-version: v1.22
+---
+
+Namespaces can be labeled to enforce the [Pod Security Standards](/docs/concepts/security/pod-security-standards).
+
+## {{% heading "prerequisites" %}}
+
+{{% version-check %}}
+
+- Enable the `PodSecurity` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/#feature-gates-for-alpha-or-beta-features).
+
+## Requiring the `baseline` Pod Security Standard with namespace labels
+
+This manifest defines a Namespace `my-baseline-namespace` that:
+
+- _Blocks_ any pods that don't satisfy the `baseline` policy requirements.
+- Generates a user-facing warning and adds an audit annotation to any created pod that does not
+  meet the `restricted` policy requirements.
+- Pins the versions of the `baseline` and `restricted` policies to v{{< skew latestVersion >}}.
+
+```yaml
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: my-baseline-namespace
+  labels:
+    pod-security.kubernetes.io/enforce: baseline
+    pod-security.kubernetes.io/enforce-version: v{{< skew latestVersion >}}
+
+    # We are setting these to our _desired_ `enforce` level.
+    pod-security.kubernetes.io/audit: restricted
+    pod-security.kubernetes.io/audit-version: v{{< skew latestVersion >}}
+    pod-security.kubernetes.io/warn: restricted
+    pod-security.kubernetes.io/warn-version: v{{< skew latestVersion >}}
+```
+
+## Add labels to existing namespaces with `kubectl label`
+
+{{< note >}}
+When an `enforce` policy (or version) label is added or changed, the admission plugin will test
+each pod in the namespace against the new policy. Violations are returned to the user as warnings.
+{{< /note >}}
+
+It is helpful to apply the `--dry-run` flag when initially evaluating security profile changes for
+namespaces. The Pod Security Standard checks will still be run in _dry run_ mode, giving you
+information about how the new policy would treat existing pods, without actually updating a policy.
+
+```shell
+kubectl label --dry-run=server --overwrite ns --all \
+    pod-security.kubernetes.io/enforce=baseline
+```
+
+### Applying to all namespaces
+
+If you're just getting started with the Pod Security Standards, a suitable first step would be to
+configure all namespaces as `privileged` but set up audit annotations for a stricter level such as
+`baseline`:
+
+```shell
+kubectl label --overwrite ns --all \
+  pod-security.kubernetes.io/enforce=privileged \
+  pod-security.kubernetes.io/audit=baseline \
+  pod-security.kubernetes.io/warn=baseline
+```
+
+### Applying to a single namespace
+
+You can update a specific namespace as well. This command adds the `enforce=restricted`
+policy to `my-existing-namespace`, pinning the restricted policy version to v{{< skew latestVersion >}}.
+
+```shell
+kubectl label --overwrite ns my-existing-namespace \
+  pod-security.kubernetes.io/enforce=restricted \
+  pod-security.kubernetes.io/enforce-version=v{{< skew latestVersion >}}
+```
@@ -0,0 +1,48 @@
+---
+title: Migrate from PodSecurityPolicy to the Built-In PodSecurity Admission Controller
+reviewers:
+- tallclair
+- liggitt
+content_type: task
+min-kubernetes-server-version: v1.22
+---
+
+<!-- overview -->
+
+This page describes the process of migrating from PodSecurityPolicies to the built-in PodSecurity
+admission controller. This can be done effectively using a combination of dry-run and `audit` and
+`warn` modes, although this becomes harder if mutating PSPs are used.
+
+## {{% heading "prerequisites" %}}
+
+{{% version-check %}}
+
+- Enable the `PodSecurity` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/#feature-gates-for-alpha-or-beta-features).
+
+<!-- body -->
+
+## Steps
+
+- **Eliminate mutating PodSecurityPolicies, if your cluster has any set up.**
+  - Clone all mutating PSPs into a non-mutating version.
+  - Update all ClusterRoles authorizing use of those mutating PSPs to also authorize use of the
+    non-mutating variant.
+  - Watch for Pods using the mutating PSPs and work with code owners to migrate to valid,
+    non-mutating resources.
+  - Delete mutating PSPs.
+- **Select a compatible policy level for each namespace.** Analyze existing resources in the
+  namespace to drive this decision.
+  - Review the requirements of the different [Pod Security Standards](/docs/concepts/security/pod-security-standards).
+  - Evaluate the difference in privileges that would come from disabling the PSP controller.
+  - In the event that a PodSecurityPolicy falls between two levels, consider:
+    - Selecting a _less_ permissive PodSecurity level prioritizes security, and may require adjusting
+      workloads to fit within the stricter policy.
+    - Selecting a _more_ permissive PodSecurity level prioritizes avoiding disrupting or
+      changing workloads, but may allow workload authors in the namespace greater permissions
+      than desired.
+- **Apply the selected profiles in `warn` and `audit` mode.** This will give you an idea of how
+  your Pods will respond to the new policies, without breaking existing workloads. Iterate on your
+  [Pods' configuration](/docs/concepts/security/pod-security-admission#configuring-pods) until
+  they are in compliance with the selected profiles.
+- Apply the profiles in `enforce` mode.
+- Stop including `PodSecurityPolicy` in the `--enable-admission-plugins` flag.