Merge pull request #64227 from bergerhoffer/OSDOCS-7527

OSDOCS#7527: Adding more info about PSA, including namespaces that ar…

Author: bergerhoffer

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

@@ -8,12 +8,18 @@ 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.
 
+// About pod security admission
+include::modules/security-context-constraints-psa-about.adoc[leveloffset=+1]
+
 // Security context constraint synchronization with pod security standards
 include::modules/security-context-constraints-psa-synchronization.adoc[leveloffset=+1]
 
 // Controlling pod security admission synchronization
 include::modules/security-context-constraints-psa-opting.adoc[leveloffset=+1]
 
+// Configuring pod security admission for a namespace
+include::modules/security-context-constraints-psa-label.adoc[leveloffset=+1]
+
 // About pod security admission alerts
 include::modules/security-context-constraints-psa-rectifying.adoc[leveloffset=+1]
 

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

@@ -0,0 +1,71 @@
+// Module included in the following assemblies:
+//
+// * authentication/understanding-and-managing-pod-security-admission.adoc
+// * operators/operator_sdk/osdk-complying-with-psa.adoc
+
+:_content-type: CONCEPT
+[id="security-context-constraints-psa-about_{context}"]
+= About pod security admission
+
+{product-title} includes link:https://kubernetes.io/docs/concepts/security/pod-security-admission[Kubernetes pod security admission]. Pods that do not comply with the pod security admission defined globally or at the namespace level are not admitted to the cluster and cannot run.
+
+Globally, the `privileged` profile is enforced, and the `restricted` profile is used for warnings and audits.
+
+You can also configure the pod security admission settings at the namespace level.
+
+[id="psa-modes_{context}"]
+== Pod security admission modes
+
+You can configure the following pod security admission modes for a namespace:
+
+.Pod security admission modes
+[cols="1,2,3a",options="header"]
+|===
+|Mode
+|Label
+|Description
+
+|`enforce`
+|`pod-security.kubernetes.io/enforce`
+|Rejects a pod from admission if it does not comply with the set profile
+
+|`audit`
+|`pod-security.kubernetes.io/audit`
+|Logs audit events if a pod does not comply with the set profile
+
+|`warn`
+|`pod-security.kubernetes.io/warn`
+|Displays warnings if a pod does not comply with the set profile
+|===
+
+[id="psa-profiles_{context}"]
+== Pod security admission profiles
+
+You can set each of the pod security admission modes to one of the following profiles:
+
+.Pod security admission profiles
+[cols="1,3a",options="header"]
+|===
+|Profile
+|Description
+
+|`privileged`
+|Least restrictive policy; allows for known privilege escalation
+
+|`baseline`
+|Minimally restrictive policy; prevents known privilege escalations
+
+|`restricted`
+|Most restrictive policy; follows current pod hardening best practices
+|===
+
+[id="psa-privileged-namespaces_{context}"]
+== Privileged namespaces
+
+The following system namespaces are always set to the `privileged` pod security admission profile:
+
+* `default`
+* `kube-public`
+* `kube-system`
+
+You cannot change the pod security profile for these privileged namespaces.

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

@@ -0,0 +1,23 @@
+// Module included in the following assemblies:
+//
+// * authentication/understanding-and-managing-pod-security-admission.adoc
+
+:_content-type: PROCEDURE
+[id="security-context-constraints-psa-label_{context}"]
+=  Configuring pod security admission for a namespace
+
+You can configure the pod security admission settings at the namespace level. For each of the pod security admission modes on the namespace, you can set which pod security admission profile to use.
+
+.Procedure
+
+* For each pod security admission mode that you want to set on a namespace, run the following command:
+
++
+[source,terminal]
+----
+$ oc label namespace <namespace> \                <1>
+    pod-security.kubernetes.io/<mode>=<profile> \ <2>
+    --overwrite
+----
+<1> Set `<namespace>` to the namespace to configure.
+<2> Set `<mode>` to `enforce`, `warn`, or `audit`. Set `<profile>` to `restricted`, `baseline`, or `privileged`.

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

@@ -7,16 +7,14 @@
 [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.
+In addition to the global pod security admission control configuration, a controller 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.
 
 [IMPORTANT]
 ====
-Namespaces that are defined as part of the cluster payload have pod security admission synchronization disabled permanently. You can enable pod security admission synchronization on other namespaces as necessary. If an Operator is installed in a user-created `openshift-*` namespace, synchronization is turned on by default after a cluster service version (CSV) is created in the namespace. 
+Namespaces that are defined as part of the cluster payload have pod security admission synchronization disabled permanently. You can enable pod security admission synchronization on other namespaces as necessary. If an Operator is installed in a user-created `openshift-*` namespace, synchronization is turned on by default after a cluster service version (CSV) is created in the 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.
+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 in the namespace to prevent displaying warnings and logging audit events when pods are created. 
 
 Namespace labeling is based on consideration of namespace-local service account privileges.
 

operators/operator_sdk/osdk-complying-with-psa.adoc

@@ -16,6 +16,9 @@ If your Operator project does not require escalated permissions to run, you can
 
 For more information, see xref:../../authentication/understanding-and-managing-pod-security-admission.adoc#understanding-and-managing-pod-security-admission[Understanding and managing pod security admission].
 
+// About pod security admission
+include::modules/security-context-constraints-psa-about.adoc[leveloffset=+1]
+
 include::modules/security-context-constraints-psa-synchronization.adoc[leveloffset=+1]
 include::modules/osdk-ensuring-operator-workloads-run-restricted-psa.adoc[leveloffset=+1]