OSDOCS-4047 and OSDOCS-3861: Operator workloads and PSA compliance

Author: michaelryanpeter

_topic_maps/_topic_map.yml

@@ -1769,6 +1769,8 @@ Topics:
     File: osdk-generating-csvs
   - Name: Working with bundle images
     File: osdk-working-bundle-images
+  - Name: Complying with pod security admission
+    File: osdk-complying-with-psa
   - Name: Validating Operators using the scorecard
     File: osdk-scorecard
   - Name: Validating Operator bundles

modules/osdk-ensuring-operator-workloads-run-restricted-psa.adoc

@@ -0,0 +1,65 @@
+// Module included in the following assemblies:
+//
+// * operators/operator_sdk/osdk-complying-with-psa.adoc
+
+:_content-type: PROCEDURE
+[id="osdk-ensuring-operator-workloads-run-restricted-psa_{context}"]
+= Ensuring Operator workloads run in namespaces set to the restricted pod security level
+
+To ensure your Operator project can run on a wide variety of deployments and environments, configure the Operator's workloads to run in namespaces set to the `restricted` pod security level.
+
+[WARNING]
+====
+You must leave the `runAsUser` field empty. If your image requires a specific user, it cannot be run under restricted security context constraints (SCC) and restricted pod security enforcement.
+====
+
+.Procedure
+
+* To configure Operator workloads to run in namespaces set to the `restricted` pod security level, edit your Operator's namespace definition similar to the following examples:
++
+[IMPORTANT]
+====
+It is recommended that you set the seccomp profile in your Operator's namespace definition. However, setting the seccomp profile is not supported in {product-title} 4.10.
+====
+
+** For Operator projects that must run in only {product-title} 4.11 and later, edit your Operator's namespace definition similar to the following example:
++
+.Example `config/manager/manager.yaml` file
+[source,yaml]
+----
+...
+spec:
+ securityContext:
+   seccompProfile:
+     type: RuntimeDefault <1>
+   runAsNonRoot: true
+ containers:
+   - name: <operator_workload_container>
+     securityContext:
+       allowPrivilegeEscalation: false
+       capabilities:
+         drop:
+           - ALL
+...
+----
+<1> By setting the seccomp profile type to `RuntimeDefault`, the SCC defaults to the pod security profile of the namespace.
+
+** For Operator projects that must also run in {product-title} 4.10, edit your Operator's namespace definition similar to the following example:
++
+.Example `config/manager/manager.yaml` file
+[source,yaml]
+----
+...
+spec:
+ securityContext: <1>
+   runAsNonRoot: true
+ containers:
+   - name: <operator_workload_container>
+     securityContext:
+       allowPrivilegeEscalation: false
+       capabilities:
+         drop:
+           - ALL
+...
+----
+<1> Leaving the seccomp profile type unset ensures your Operator project can run in {product-title} 4.10.

modules/osdk-managing-psa-for-operators-with-escalated-permissions.adoc

@@ -0,0 +1,61 @@
+// Module included in the following assemblies:
+//
+// * operators/operator_sdk/osdk-complying-with-psa.adoc
+
+:_content-type: PROCEDURE
+[id="osdk-managing-psa-for-operators-with-escalated-permissions.adoc_{context}"]
+= Managing pod security admission for Operator workloads that require escalated permissions
+
+If your Operator project requires escalated permissions to run, you must edit your Operator's cluster service version (CSV).
+
+.Procedure
+
+. Set the security context configuration to the required permission level in your Operator's CSV, similar to the following example:
++
+.Example `<operator_name>.clusterserviceversion.yaml` file with network administrator privileges
+[source,yaml]
+----
+...
+containers:
+   - name: my-container
+     securityContext:
+       allowPrivilegeEscalation: false
+       capabilities:
+         add:
+           - "NET_ADMIN"
+...
+----
+
+. Set the service account privileges that allow your Operator's workloads to use the required security context constraints (SCC), similar to the following example:
++
+.Example `<operator_name>.clusterserviceversion.yaml` file
+[source,yaml]
+----
+...
+  install:
+    spec:
+      clusterPermissions:
+      - rules:
+        - apiGroups:
+          - security.openshift.io
+          resourceNames:
+          - privileged
+          resources:
+          - securitycontextconstraints
+          verbs:
+          - use
+        serviceAccountName: default
+...
+----
+
+. Edit your Operator's CSV description to explain why your Operator project requires escalated permissions similar to the following example:
++
+.Example `<operator_name>.clusterserviceversion.yaml` file
+[source,yaml]
+----
+...
+spec:
+  apiservicedefinitions:{}
+  ...
+description: The <operator_name> requires a privileged pod security admission label set on the Operator's namespace. The Operator's agents require escalated permissions to restart the node if the node needs remediation.
+----

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

@@ -1,6 +1,7 @@
 // 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-synchronization_{context}"]

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

@@ -0,0 +1,32 @@
+:_content-type: ASSEMBLY
+[id="osdk-complying-with-psa"]
+= Complying with pod security admission
+include::_attributes/common-attributes.adoc[]
+:context: osdk-complying-with-psa.adoc
+
+toc::[]
+
+_Pod security admission_ is an implementation of the link:https://kubernetes.io/docs/concepts/security/pod-security-standards/[Kubernetes pod security standards]. link:https://kubernetes.io/docs/concepts/security/pod-security-admission/[Pod security admission] restricts the behavior of pods. 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.
+
+If your Operator project does not require escalated permissions to run, you can ensure your workloads run in namespaces set to the `restricted` pod security level. If your Operator project requires escalated permissions to run, you must set the following security context configurations:
+
+* The allowed pod security admission level for the Operator's namespace
+* The allowed security context constraints (SCC) for the workload's service account
+
+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].
+
+include::modules/security-context-constraints-psa-synchronization.adoc[leveloffset=+1]
+include::modules/osdk-ensuring-operator-workloads-run-restricted-psa.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../authentication/managing-security-context-constraints.adoc#managing-security-context-constraints[Managing security context constraints]
+
+include::modules/osdk-managing-psa-for-operators-with-escalated-permissions.adoc[leveloffset=+1]
+
+[id="osdk-complying-with-psa-additional-resources"]
+[role="_additional-resources"]
+== Additional resources
+
+* xref:../../authentication/understanding-and-managing-pod-security-admission.adoc#understanding-and-managing-pod-security-admission[Understanding and managing pod security admission]