ROX-30372: Update docs for admission controller changes

_topic_maps/_topic_map.yml

@@ -224,10 +224,10 @@ Topics:
   Topics:
   - Name: About policies in RHACS
     File: about-security-policies
-  - Name: Creating and modifying security policies
-    File: custom-security-policies
   - Name: Using admission controller enforcement
     File: use-admission-controller-enforcement
+  - Name: Creating and modifying security policies
+    File: custom-security-policies
   - Name: Managing policies as code
     File: managing-policies-as-code
   - Name: Security policy reference

integration/integrate-with-ci-systems.adoc

@@ -32,18 +32,17 @@ You can check {product-title-short} policies during builds.
 
 .Procedure
 
-. Configure policies that apply to the build time of the container lifecycle.
+. Configure policies that apply to the build stage of the container lifecycle.
 . Integrate with the registry that images are pushed to during the build.
 
 [role="_additional-resources"]
 .Additional resources
 
-xref:../integration/integrate-with-image-registries.adoc#integrate-with-image-registries[Integrating with image registries]
+* xref:..//operating/manage_security_policies/custom-security-policies.adoc#custom-security-policies[Creating and modifying security policies]
+* xref:../integration/integrate-with-image-registries.adoc#integrate-with-image-registries[Integrating with image registries]
 
 include::modules/integrate-ci-check-existing-build-phase-policies.adoc[leveloffset=+2]
 
-include::modules/create-new-system-policy.adoc[leveloffset=+2]
-
 include::modules/policy-enforcement-deploy.adoc[leveloffset=+3]
 
 [role="_additional-resources"]
@@ -59,7 +58,7 @@ To scan images, you must provide {product-title} with access to the image regist
 include::modules/check-for-existing-registry-integration.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
-==== Additional resources
+=== Additional resources
 * xref:../integration/integrate-with-image-registries.adoc#integrate-with-image-registries[Integrating with image registries]
 
 [id="configure-access"]

modules/admission-controller-failure-policy-changing.adoc

@@ -0,0 +1,30 @@
+// Module included in the following assemblies:
+//
+// * operating/manage_security_policies/use-admission-controller-enforcement.adoc
+:_mod-docs-content-type: PROCEDURE
+[id="admission-controller-failure-policy-changing_{context}"]
+= Configuring the admission controller failure policy on an existing cluster
+
+[role="_abstract"]
+You can configure the admission controller failure policy for an existing cluster. This setting determines whether the API server request is allowed (fail open) or blocked (fail closed) if an error or timeout happens in the {product-title-short} validating webhook evaluation. 
+
+. For a cluster that was installed by using the Operator, in the `SecuredCluster` custom resource (CR), edit the `admissionControl.failurePolicy` parameter to `Ignore` to fail open, or `Fail` to fail closed.
+. For a cluster that was installed by using Helm, in the `values-public.yaml` file, set the `admissionControl.failurePolicy` value to parameter to `Ignore` to fail open, or `Fail` to fail closed. Then then run the following command:
++
+[source,terminal]
+----
+helm upgrade -n stackrox \
+  stackrox-secured-cluster-services rhacs/secured-cluster-services \
+  --reuse-values \
+  -f /config/yaml/values-public.yaml \
+  -f /config/yaml/values-private.yaml
+----
+. For clusters installed by another method, you can use the {product-title-short} portal to edit the admission controller failure policy. You cannot edit Operator- or Helm-managed clusters by using the portal. Perform these steps:
+.. In the {product-title-short} portal, select *Platform Configuration* -> *Clusters*.
+.. Click *Secure a cluster* -> *Legacy installation method*. 
+.. In the *Static configuration (requires deployment)* section, in the *Admission controller failure policy* field, select one of the following options:
+* *Fail open*: If an error or timeout occurs when a workload admission or update request is being evaluated by the validating webhook, the request should be allowed to reach the API server.
+* *Fail closed*: If an error or timeout occurs when a workload admission or update request is being evaluated by the validating webhook, the request should not be allowed to reach the API server, but should be blocked.
+.. Select *Next*.
+.. Select *Finish*. Because this is a change to the static configuration, you must redeploy the cluster for your changes to take effect.
+

modules/admission-controller-failure-policy.adoc

@@ -0,0 +1,20 @@
+// Module included in the following assemblies:
+//
+// * operating/manage_security_policies/use-admission-controller-enforcement.adoc
+:_mod-docs-content-type: PROCEDURE
+[id="admission-controller-failure-policy_{context}"]
+= Configuring the admission controller failure policy during installation
+
+[role="_abstract"]
+You can configure the admission controller failure policy when you install a cluster. This setting determines whether the API server request is allowed (fail open) or blocked (fail closed) if an error or timeout happens in the {product-title-short} validating webhook evaluation. 
+
+. When installing a cluster by using the Operator, Helm, or `roxctl` CLI methods, follow the instructions in "Installing {product-title-short} on Red Hat OpenShift" and "Installing {product-title-short} on other platforms" to configure this parameter during installation.
+. When installing a cluster by using the legacy installation method, follow these steps:
+.. In the {product-title-short} portal, select *Platform Configuration* -> *Clusters*.
+.. Select an existing cluster from the list. 
+.. In the *Static configuration (requires deployment)* section, in the *Admission controller failure policy* field, select one of the following options:
+* *Fail open*: If an error or timeout occurs when a workload admission or update request is being evaluated by the validating webhook, the request should be allowed to reach the API server.
+* *Fail closed*: If an error or timeout occurs when a workload admission or update request is being evaluated by the validating webhook, the request should not be allowed to reach the API server, but should be blocked.
+.. Select *Next*.
+.. Select *Finish*. Because this is a change to the static configuration, you must redeploy the cluster for your changes to take effect.
+

modules/bypass-admission-controller-enforcement.adoc

@@ -1,12 +1,43 @@
 // Module included in the following assemblies:
 //
-// * operating/manage_security_policies/about-security-policies.adoc
+// * operating/manage_security_policies/use-admission-controller-enforcement.adoc
 
-:_mod-docs-content-type: CONCEPT
+:_mod-docs-content-type: PROCEDURE
 [id="bypass-admission-controller-enforcement_{context}"]
 = Bypassing admission controller enforcement
 
 [role="_abstract"]
-To bypass the admission controller, add the `admission.stackrox.io/break-glass` annotation to your configuration YAML.
-Bypassing the admission controller triggers a policy violation which includes deployment details.
-Red{nbsp}Hat recommends providing an issue-tracker link or some other reference as the value of this annotation so that others can understand why you bypassed the admission controller.
+To configure a deployment to bypass the admission controller, you must set the `admission.stackrox.io/break-glass` annotation on the deployment. Bypassing the admission controller triggers a violation of the "StackRox Emergency Deployment Annotation" policy, which includes deployment details.
+
+To help others understand why you bypassed the admission controller, use an issue-tracker link or some other reference as the value of this annotation.
+
+.Prerequisites
+
+* You have enabled the ability to bypass the admission controller on the secured cluster by setting the `admissionControl.bypass` parameter to `BreakGlassAnnotation`.
+
+.Procedure
+
+. Create a deployment YAML that includes the `admission.stackrox.io/break-glass` annotation, as shown in the following example:
+
+[source,yaml]
+----
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  annotations:
+    "admission.stackrox.io/break-glass": "jira-3423"
+  creationTimestamp: "2025-03-07T03:18:21Z"
+  generation: 1
+  labels:
+    app: hello-node
+  name: hello-node
+  namespace: test-bypass-adm
+...
+----
+
+where:
+
+"admission.stackrox.io/break-glass": "jira-3423"::
+
+Provides a change control reference or relevant explanation for why the admission controller was bypassed.
+

modules/disable-admission-controller-enforcement.adoc

@@ -1,16 +1,30 @@
 // Module included in the following assemblies:
 //
-// * operating/manage_security_policies/about-security-policies.adoc
+// * operating/manage_security_policies/use-admission-controller-enforcement.adoc
 :_mod-docs-content-type: PROCEDURE
 [id="disable-admission-controller-enforcement_{context}"]
-= Disabling admission controller enforcement
+= Disabling admission controller enforcement on a cluster
 
 [role="_abstract"]
-You can disable admission controller enforcement from the *Clusters* view on the {product-title} ({product-title-short}) portal.
+You can disable admission controller enforcement on a cluster when installing {product-title-short}. For clusters that you did not install by using the Operator or Helm, you can disable admission controller enforcement from the *Clusters* view on the {product-title} ({product-title-short}) portal. 
 
 .Procedure
-. In the {product-title-short} portal, select *Platform Configuration* -> *Clusters*.
-. Select an existing cluster from the list.
-. Turn off the *Enforce on Object Creates* and *Enforce on Object Updates* toggles in the *Dynamic Configuration* section.
-. Select *Next*.
-. Select *Finish*.
+. For a cluster that was installed by using the Operator, in the `SecuredCluster` custom resource (CR), edit the `admissionControl.enforcement` parameter to `Disabled`.
+. For a cluster that was installed by using Helm, in the `values-public.yaml` file, set the `admissionControl.enforce` value to `false` and run the following command:
++
+[source,terminal]
+----
+helm upgrade -n stackrox \
+  stackrox-secured-cluster-services rhacs/secured-cluster-services \
+  --reuse-values \
+  -f /config/yaml/values-public.yaml \
+  -f /config/yaml/values-private.yaml
+----
+. For clusters that are not managed by the Operator or Helm, you can use the {product-title-short} portal to change this setting:
+.. In the {product-title-short} portal, select *Platform Configuration* -> *Clusters*.
+.. Select an existing cluster from the list.
+.. In the *Dynamic configuration* section, in the *Admission controller enforcement behavior* field, select one of the following options:
+* Enforce policies: The admission controller enforces policies that are configured for enforcement by rejecting the workload admission or update attempt.
+* No enforcement: Even if enforcement is configured for a policy, if this option is selected, the admission controller does not enforce the policy and allows workload admission attempts or updates that violate the policy.
+.. Select *Next*.
+.. Select *Finish*.

modules/disable-associated-policies.adoc

@@ -3,13 +3,14 @@
 // * operating/manage_security_policies/about-security-policies.adoc
 :_mod-docs-content-type: PROCEDURE
 [id="disable-associated-policies_{context}"]
-= Disabling the admission controller for policies
+= Disabling a policy
 
 [role="_abstract"]
-You can turn off the enforcement on relevant policies, which in turn instructs the admission controller to skip enforcements.
-//is this correct? It doesn't seem right.
+You can disable a policy by using the {product-title-short} portal.
 
 .Procedure
-. In the {product-title-short} portal, go to *Platform Configuration* -> *Policy Management*.
-. Disable enforcement on the default policies that you do not want to enforce. For example:
-** In the policies view, click the *Kubernetes Actions: Exec into Pod* policy. Selection *Actions* -> *Disable policy*.
+. In the {product-title-short} portal, go to *Platform Configuration* -> *Policy Management*. For default policies, you cannot edit enforcement options. 
+. If you do not want the policy to be evaluated against workload operations, select *Actions* -> *Edit policy*.
+. In the left navigation menu, select *Actions*.
+. In the *Activation state* field, select *Disable*.
+. Save the policy.