AUTH-133: Pod security admission

Introduce pod security admission for OCP.

Commit adds a PSA assembly to the auth section, as well as updates
the SCC list module with new PSA SCCs.

Author: maxwelldb

_topic_maps/_topic_map.yml

@@ -943,6 +943,9 @@ Topics:
 - Name: Managing security context constraints
   File: managing-security-context-constraints
   Distros: openshift-enterprise,openshift-origin
+- Name: Understanding and managing pod security admission
+  File: understanding-and-managing-pod-security-admission
+  Distros: openshift-enterprise,openshift-origin
 - Name: Impersonating the system:admin user
   File: impersonating-system-admin
   Distros: openshift-enterprise,openshift-origin

authentication/understanding-and-managing-pod-security-admission.adoc

@@ -0,0 +1,22 @@
+:_content-type: ASSEMBLY
+[id="understanding-and-managing-pod-security-admission"]
+= Understanding and managing pod security admission
+include::_attributes/common-attributes.adoc[]
+:context: understanding-and-managing-pod-security-admission
+
+toc::[]
+
+Pod security admission is an implementation of the link:https://kubernetes.io/docs/concepts/security/pod-security-standards/[Kubernetes pod security standards]. Use pod security admission to restrict the behavior of pods.
+
+include::modules/security-context-constraints-psa-synchronization.adoc[leveloffset=+1]
+
+include::modules/security-context-constraints-psa-opting.adoc[leveloffset=+1]
+
+include::modules/security-context-constraints-psa-rectifying.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+[id="additional-resources_managing-pod-security-admission"]
+== Additional resources
+
+* xref:../security/audit-log-view.adoc#nodes-nodes-audit-log-basic-viewing_audit-log-view[Viewing audit logs]
+* xref:../authentication/managing-security-context-constraints.adoc#managing-pod-security-policies[Managing security context constraints]

modules/security-context-constraints-about.adoc

@@ -75,6 +75,14 @@ This SCC allows host file system access as any UID, including UID 0. Grant with
 If additional workloads are run on control plane hosts, use caution when providing access to `hostnetwork`. A workload that runs `hostnetwork` on a control plane host is effectively root on the cluster and must be trusted accordingly.
 ====
 
+|`hostnetwork-v2`
+| Like the `hostnetwork` SCC, but with the following differences:
+
+* `ALL` capabilities are dropped from containers.
+* The `NET_BIND_SERVICE` capability can be added explicitly.
+* `seccompProfile` is set to `runtime/default` by default.
+* `allowPrivilegeEscalation` must be unset or set to `false` in security contexts.
+
 |`node-exporter`
 |Used for the Prometheus node exporter.
 
@@ -87,6 +95,14 @@ endif::[]
 |`nonroot`
 |Provides all features of the `restricted` SCC, but allows users to run with any non-root UID. The user must specify the UID or it must be specified in the manifest of the container runtime.
 
+|`nonroot-v2`
+| Like the `nonroot` SCC, but with the following differences:
+
+* `ALL` capabilities are dropped from containers.
+* The `NET_BIND_SERVICE` capability can be added explicitly.
+* `seccompProfile` is set to `runtime/default` by default.
+* `allowPrivilegeEscalation` must be unset or set to `false` in security contexts.
+
 ifndef::openshift-dedicated[]
 |`privileged`
 |Allows access to all privileged and host features and the ability to run as any user, any group, any FSGroup, and with any SELinux context.
@@ -132,6 +148,14 @@ The `restricted` SCC:
 The restricted SCC is the most restrictive of the SCCs that ship by default with the system. However, you can create a custom SCC that is even more restrictive. For example, you can create an SCC that restricts `readOnlyRootFS` to `true` and `allowPrivilegeEscalation` to `false`.
 ====
 
+|`restricted-v2`
+| Like the `restricted` SCC, but with the following differences:
+
+* `ALL` capabilities are dropped from containers.
+* The `NET_BIND_SERVICE` capability can be added explicitly.
+* `seccompProfile` is set to `runtime/default` by default.
+* `allowPrivilegeEscalation` must be unset or set to `false` in security contexts.
+
 |===
 
 [id="scc-settings_{context}"]

modules/security-context-constraints-psa-opting.adoc

@@ -0,0 +1,44 @@
+// Module included in the following assemblies:
+//
+// * authentication/understanding-and-managing-pod-security-admission.adoc
+
+:_content-type: PROCEDURE
+[id="security-context-constraints-psa-opting_{context}"]
+= Controlling pod security admission synchronization
+
+You can enable or disable automatic pod security admission synchronization for most namespaces.
+
+[NOTE]
+====
+By default, user-created namespaces that have the prefix `openshift-` have pod security admission label synchronization disabled.
+
+Namespaces that the installer creates have pod security admission label synchronization disabled permanently. These namespaces include:
+
+* All namespaces that are prefixed with `openshift-`, except for `openshift-operators`
+* `default`
+* `kube-node-lease`
+* `kube-system`
+* `kube-public`
+* `openshift`
+====
+
+.Procedure
+
+* For each namespace that you want to configure, set a value for the `security.openshift.io/scc.podSecurityLabelSync` label:
+** To disable pod security admission label sychronization in a namespace, set the value of the `security.openshift.io/scc.podSecurityLabelSync` label to `false`.
++
+Run the following command:
++
+[source,terminal]
+----
+$ oc label namespace <namespace> security.openshift.io/scc.podSecurityLabelSync=false
+----
+
+** To enable pod security admission label sychronization in a namespace, set the value of the `security.openshift.io/scc.podSecurityLabelSync` label to `true`.
++
+Run the following command:
++
+[source,terminal]
+----
+$ oc label namespace <namespace> security.openshift.io/scc.podSecurityLabelSync=true
+----

modules/security-context-constraints-psa-rectifying.adoc

@@ -0,0 +1,13 @@
+// Module included in the following assemblies:
+//
+// * authentication/understanding-and-managing-pod-security-admission.adoc
+
+:_content-type: PROCEDURE
+[id="security-context-constraints-psa-rectifying_{context}"]
+= About pod security admission alerts
+
+A `PodSecurityViolation` alert is triggered when the Kubernetes API server reports that there is a pod denial on the audit level of the pod security admission controller. This alert persists for one day.
+
+View the Kubernetes API server audit logs to investigate alerts that were triggered. As an example, a workload is likely to fail admission if global enforcement is set to the `restricted` pod security level.
+
+For assistance in identifying pod security admission violation audit events, see link:https://kubernetes.io/docs/reference/labels-annotations-taints/audit-annotations/#pod-security-kubernetes-io-audit-violations[Audit annotations] in the Kubernetes documentation.

modules/security-context-constraints-psa-synchronization.adoc

@@ -0,0 +1,35 @@
+// Module included in the following assemblies:
+//
+// * authentication/understanding-and-managing-pod-security-admission.adoc
+
+:_content-type: CONCEPT
+[id="security-context-constraints-psa-synchronization_{context}"]
+= Security context constraint synchronization with pod security standards
+
+{product-title} includes link:https://kubernetes.io/docs/concepts/security/pod-security-admission[Kubernetes pod security admission]. Globally, the `privileged` profile is enforced, and the `restricted` profile is used for warnings and audits.
+
+In addition to the global pod security admission control configuration, a controller exists that applies pod security admission control `warn` and `audit` labels to namespaces according to the SCC permissions of the service accounts that are in a given namespace.
+
+The controller examines `ServiceAccount` object permissions to use security context constraints in each namespace. Security context constraints (SCCs) are mapped to pod security profiles based on their field values; the controller uses these translated profiles. Pod security admission `warn` and `audit` labels are set to the most privileged pod security profile found in the namespace to prevent warnings and audit logging as pods are created.
+
+Namespace labeling is based on consideration of namespace-local service account privileges.
+
+Applying pods directly might use the SCC privileges of the user who runs the pod. However, user privileges are not considered during automatic labeling.
+
+[IMPORTANT]
+====
+Namespaces that have an `openshift-` name prefix and were not created by the system during the installation are not synchronized by default.
+
+Namespaces that have the `openshift-` prefix are typically system namespaces; by convention, a controller should exist to manage them.
+
+You can enable SCC synchronization in namespaces that have the `openshift-` prefix by setting the value of the `security.openshift.io/scc.podSecurityLabelSync` label to `true`.
+
+Namespaces that are defined as part of the cluster payload have pod security admission synchronization disabled permanently. These namespaces include:
+
+* All namespaces that are prefixed with `openshift-`, except for `openshift-operators`
+* `default`
+* `kube-node-lease`
+* `kube-system`
+* `kube-public`
+* `openshift`
+====