From d4a6d815858a3f3e30c0aecd921d683259100bbf Mon Sep 17 00:00:00 2001 From: kcarmich Date: Fri, 3 Oct 2025 15:07:24 -0400 Subject: [PATCH] Update docs for admission controller change --- _topic_maps/_topic_map.yml | 4 +- integration/integrate-with-ci-systems.adoc | 9 +- ...on-controller-failure-policy-changing.adoc | 30 ++++++ .../admission-controller-failure-policy.adoc | 20 ++++ ...pass-admission-controller-enforcement.adoc | 44 ++++++++- modules/create-new-system-policy.adoc | 70 -------------- ...able-admission-controller-enforcement.adoc | 30 ++++-- modules/disable-associated-policies.adoc | 13 +-- modules/disable-the-webhook.adoc | 76 ---------------- ...ntroller-enforcement-existing-cluster.adoc | 34 +++++++ ...able-admission-controller-enforcement.adoc | 55 +++-------- modules/policy-enforcement-about.adoc | 7 ++ modules/policy-enforcement-build-stage.adoc | 1 + modules/policy-enforcement-hard.adoc | 14 +-- ...tand-admission-controller-enforcement.adoc | 33 ++++--- modules/update-admission-controller.adoc | 91 ------------------- ...date-validating-webhook-configuration.adoc | 20 ---- ...tingwebhookconfiguration-yaml-changes.adoc | 65 ------------- .../about-security-policies.adoc | 6 +- .../custom-security-policies.adoc | 1 + .../use-admission-controller-enforcement.adoc | 28 ++++-- 21 files changed, 226 insertions(+), 425 deletions(-) create mode 100644 modules/admission-controller-failure-policy-changing.adoc create mode 100644 modules/admission-controller-failure-policy.adoc delete mode 100644 modules/create-new-system-policy.adoc delete mode 100644 modules/disable-the-webhook.adoc create mode 100644 modules/enable-admission-controller-enforcement-existing-cluster.adoc delete mode 100644 modules/update-admission-controller.adoc delete mode 100644 modules/update-validating-webhook-configuration.adoc delete mode 100644 modules/validatingwebhookconfiguration-yaml-changes.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 72a673b2c8aa..19f90ddc5061 100644 --- a/_topic_maps/_topic_map.yml +++ b/_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 diff --git a/integration/integrate-with-ci-systems.adoc b/integration/integrate-with-ci-systems.adoc index 0ad8e9380dfe..0be1f588d460 100644 --- a/integration/integrate-with-ci-systems.adoc +++ b/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"] diff --git a/modules/admission-controller-failure-policy-changing.adoc b/modules/admission-controller-failure-policy-changing.adoc new file mode 100644 index 000000000000..eca880ffa891 --- /dev/null +++ b/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. + diff --git a/modules/admission-controller-failure-policy.adoc b/modules/admission-controller-failure-policy.adoc new file mode 100644 index 000000000000..6bbb543f632f --- /dev/null +++ b/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 Secured Cluster services for {product-title-short} on Red Hat OpenShift" and "Installing Secured Cluster services for {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. + diff --git a/modules/bypass-admission-controller-enforcement.adoc b/modules/bypass-admission-controller-enforcement.adoc index 9e295a7a69d1..697571f11dc2 100644 --- a/modules/bypass-admission-controller-enforcement.adoc +++ b/modules/bypass-admission-controller-enforcement.adoc @@ -1,12 +1,46 @@ // 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 using one of the following options: +** Operator: You set the `admissionControl.bypass` parameter to `BreakGlassAnnotation`. +** Helm: You set the `admissionControl.dynamic.disableBypass` parameter to `false`. +** {product-title-short} portal: You set the option in *Platform Configuration* -> *Clusters* -> *Admission controller bypass annotation* to *Enabled*. + +.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. + diff --git a/modules/create-new-system-policy.adoc b/modules/create-new-system-policy.adoc deleted file mode 100644 index 2b98503fcdc2..000000000000 --- a/modules/create-new-system-policy.adoc +++ /dev/null @@ -1,70 +0,0 @@ -// Module included in the following assemblies: -// -// * integration/integrate-with-ci-systems.adoc -:_mod-docs-content-type: PROCEDURE -[id="create-new-system-policy_{context}"] -= Creating a new system policy - -In addition to using the default policies, you can also create custom policies in {product-title}. - -.Procedure -. In the {product-title-short} portal, go to *Platform Configuration* -> *Policy Management*. -. Click *+ New Policy*. -. Enter the *Name* for the policy. -. Select a *Severity* level for the policy: Critical, High, Medium, or Low. -. Choose the *Lifecycle Stages* for which the policy is applicable, from *Build*, *Deploy*, or *Runtime*. You can select more than one stage. -+ -[NOTE] -==== -If you create a new policy for integrating with a CI system, select *Build* as the lifecycle stage. -==== -** Build-time policies apply to image fields such as CVEs and Dockerfile instructions. -** Deploy-time policies can include all build-time policy criteria. They can also have data from your cluster configurations, such as running in privileged mode or mounting the Docker daemon socket. -** Runtime policies can include all build-time and deploy-time policy criteria, and data about process executions during runtime. -. Enter information about the policy in the *Description*, *Rationale*, and *Remediation* fields. -When CI validates the build, the data from these fields is displayed. -Therefore, include all information explaining the policy. -. Select a category from the *Categories* drop-down menu. -. Select a notifier from the *Notifications* drop-down menu that receives alert notifications when a violation occurs for this policy. -+ -[NOTE] -==== -You must integrate {product-title-short} with your notification providers, such as webhooks, Jira, or PagerDuty, to receive alert notifications. Notifiers only show up if you have integrated any notification providers with {product-title-short}. -==== -. Use *Restrict to Scope* to enable this policy only for a specific cluster, namespace, or label. -You can add multiple scopes and also use regular expressions in RE2 Syntax for namespaces and labels. -. Use *Exclude by Scope* to exclude deployments, clusters, namespaces, and labels. -This field indicates that the policy will not apply to the entities that you specify. -You can add multiple scopes and also use regular expressions in RE2 Syntax for namespaces and labels. -However, you cannot use regular expressions for selecting deployments. -. For *Excluded Images (Build Lifecycle only)*, select all the images from the list for which you do not want to trigger a violation for the policy. -+ -[NOTE] -==== -The *Excluded Images (Build Lifecycle only)* setting only applies when you check images in a continuous integration system (the Build lifecycle stage). -It does not have any effect if you use this policy to check running deployments (the Deploy lifecycle stage) or runtime activities (the Runtime lifecycle stage). -==== -. In the *Policy Criteria* section, configure the attributes that will trigger the policy. -//TODO: Add link to policy criteria -. Select *Next* on the panel header. -. The new policy panel shows a preview of the violations that are triggered if you enable the policy. -. Select *Next* on the panel header. -. Choose the enforcement behavior for the policy. -Enforcement settings are only available for the stages that you selected for the *Lifecycle Stages* option. -Select *ON* to enforce policy and report a violation. Select *OFF* to only report a violation. -+ -[NOTE] -==== -The enforcement behavior is different for each lifecycle stage. - -* For the *Build* stage, {product-title-short} fails your CI builds when images match the conditions of the policy. -* For the *Deploy* stage, {product-title-short} blocks the creation and update of deployments that match the conditions of the policy if the {product-title-short} admission controller is configured and running. -** In clusters with admission controller enforcement, the Kubernetes or {ocp} API server blocks all noncompliant deployments. In other clusters, {product-title-short} edits noncompliant deployments to prevent pods from being scheduled. -** For existing deployments, policy changes only result in enforcement at the next detection of the criteria, when a Kubernetes event occurs. For more information about enforcement, see "Deploy stage enforcement". -* For the *Runtime* stage, {product-title-short} stops all pods that match the conditions of the policy. -==== -+ -[WARNING] -==== -Policy enforcement can impact running applications or development processes. Before you enable enforcement options, inform all stakeholders and plan how to respond to the automated enforcement actions. -==== diff --git a/modules/disable-admission-controller-enforcement.adoc b/modules/disable-admission-controller-enforcement.adoc index 84e96ad2bb35..21dd6bf7aa07 100644 --- a/modules/disable-admission-controller-enforcement.adoc +++ b/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*. diff --git a/modules/disable-associated-policies.adoc b/modules/disable-associated-policies.adoc index 8469ff9eea7e..387ad7e33b7e 100644 --- a/modules/disable-associated-policies.adoc +++ b/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. \ No newline at end of file diff --git a/modules/disable-the-webhook.adoc b/modules/disable-the-webhook.adoc deleted file mode 100644 index 4ccdc3e244f7..000000000000 --- a/modules/disable-the-webhook.adoc +++ /dev/null @@ -1,76 +0,0 @@ -// Module included in the following assemblies: -// -// * operating/manage_security_policies/about-security-policies.adoc -:_mod-docs-content-type: PROCEDURE -[id="disable-the-webhook_{context}"] -= Disabling the webhook - -[role="_abstract"] - -You can disable admission controller enforcement from the *Clusters* view in the {product-title-short} portal. - -[IMPORTANT] -==== -If you disable the admission controller by turning off the webhook, you must redeploy the Sensor bundle. -==== - -.Procedure -. In the {product-title-short} portal, go to *Platform Configuration* -> *Clusters*. -. Select an existing cluster from the list. -. Turn off the *Enable Admission Controller Webhook to listen on exec and port-forward events* toggle in the *Static Configuration* section. -. Select *Next* to continue with Sensor setup. -. Click *Download YAML file and keys*. -. From a system that has access to the monitored cluster, extract and run the `sensor` script: -+ -[source,terminal] ----- -$ unzip -d sensor sensor-.zip ----- -+ -[source,terminal] ----- -$ ./sensor/sensor.sh ----- -+ -[NOTE] -==== -If you get a warning that you do not have the required permissions to deploy the sensor, follow the on-screen instructions, or contact your cluster administrator for help. -==== -After the sensor is deployed, it contacts Central and provides cluster information. -. Return to the {product-title-short} portal and check if the deployment is successful. -If it is successful, a green checkmark appears under section #2. -If you do not see a green checkmark, use the following command to check for problems: -* On {ocp}: -+ -[source,terminal] ----- -$ oc get pod -n stackrox -w ----- -* On Kubernetes: -+ -[source,terminal] ----- -$ kubectl get pod -n stackrox -w ----- -. Select *Finish*. - -[NOTE] -==== -When you disable the admission controller, {product-title-short} does not delete the `ValidatingWebhookConfiguration` parameter. -However, instead of checking requests for violations, it accepts all `AdmissionReview` requests. - -To remove the `ValidatingWebhookConfiguration` object, run the following command in the secured cluster: - -* On {ocp}: -+ -[source,terminal] ----- -$ oc delete ValidatingWebhookConfiguration/stackrox ----- -* On Kubernetes: -+ -[source,terminal] ----- -$ kubectl delete ValidatingWebhookConfiguration/stackrox ----- -==== diff --git a/modules/enable-admission-controller-enforcement-existing-cluster.adoc b/modules/enable-admission-controller-enforcement-existing-cluster.adoc new file mode 100644 index 000000000000..6ac0585f7ce2 --- /dev/null +++ b/modules/enable-admission-controller-enforcement-existing-cluster.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// +// * operating/manage_security_policies/use-admission-controller-enforcement.adoc +:_mod-docs-content-type: PROCEDURE +[id="enable-admission-controller-enforcement-existing-cluster_{context}"] += Viewing and enabling admission controller enforcement on an existing cluster + +[role="_abstract"] +You can view whether admission controller enforcement was enabled on a cluster or change the enforcement behavior after installation. + +.Procedure + +. For a cluster that was installed by using the Operator, in the `SecuredCluster` custom resource (CR), edit the `admissionControl.enforcement` parameter to `Enabled`. +. 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 installed by another method, you can use the {product-title-short} portal to edit the enforcement option. You cannot edit Operator- or Helm-managed clusters by using the portal. Follow these steps: +.. In the {product-title-short} portal, go to *Platform Configuration* -> *Clusters*. +.. Select an existing cluster from the list. +.. In the *Dynamic configuration* section, in the *Admission controller enforcement behavior* field, select *Enforce policies*. The admission controller enforces policies that are configured for enforcement by rejecting the workload admission or update attempt. +.. Select *Next*. +.. Select *Finish*. {product-title-short} automatically synchronizes the admission controller and applies the changes. + +.Verification +* The `ValidatingWebhookConfiguration` Kubernetes resource contains information about enforcement configuration behavior. The configuration settings are available in the admission controller logs. + + diff --git a/modules/enable-admission-controller-enforcement.adoc b/modules/enable-admission-controller-enforcement.adoc index b36cd4bba585..12286c319cb9 100644 --- a/modules/enable-admission-controller-enforcement.adoc +++ b/modules/enable-admission-controller-enforcement.adoc @@ -3,53 +3,20 @@ // * operating/manage_security_policies/use-admission-controller-enforcement.adoc :_mod-docs-content-type: PROCEDURE [id="enable-admission-controller-enforcement_{context}"] -= Enabling admission controller enforcement += Enabling admission controller enforcement during installation [role="_abstract"] -You can enable admission controller enforcement from the *Clusters* view when you install Sensor or edit an existing cluster configuration. +You can enable admission controller enforcement when you install a cluster. -//Add something here about how enforcement can be enabled in individual policies +. When installing a cluster by using the Operator, Helm, or `roxctl` CLI methods, follow the instructions in "Installing Secured Cluster services for {product-title-short} on Red Hat OpenShift" and "Installing Secured Cluster services for {product-title-short} on other platforms" to enable admission controller enforcement 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*. +.. Click *Secure a cluster* -> *Legacy installation method*. +.. In the *Dynamic configuration (syncs with Sensor)* section, in the *Admission controller enforcement behavior* field, select *Enforce policies*. +.. Select *Next*. +.. Select *Finish*. {product-title-short} automatically synchronizes the admission controller and applies the changes. -//Also add something about how it needs to be configured when installing the Operator, if you have chosen an Operator install method - -//This section will be heavily changed for 4.9 in a separate PR - -.Procedure -. In the {product-title-short} portal, go to *Platform Configuration* -> *Clusters*. -. Select an existing cluster from the list or secure a new cluster by selecting *Secure a cluster* -> *Legacy installation method*. -. If you are securing a new cluster, in the *Static Configuration* section of the cluster configuration panel, enter the details for your cluster. -. Red{nbsp}Hat recommends that you only turn on the *Configure Admission Controller Webhook to listen on Object Creates* toggle if you are planning to use the admission controller to enforce on object create events. -. Red{nbsp}Hat recommends that you only turn on the *Configure Admission Controller Webhook to listen on Object Updates* toggle if you are planning to use the admission controller to enforce on update events. -. Red{nbsp}Hat recommends that you only turn on the *Enable Admission Controller Webhook to listen on exec and port-forward events* toggle if you are planning to use the admission controller to enforce on pod execution and pod port forwards events. -. Configure the following options in the *Dynamic Configuration* section: -** *Enforce on Object Creates*: This toggle controls the behavior of the admission control service. -You must have the *Configure Admission Controller Webhook to listen on Object Creates* toggle turned on for this to work. -** *Enforce on Object Updates*: This toggle controls the behavior of the admission control service. -You must have the *Configure Admission Controller Webhook to listen on Object Updates* toggle turned on for this to work. -. Select *Next*. -. In the *Download files* section, select *Download YAML files and keys*. -+ -[NOTE] -==== -When enabling admission controller for an existing cluster, follow this guidance: +.Verification +* The `ValidatingWebhookConfiguration` Kubernetes resource contains information about enforcement configuration behavior. The configuration settings are available in the admission controller logs. -* If you make any changes in the *Static Configuration* section, you must download the YAML files and redeploy the Sensor. -* If you make any changes in the *Dynamic Configuration* section, you can skip downloading the files and deployment, as {product-title-short} automatically synchronizes the Sensor and applies the changes. -==== -. Select *Finish*. -.Verification -* After you provision a new cluster with the generated YAML, run the following command to verify if admission controller enforcement is configured correctly: -+ -[source,terminal] ----- -$ oc get ValidatingWebhookConfiguration <1> ----- -<1> If you use Kubernetes, enter `kubectl` instead of `oc`. -+ -.Example output -[source,terminal] ----- -NAME CREATED AT -stackrox 2019-09-24T06:07:34Z ----- diff --git a/modules/policy-enforcement-about.adoc b/modules/policy-enforcement-about.adoc index 5f4d3a36b3f4..3cc5faf6ba2a 100644 --- a/modules/policy-enforcement-about.adoc +++ b/modules/policy-enforcement-about.adoc @@ -9,3 +9,10 @@ When you configure policies in {product-title-short}, you can configure how {product-title-short} responds when it detects a condition that violates a security policy. {product-title-short} allows you to enforce security policies during all phases of the development lifecycle: build, deploy, and runtime. + +{product-title-short} provides two types of policy enforcement: + +* Sensor enforcement: Also known as _soft_ enforcement, if a workload is examined and violates a policy, Sensor scales down pods by using the Kubernetes API. +* Admission controller enforcement: Also known as _hard_ enforcement, an admission controller works with validating webhooks and the Kubernetes API server to block workload admission or update attempts that violate an enforced policy. When a request is made to deploy or update, the validating webhooks communicate with the admission controller and the admission controller responds to either allow or block the action based on whether a policy is enforced. The API server accepts or rejects the request based on whether it violates the policy and if the policy is enforced. + +For more information about admission controller enforcement, see "Understanding admission controller enforcement". diff --git a/modules/policy-enforcement-build-stage.adoc b/modules/policy-enforcement-build-stage.adoc index 747f45c892f9..0062022e6120 100644 --- a/modules/policy-enforcement-build-stage.adoc +++ b/modules/policy-enforcement-build-stage.adoc @@ -1,6 +1,7 @@ // Module included in the following assemblies: // // * operating/manage_security_policies/about-security-policies.adoc +// * integrating/integrate-with-ci-systems.aodc :_mod-docs-content-type: CONCEPT [id="build-stage-policies_{context}"] diff --git a/modules/policy-enforcement-hard.adoc b/modules/policy-enforcement-hard.adoc index b4c1c2e41fd6..5d46f25de369 100644 --- a/modules/policy-enforcement-hard.adoc +++ b/modules/policy-enforcement-hard.adoc @@ -8,18 +8,12 @@ [id="policy-enforcement-hard_{context}"] = Hard enforcement -Hard enforcement is performed by the {product-title-short} admission controller. In clusters with admission controller enforcement, the Kubernetes or {ocp} API server blocks all noncompliant deployments. The admission controller blocks `CREATE` and `UPDATE` operations. Any pod create or update request that satisfies a policy configured with deploy-time enforcement enabled will fail. +[role="_abstract"] +Hard enforcement is performed by the {product-title-short} admission controller. In clusters with admission controller enforcement, the Kubernetes or {ocp} API server blocks all noncompliant deployments. The admission controller blocks `CREATE`, `UPDATE`, and `SCALE` operations. Any pod create, update, or scale request that satisfies a policy configured with deploy-time enforcement enabled will fail. The admission controller also blocks user-initiated container commands such as `pod exec` and `port forward` for policies configured with runtime enforcement. [NOTE] ==== -Kubernetes admission webhooks support only `CREATE`, `UPDATE`, `DELETE`, or `CONNECT` operations. The {product-title-short} admission controller supports only `CREATE` and `UPDATE` operations. Operations such as `kubectl patch`, `kubectl set`, and `kubectl scale` are PATCH operations, not UPDATE operations. Because PATCH operations are not supported in Kubernetes, {product-title-short} cannot perform enforcement on PATCH operations. +Kubernetes admission webhooks support only `CREATE`, `UPDATE`, `DELETE`, and `CONNECT` operations. The {product-title-short} admission controller supports only `CREATE`, `UPDATE`, and `SCALE` operations. Operations such as `kubectl patch`, `kubectl set`, and `kubectl scale` are `PATCH` operations, not `UPDATE` operations. Because `PATCH` operations are not supported in Kubernetes, {product-title-short} cannot perform enforcement on PATCH operations. However, enforcement against `SCALE` operations is supported. ==== -For blocking enforcement, you must enable the following settings for the cluster in {product-title-short}: - -* *Enforce on Object Creates*: This toggle in the *Dynamic Configuration* section controls the behavior of the admission control service. -You must have the *Configure Admission Controller Webhook to listen on Object Creates* toggle in the *Static Configuration* section turned on for this to work. -* *Enforce on Object Updates*: This toggle in the *Dynamic Configuration* section controls the behavior of the admission control service. -You must have the *Configure Admission Controller Webhook to listen on Object Updates* toggle in the *Static Configuration* section turned on for this to work. - -If you make changes to settings in the *Static Configuration* setting, you must redeploy the secured cluster for those changes to take effect. +For hard enforcement, enable the enforcement settings for the cluster in {product-title-short}. To verify that enforcement is enabled, in the *Dynamic configuration* section, in the *Admission controller enforcement behavior* field, ensure that *Enforce policies* is selected. Additionally, for each policy that you want to enforce, select *Inform and enforce* when configuring the policy. \ No newline at end of file diff --git a/modules/understand-admission-controller-enforcement.adoc b/modules/understand-admission-controller-enforcement.adoc index f0d7705c6f9b..7590331c5b6e 100644 --- a/modules/understand-admission-controller-enforcement.adoc +++ b/modules/understand-admission-controller-enforcement.adoc @@ -5,23 +5,30 @@ [id="understand-admission-controller-enforcement_{context}"] = Understanding admission controller enforcement -If you intend to use admission controller enforcement, consider the following: +[role="_abstract"] -* *API latency*: Using admission controller enforcement increases Kubernetes or {ocp} API latency because it involves additional API validation requests. +{product-title-short} uses an admission controller to provide enforcement for security policies that you have configured. The admission controller works with validating webhooks to evaluate requests to create, update, and perform workload operations against security policies. It can also evaluate running workloads and detect user-initiated container commands such as `pod exec` and `port forward`. If enforcement is configured for a policy and results in a violation, the request fails, preventing the operation from persisting in the API server and being successfully completed. + +The workflow for evaluating requests and enforcing policies follows these steps: + +. A user or system submits a request to create, update, or perform workload operations that is received by the Kubernetes or {ocp} API server. +. The API server contacts the validating webhooks with an `AdmissionReview` request. +. The validating webhooks call the admission controller via the service endpoint to verify that the resource being provisioned or user-issued commands in the containers comply with the specified security policies. +. The review request is either passed or failed, or can time out in some cases: +* If the review request violates an enforced security policy, the API server rejects the request. +* If review request is not prevented by a security policy or times out, the API server accepts and persists the resource. In the case of a timeout, this behavior is known as "fail open", which is the default behavior. However, you can configure the default behavior in case of timeout to "fail closed" for stricter enforcement. + +If you use admission controller enforcement, consider the following guidance: + +* Using admission controller enforcement increases Kubernetes or {ocp} API latency because it involves additional validation like policy evaluation on Kubernetes operations. Many standard Kubernetes libraries, such as fabric8, have short Kubernetes or {ocp} API timeouts by default. -Also, consider API timeouts in any custom automation you might be using. If a request does time out due to latency issues, the admission controller will _fail open_, or allow the request to reach the API server. -* *Image scanning*: You can choose whether the admission controller scans images while reviewing requests by setting the *Contact Image Scanners* option in the cluster configuration panel. -** If you enable this setting, {product-title} contacts the image scanners if the scan or image signature verification results are not already available, which adds considerable latency. -** If you disable this setting, the enforcement decision only considers image scan criteria if cached scan and signature verification results are available. -* You can use admission controller enforcement for: ++ +Consider API timeouts in any custom automation you might be using. If a request does time out due to latency issues, you can configure if the admission controller will fail open, allowing the request to reach the API server, or fail closed, blocking the requested operation. This setting is configured during installation and you can verify the setting by selecting *Platform Configuration* -> *Clusters* and checking the *Admission controller failure policy*. +* If you are using {product-title-short} in a continuous development (CD) tool, set the admission controller failure policy to fail closed, so that your CD tool handles the enforcement. +* You can use admission controller enforcement for the following items: ** Options in the pod `securityContext` ** Deployment configurations ** Image components and vulnerabilities -* You cannot use admission controller enforcement for the following items: -** Any runtime behavior, such as processes -** Any policies based on port exposure -* The admission controller might fail if there are connectivity issues between the Kubernetes or {ocp} API server and {product-title-short} Sensor. -To resolve this issue, delete the `ValidatingWebhookConfiguration` object as described in "Disabling admission controller enforcement". -//link to Disable admission controller enforcement +** User-initiated container commands such as `pod exec` and `port forward` * If you have deploy stage enforcement enabled for a policy and you enable the admission controller, {product-title-short} attempts to block deployments that violate the policy. If a noncompliant deployment is not rejected by the admission controller, for example, in case of a timeout, {product-title-short} still applies other deploy stage enforcement mechanisms, such as scaling to zero replicas. diff --git a/modules/update-admission-controller.adoc b/modules/update-admission-controller.adoc deleted file mode 100644 index 3665f2c07b54..000000000000 --- a/modules/update-admission-controller.adoc +++ /dev/null @@ -1,91 +0,0 @@ -// Module included in the following assemblies: -// -// * upgrade/upgrade-from-44.adoc -:_mod-docs-content-type: PROCEDURE -[id="update-admission-controller_{context}"] -= Updating Admission controller - -[role="_abstract"] -{product-title} 3.0.55 includes changes that affect admission controller integration. Therefore, if you are using an admission controller or want to take advantage of the admission controller integration’s new features, you must run some additional commands to upgrade the secured cluster. - -[IMPORTANT] -==== -If you are upgrading from a {product-title} version between 3.0.44 and 3.0.54, and you are not using an Admission controller and automatic upgrades, then you must manually redeploy Sensor on all clusters. -==== - -.Prerequisites - -* You must be using the {product-title} Admission controller. To check if you are using the Admission controller, run the following command: -+ -[source,terminal] ----- -$ oc get validatingwebhookconfiguration stackrox <1> ----- -<1> If you use Kubernetes, enter `kubectl` instead of `oc`. -+ -If you get an error, it means that you are not using an admission controller. - -.Procedure - -. Delete the existing validating webhook configuration: -+ -[source,terminal] ----- -$ oc delete validatingwebhookconfiguration stackrox <1> ----- -<1> If you use Kubernetes, enter `kubectl` instead of `oc`. -+ -[TIP] -==== -If you want to allow any additional admission controller features moving forward, go to the *Clusters* configuration view in the {product-title-short} portal, select the cluster you are updating, and enable the appropriate options. -==== -. Obtain a new Sensor bundle for the secured cluster: -+ -[source,terminal] ----- -$ roxctl sensor get-bundle ----- -. Unzip the Sensor bundle and open the extracted directory. -. Create the `admission-control` deployment and related objects: -+ -[source,terminal] ----- -$ oc -n stackrox apply -f admission-controller-scc.yaml <1> ----- -<1> If you use Kubernetes, enter `kubectl` instead of `oc`. -+ -[source,terminal] ----- -$ oc -n stackrox apply -f admission-controller-secret.yaml <1> ----- -<1> If you use Kubernetes, enter `kubectl` instead of `oc`. -+ -[source,terminal] ----- -$ oc -n stackrox apply -f admission-controller-rbac.yaml <1> ----- -<1> If you use Kubernetes, enter `kubectl` instead of `oc`. -+ -[source,terminal] ----- -$ oc -n stackrox apply -f admission-controller-netpol.yaml <1> ----- -<1> If you use Kubernetes, enter `kubectl` instead of `oc`. -+ -[source,terminal] ----- -$ oc -n stackrox apply -f admission-controller-pod-security.yaml <1> ----- -<1> If you use Kubernetes, enter `kubectl` instead of `oc`. -+ -[source,terminal] ----- -$ oc -n stackrox apply -f admission-controller.yaml <1> ----- -<1> If you use Kubernetes, enter `kubectl` instead of `oc`. - -[WARNING] -==== -By default, the `--listenOnEvents` option is set to `false` during the upgrade. It controls the deployment of the admission controller webhook, which listens for `exec` and `portforward` events. If you are using {ocp} version 3.11, do not set the `--listenOnEvents` option to `true`. Because these events are not available for {ocp} 3.11, enabling them causes errors. For more information, see link:https://access.redhat.com/support/policy/updates/rhacs[{product-title} Support Policy]. -==== -//changes in PR#100022 \ No newline at end of file diff --git a/modules/update-validating-webhook-configuration.adoc b/modules/update-validating-webhook-configuration.adoc deleted file mode 100644 index bcb80cd5c87f..000000000000 --- a/modules/update-validating-webhook-configuration.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// Module included in the following assemblies: -// -// * upgrade/upgrade-roxctl.adoc -:_mod-docs-content-type: PROCEDURE -[id="update-validating-webhook-configuration_{context}"] -= Update ValidatingWebhookConfiguration - -[role="_abstract"] -Earlier {product-title-short} versions included a wrong entry in the ValidatingWebhookConfiguration. To fix it, you must update the ValidatingWebhookConfiguration. - -.Procedure - -* If you have enabled `listenOnEvents` in your Admission controller, you must run the following command: -+ -[source,terminal] ----- -$ oc patch validatingwebhookconfiguration stackrox -p '{"webhooks":[{"name": "k8sevents.stackrox.io", "rules": [{"apiGroups": ["*"], "apiVersions": ["*"], "operations": ["CONNECT"], "resources": ["pods", "pods/exec", "pods/portforward"]}]}]}' <1> ----- -<1> If you use Kubernetes, enter `kubectl` instead of `oc`. -//Changes in PR #100022 \ No newline at end of file diff --git a/modules/validatingwebhookconfiguration-yaml-changes.adoc b/modules/validatingwebhookconfiguration-yaml-changes.adoc deleted file mode 100644 index c15e7d143c79..000000000000 --- a/modules/validatingwebhookconfiguration-yaml-changes.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// Module included in the following assemblies: -// -// * operating/manage_security_policies/about-security-policies.adoc -:_mod-docs-content-type: CONCEPT -[id="validatingwebhookconfiguration-yaml-changes_{context}"] -= ValidatingWebhookConfiguration YAML file changes - -With {product-title} you can enforce security policies on: - -* Object creation -* Object update -* Pod execution -* Pod port forward - -== If Central or Sensor is unavailable -The admission controller requires an initial configuration from Sensor to work. -Kubernetes or {ocp} saves this configuration, and it remains accessible even if all admission control service replicas are rescheduled onto other nodes. -If this initial configuration exists, the admission controller enforces all configured deploy-time policies. - -If Sensor or Central becomes unavailable later: - -* you will not be able to run image scans, or query information about cached image scans. -However, admission controller enforcement still functions based on the available information gathered before the timeout expires, even if the gathered information is incomplete. -* you will not be able to disable the admission controller from the {product-title-short} portal or modify enforcement for an existing policy as the changes will not get propagated to the admission control service. - -[NOTE] -==== -If you need to disable admission control enforcement, you can delete the validating webhook configuration by running the following command: - -* On {ocp}: -+ -[source,terminal] ----- -$ oc delete ValidatingWebhookConfiguration/stackrox ----- -* On Kubernetes: -+ -[source,terminal] ----- -$ kubectl delete ValidatingWebhookConfiguration/stackrox ----- -==== - -== Make the admission controller more reliable - -Red{nbsp}Hat recommends that you schedule the admission control service on the control plane and not on worker nodes. -The deployment YAML file includes a soft preference for running on the control plane, however it is not enforced. - -By default, the admission control service runs 3 replicas. -To increase reliability, you can increase the replicas by running the following command: - -[source,terminal] ----- -$ oc -n stackrox scale deploy/admission-control --replicas= <1> ----- -<1> If you use Kubernetes, enter `kubectl` instead of `oc`. - -== Using with the roxctl CLI - -You can use the following options when you generate a Sensor deployment YAML file: - -* `--admission-controller-listen-on-updates`: If you use this option, {product-title} generates a Sensor bundle with a `ValidatingWebhookConfiguration` pre-configured to receive update events from the Kubernetes or {ocp} API server. -* `--admission-controller-enforce-on-updates`: If you use this option, {product-title} configures Central such that the admission controller also enforces security policies object updates. - -Both these options are optional, and are `false` by default. diff --git a/operating/manage_security_policies/about-security-policies.adoc b/operating/manage_security_policies/about-security-policies.adoc index 0c44de12cd99..c176567802a0 100644 --- a/operating/manage_security_policies/about-security-policies.adoc +++ b/operating/manage_security_policies/about-security-policies.adoc @@ -20,6 +20,11 @@ include::modules/policy-evaluation-engine.adoc[leveloffset=+1] include::modules/policy-enforcement-about.adoc[leveloffset=+1] +[role="_additional-resources"] +.Additional resources + +* xref:../../operating/manage_security_policies/use-admission-controller-enforcement.adoc#understand-admission-controller-enforcement_use-admission-controller-enforcement[Understanding admission controller enforcement] + include::modules/policy-enforcement-build-stage.adoc[leveloffset=+2] include::modules/policy-enforcement-deploy.adoc[leveloffset=+2] @@ -34,7 +39,6 @@ include::modules/policy-enforcement-soft.adoc[leveloffset=+3] include::modules/policy-enforcement-runtime.adoc[leveloffset=+2] - //RHACS Policy Structure include::modules/policy-structure.adoc[leveloffset=+1] diff --git a/operating/manage_security_policies/custom-security-policies.adoc b/operating/manage_security_policies/custom-security-policies.adoc index 931629cbf4e3..770b0958efc2 100644 --- a/operating/manage_security_policies/custom-security-policies.adoc +++ b/operating/manage_security_policies/custom-security-policies.adoc @@ -36,3 +36,4 @@ include::modules/create-policy-from-risk-view.adoc[leveloffset=+1] //Modifying existing security policies include::modules/modify-existing-security-policies.adoc[leveloffset=+1] +include::modules/disable-associated-policies.adoc[leveloffset=+2] diff --git a/operating/manage_security_policies/use-admission-controller-enforcement.adoc b/operating/manage_security_policies/use-admission-controller-enforcement.adoc index 0948b04fcb9f..1a27cf511751 100644 --- a/operating/manage_security_policies/use-admission-controller-enforcement.adoc +++ b/operating/manage_security_policies/use-admission-controller-enforcement.adoc @@ -8,22 +8,32 @@ toc::[] [role="_abstract"] {product-title-short} works with link:https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/[Kubernetes admission controllers] and link:https://docs.openshift.com/container-platform/4.19/architecture/admission-plug-ins.html[{ocp} admission plugins] to allow you to enforce security policies before Kubernetes or {ocp} creates workloads, for example, deployments, daemon sets or jobs. The {product-title-short} admission controller prevents users from creating or updating workloads that violate policies that you configure in {product-title-short}. -{product-title-short} uses the `ValidatingAdmissionWebhook` controller to verify that the resource being provisioned complies with the specified security policies. -To handle this, {product-title-short} creates a `ValidatingWebhookConfiguration` which contains multiple webhook rules. - -When the Kubernetes or {ocp} API server receives a request that matches one of the webhook rules, the API server sends an `AdmissionReview` request to {product-title-short}. {product-title-short} then accepts or rejects the request based on the configured security policies. - -//There will be additional changes to these modules as part of 4.9 include::modules/understand-admission-controller-enforcement.adoc[leveloffset=+1] include::modules/enable-admission-controller-enforcement.adoc[leveloffset=+1] +[role="_additional-resources"] +.Additional resources + +* xref:../../installing/installing_ocp/install-secured-cluster-ocp.adoc#install-secured-cluster-ocp[Installing Secured Cluster services for RHACS on Red Hat OpenShift] +* xref:../../installing/installing_other/install-secured-cluster-other.adoc#install-secured-cluster-other[Installing Secured Cluster services for RHACS on other platforms] + +include::modules/enable-admission-controller-enforcement-existing-cluster.adoc[leveloffset=+1] + include::modules/bypass-admission-controller-enforcement.adoc[leveloffset=+1] include::modules/disable-admission-controller-enforcement.adoc[leveloffset=+1] -include::modules/disable-associated-policies.adoc[leveloffset=+2] +include::modules/admission-controller-failure-policy.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources + +* xref:../../installing/installing_ocp/install-secured-cluster-ocp.adoc#install-secured-cluster-ocp[Installing Secured Cluster services for RHACS on Red Hat OpenShift] +* xref:../../installing/installing_other/install-secured-cluster-other.adoc#install-secured-cluster-other[Installing Secured Cluster services for RHACS on other platforms] + +include::modules/admission-controller-failure-policy-changing.adoc[leveloffset=+1] + + -include::modules/disable-the-webhook.adoc[leveloffset=+2] -include::modules/validatingwebhookconfiguration-yaml-changes.adoc[leveloffset=+1] \ No newline at end of file