Merge pull request #64343 from bergerhoffer/OSDOCS-7528

OSDOCS#7528: Reorganizing namespace exclusions and disabling after mo…

Author: bergerhoffer

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

@@ -11,12 +11,19 @@ Pod security admission is an implementation of the link:https://kubernetes.io/do
 // About pod security admission
 include::modules/security-context-constraints-psa-about.adoc[leveloffset=+1]
 
-// Security context constraint synchronization with pod security standards
+// About pod security admission synchronization
 include::modules/security-context-constraints-psa-synchronization.adoc[leveloffset=+1]
 
+// Pod security admission synchronization namespace exclusions
+include::modules/security-context-constraints-psa-sync-exclusions.adoc[leveloffset=+2]
+
 // Controlling pod security admission synchronization
 include::modules/security-context-constraints-psa-opting.adoc[leveloffset=+1]
 
+.Additional resources
+
+* xref:../authentication/understanding-and-managing-pod-security-admission.adoc#security-context-constraints-psa-sync-exclusions_understanding-and-managing-pod-security-admission[Pod security admission synchronization namespace exclusions]
+
 // Configuring pod security admission for a namespace
 include::modules/security-context-constraints-psa-label.adoc[leveloffset=+1]
 

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

@@ -10,18 +10,7 @@ You can enable or disable automatic pod security admission synchronization for m
 
 [IMPORTANT]
 ====
-Namespaces that are defined as part of the cluster payload have pod security admission synchronization disabled permanently. These namespaces include:
-
-* `default`
-* `kube-node-lease`
-* `kube-system`
-* `kube-public`
-* `openshift`
-* All system-created namespaces that are prefixed with `openshift-`, except for `openshift-operators`
-
-By default, all namespaces that have an `openshift-` prefix are not synchronized. You can enable synchronization for any user-created [x-]`openshift-*` namespaces. You cannot enable synchronization for any system-created [x-]`openshift-*` namespaces, except for `openshift-operators`. 
-
-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 synchronized label inherits the permissions of the service accounts in the namespace.
+You cannot enable pod security admission synchronization on some system-created namespaces. For more information, see _Pod security admission synchronization namespace exclusions_.
 ====
 
 .Procedure

modules/security-context-constraints-psa-sync-exclusions.adoc

@@ -0,0 +1,46 @@
+// 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-sync-exclusions_{context}"]
+= Pod security admission synchronization namespace exclusions
+
+Pod security admission synchronization is permanently disabled on most system-created namespaces. Synchronization is also initially disabled on user-created `openshift-*` prefixed namespaces, but you can enable synchronization on them later.
+
+[IMPORTANT]
+====
+If a pod security admission label (`pod-security.kubernetes.io/<mode>`) is manually modified from the automatically labeled value on a label-synchronized namespace, synchronization is disabled for that label.
+
+If necessary, you can enable synchronization again by using one of the following methods:
+
+* By removing the modified pod security admission label from the namespace
+* By setting the `security.openshift.io/scc.podSecurityLabelSync` label to `true`
++
+If you force synchronization by adding this label, then any modified pod security admission labels will be overwritten.
+====
+
+[discrete]
+== Permanently disabled namespaces
+
+Namespaces that are defined as part of the cluster payload have pod security admission synchronization disabled permanently. The following namespaces are permanently disabled:
+
+* `default`
+* `kube-node-lease`
+* `kube-system`
+* `kube-public`
+* `openshift`
+* All system-created namespaces that are prefixed with `openshift-`, except for `openshift-operators`
+
+[discrete]
+== Initially disabled namespaces
+
+By default, all namespaces that have an `openshift-` prefix have pod security admission synchronization disabled initially. You can enable synchronization for user-created [x-]`openshift-*` namespaces and for the `openshift-operators` namespace.
+
+[NOTE]
+====
+You cannot enable synchronization for any system-created [x-]`openshift-*` namespaces, except for `openshift-operators`.
+====
+
+If an Operator is installed in a user-created `openshift-*` namespace, synchronization is enabled automatically after a cluster service version (CSV) is created in the namespace. The synchronized label is derived from the permissions of the service accounts in the namespace.

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

@@ -5,16 +5,11 @@
 
 :_content-type: CONCEPT
 [id="security-context-constraints-psa-synchronization_{context}"]
-= Security context constraint synchronization with pod security standards
+= About pod security admission synchronization
 
 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.
-====
-
-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. 
+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

@@ -20,6 +20,10 @@ For more information, see xref:../../authentication/understanding-and-managing-p
 include::modules/security-context-constraints-psa-about.adoc[leveloffset=+1]
 
 include::modules/security-context-constraints-psa-synchronization.adoc[leveloffset=+1]
+
+// Pod security admission synchronization namespace exclusions
+include::modules/security-context-constraints-psa-sync-exclusions.adoc[leveloffset=+2]
+
 include::modules/osdk-ensuring-operator-workloads-run-restricted-psa.adoc[leveloffset=+1]
 
 [role="_additional-resources"]