Merge pull request #93465 from openshift-cherrypick-robot/cherry-pick-91676-to-rhacs-docs-4.7

kcarmichael08 · web-flow · commit 92fa81b4f517 · 2025-05-15T16:02:45.000-04:00
[rhacs-docs-4.7] ROX-28835: Add info about configuring scanner v4
diff --git a/installing/installing_ocp/install-central-ocp.adoc b/installing/installing_ocp/install-central-ocp.adoc
@@ -59,6 +59,7 @@ You can install {product-title-short} on your cluster without any customizations
 
 include::modules/adding-helm-repository.adoc[leveloffset=+3]
 include::modules/acs-quick-install-using-helm.adoc[leveloffset=+3]
+include::modules/automatically-generated-ca.adoc[leveloffset=+3]
 
 [id="install-using-helm-customizations-ocp"]
 === Install Central using Helm charts with customizations
diff --git a/modules/automatically-generated-ca.adoc b/modules/automatically-generated-ca.adoc
@@ -0,0 +1,34 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_ocp/install-central-ocp.adoc
+// * installing/installing_other/install-central-other.adoc
+:_mod-docs-content-type: CONCEPT
+[id="automatically-generated-ca_{context}"]
+= Retrieving the automatically generated certificate authority
+
+When installing {product-title-short}, a certificate authority (CA) is automatically generated and stored in a Kubernetes secret on the cluster. If you later change your installation by using Helm, you might need to supply this CA. For example, enabling Scanner V4 requires that you provide this CA.
+
+The automatically generated CA is stored in a secret that is usually named similar to `stackrox-generated-_suffix_`, where _suffix_ is a randomly generated string.
+
+To retrieve the CA and export it to a `generated-values.yaml` file when needed for the `helm upgrade` command, for example, run the following command:
+
+[source,terminal]
+----
+$ kubectl -n <namespace> get secret stackrox-generated-<suffix> \
+  -o go-template='{{ index .data "generated-values.yaml" }}' | \
+  base64 --decode >generated-values.yaml
+----
+
+[IMPORTANT]
+====
+This file might contain sensitive data, so store it in a safe place.
+====
+
+If you are using the `helm upgrade` command after changing a configuration, you might need to supply this CA. For example, to update your system and enable Scanner V4, you run the following command:
+
+[source,terminal]
+----
+$ helm upgrade -n stackrox stackrox-central-services rhacs/central-services --reuse-values \
+  -f <path_to_generated-values.yaml> \
+  --set scannerV4.disable=false
+----
diff --git a/modules/central-configuration-options-operator.adoc b/modules/central-configuration-options-operator.adoc
@@ -123,7 +123,7 @@ Ensure that this value does not exceed the maximum number of connections support
 |===
 
 [id="scanner-settings_{context}"]
-== StackRox Scanner settings
+== StackRox Scanner settings for the Operator
 
 [cols="1,3"]
 |===
@@ -180,7 +180,7 @@ Ensure that this value does not exceed the maximum number of connections support
 |===
 
 [id="scannerv4-settings_{context}"]
-== Scanner V4 settings
+== Scanner V4 settings for the Operator
 
 [cols="1,3"]
 |===
diff --git a/modules/enabling-scanner-v4-after-helm-installation-central.adoc b/modules/enabling-scanner-v4-after-helm-installation-central.adoc
@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+//
+// * operating/examine-images-for-vulnerabilities.adoc
+:_mod-docs-content-type: PROCEDURE
+[id="enabling-scanner-v4-after-helm-installation-central_{context}"]
+= Enabling RHACS Scanner V4 for Central after Helm installation
+
+[role="_abstract"]
+Scanner V4 is not enabled by default, but you can enable Scanner V4 after installation.
+
+.Procedure
+
+. On the cluster where Central is installed, run the following command, using the instructions in "Changing configuration options after deploying the central-services Helm chart" if you need more information:
++
+[source,terminal]
+----
+$ helm upgrade -n stackrox \
+    stackrox-central-services rhacs/central-services \
+    --reuse-values \
+    -f <path_to_values_public.yaml> \
+    -f <path_to_generated-values.yaml> \// <1>
+    --set scannerV4.disable=false
+----
+<1> When updating the system and installing a new component, you must provide the internal CA. See "Retrieving the automatically generated certificate authority".
+
diff --git a/modules/enabling-scanner-v4-after-helm-installation-secured-cluster.adoc b/modules/enabling-scanner-v4-after-helm-installation-secured-cluster.adoc
@@ -0,0 +1,28 @@
+// Module included in the following assemblies:
+//
+// * operating/examine-images-for-vulnerabilities.adoc
+:_mod-docs-content-type: PROCEDURE
+[id="enabling-scanner-v4-after-helm-installation-secured-cluster_{context}"]
+= Enabling RHACS Scanner V4 on the secured cluster after Helm installation
+
+[role="_abstract"]
+Scanner V4 is not enabled by default, but you can enable Scanner V4 after installation.
+
+.Prerequisites
+
+* You set up Central and the secured cluster by using an init bundle or CRS so that they can communicate with each other.
+
+.Procedure
+
+. On the secured cluster, run the following command, using the instructions in "Configuring the secured-cluster-services Helm chart with customizations" if you need more information:
++
+[source,terminal]
+----
+$ helm upgrade -n stackrox \
+    stackrox-central-services rhacs/secured-cluster-services \
+    --reuse-values \
+    -f <path_to_values_public.yaml> \
+    -f <path_to_generated-values.yaml> \// <1>
+    --set scannerV4.disable=false
+----
+<1> When updating the system and installing a new component, you must provide the internal CA. See "Retrieving the automatically generated certificate authority".
diff --git a/modules/enabling-scanner-v4-after-operator-installation-central.adoc b/modules/enabling-scanner-v4-after-operator-installation-central.adoc
@@ -0,0 +1,23 @@
+// Module included in the following assemblies:
+//
+// * operating/examine-images-for-vulnerabilities.adoc
+:_mod-docs-content-type: PROCEDURE
+[id="enabling-scanner-v4-after-operator-installation-central_{context}"]
+= Enabling RHACS Scanner V4 for Central after Operator installation
+
+[role="_abstract"]
+Scanner V4 is not enabled by default. If you did not enable it during installation, you can enable it after installation.
+
+.Procedure
+
+. In the cluster where Central is installed, in the console, click *Operators* -> *Installed Operators* and select the {product-title-short} Operator.
+. Click *Central* in the menu bar.
+. Click the name of the cluster where Central was installed. The default value is *stackrox-central-services*.
+. Click the *YAML* tab.
+. Edit the YAML file as shown in the following example:
++
+[source,yaml]
+----
+  scannerV4:
+    scannerComponent: Enabled
+----
diff --git a/modules/enabling-scanner-v4-after-operator-installation-secured-cluster.adoc b/modules/enabling-scanner-v4-after-operator-installation-secured-cluster.adoc
@@ -0,0 +1,27 @@
+// Module included in the following assemblies:
+//
+// * operating/examine-images-for-vulnerabilities.adoc
+:_mod-docs-content-type: PROCEDURE
+[id="enabling-scanner-v4-after-operator-installation-secured-cluster_{context}"]
+= Enabling RHACS Scanner V4 on the secured cluster after Operator installation
+
+[role="_abstract"]
+Scanner V4 is not enabled by default. If you did not enable it during installation, you can enable it after installation.
+
+.Prerequisite
+
+* You set up Central and the secured cluster by using an init bundle or CRS so that they can communicate with each other.
+
+.Procedure
+
+. In the secured cluster, click *Operators* -> *Installed Operators* and select the {product-title-short} Operator.
+. Click *Secured Cluster* in the menu bar.
+. Click the default cluster name, *stackrox-secured-cluster-services*, or the name that you entered during installation.
+. Click the *YAML* tab.
+. Edit the YAML file as shown in the following example:
++
+[source,yaml]
+----
+  scannerV4:
+    scannerComponent: AutoSense
+----
diff --git a/modules/enabling-scanner-v4-helm-central.adoc b/modules/enabling-scanner-v4-helm-central.adoc
@@ -0,0 +1,37 @@
+// Module included in the following assemblies:
+//
+// * operating/examine-images-for-vulnerabilities.adoc
+:_mod-docs-content-type: PROCEDURE
+[id="enabling-scanner-v4-helm-central_{context}"]
+= Enabling RHACS Scanner V4 for Central when installing with Helm
+
+[role="_abstract"]
+Scanner V4 is not enabled by default, but you can enable it during installation.  Use this procedure to understand the steps you must follow when enabling Scanner V4. However, you might need to refer to the detailed installation documentation in "Additional resources", depending on the configuration of your other components.
+
+.Procedure
+
+. On the cluster where Central is installed, run the following command, using the instructions in "Install Central using Helm charts with customizations" if you need more information:
++
+[source,terminal]
+----
+$ helm install -n stackrox --create-namespace \
+    stackrox-central-services rhacs/central-services \
+    --set scannerV4.disable=false \
+    -f <path_to_values_public.yaml> -f <path_to_values_private.yaml>
+----
++
+.Example output
+[source,terminal]
+----
+Central Services Configuration Summary:
+
+    Stackrox Version:                            4.7.1
+    Kubernetes Version:                          v1.31.6
+    Kubernetes Namespace:                        stackrox
+    Helm Release Name:                           stackrox-central-services
+    OpenShift Cluster:                           4
+    Scanner V4:                                  enabled
+    Scanner V4 DB Volume:                        PVC (scanner-v4-db)
+----
++
+. Configure your init bundle or cluster registration secret (CRS) so that Central and the secured cluster can communicate. For more information, see "Generating and applying an init bundle or cluster registration secret for RHACS on Red Hat OpenShift" or "Generating and applying an init bundle or cluster registration secret for RHACS on other platforms".
diff --git a/modules/enabling-scanner-v4-helm-secured-cluster.adoc b/modules/enabling-scanner-v4-helm-secured-cluster.adoc
@@ -0,0 +1,30 @@
+// Module included in the following assemblies:
+//
+// * operating/examine-images-for-vulnerabilities.adoc
+:_mod-docs-content-type: PROCEDURE
+[id="enabling-scanner-v4-helm-secured-cluster_{context}"]
+= Enabling RHACS Scanner V4 on the secured cluster when installing with Helm
+
+[role="_abstract"]
+Scanner V4 is not enabled by default, but you can enable it during installation.  Use this procedure to understand the steps you must follow when enabling Scanner V4. However, you might need to refer to the detailed installation documentation in "Additional resources", depending on the configuration of your other components.
+
+.Prerequisite
+
+* You set up Central and the secured cluster by using an init bundle or CRS so that they can communicate with each other.
+
+.Procedure
+
+. On the secured cluster, run the following command, using the instructions in "Configuring the secured-cluster-services Helm chart with customizations" if you need more information:
++
+[source,terminal]
+----
+$ helm install -n stackrox --create-namespace \
+    stackrox-secured-cluster-services rhacs/secured-cluster-services \
+    --set-file crs.file=<crs_file_name.yaml> \
+    -f <path_to_pull_secret.yaml> \
+    -f <path_to_values_public.yaml> -f <path_to_values_private.yaml> \
+    --set clusterName=<name_of_the_secured_cluster> \
+    --set centralEndpoint=<endpoint_of_central_service> \
+    --set scanner.disable=false \
+    --set scannerV4.disable=false
+----
diff --git a/modules/enabling-scanner-v4-operator-central.adoc b/modules/enabling-scanner-v4-operator-central.adoc
@@ -0,0 +1,22 @@
+// Module included in the following assemblies:
+//
+// * operating/examine-images-for-vulnerabilities.adoc
+:_mod-docs-content-type: PROCEDURE
+[id="enabling-scanner-v4-operator-central_{context}"]
+= Enabling RHACS Scanner V4 for Central when installing with the Operator
+
+[role="_abstract"]
+Scanner V4 is not enabled by default, but you can enable it during installation. Use this procedure to understand the steps you must follow when enabling Scanner V4. However, you might need to refer to the detailed installation documentation in "Additional resources", depending on the configuration of your other components.
+
+.Procedure
+
+. On the cluster where Central is installed, follow the installation procedures as described in "Installing Central using the Operator method". Choose one of these methods to enable Scanner V4:
+* As described in that procedure, when configuring the available options for Central, go to the *Scanner V4 Component Settings* section and in the *Scanner V4 Component* menu, select *Enabled*.
+* In the Central custom resource (CR) YAML, configure the following parameter:
++
+[source,yaml]
+----
+  scannerV4:
+    scannerComponent: Enabled
+----
+. Configure your init bundle or cluster registration secret (CRS) to allow communication between Central and the secured cluster. For more information, see "Generating and applying an init bundle or cluster registration secret for RHACS on Red Hat OpenShift".
diff --git a/modules/enabling-scanner-v4-operator-secured-cluster.adoc b/modules/enabling-scanner-v4-operator-secured-cluster.adoc
@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+//
+// * operating/examine-images-for-vulnerabilities.adoc
+:_mod-docs-content-type: PROCEDURE
+[id="enabling-scanner-v4-operator-secured-cluster_{context}"]
+= Enabling RHACS Scanner V4 on the secured cluster when installing with the Operator
+
+[role="_abstract"]
+Scanner V4 is not enabled by default, but you can enable it during installation. Use this procedure to understand the steps you must follow when enabling Scanner V4. However, you might need to refer to the detailed installation documentation in "Additional resources", depending on the configuration of your other components.
+
+.Prerequisite
+
+* You set up Central and the secured cluster by using an init bundle or CRS so that they can communicate with each other.
+
+.Procedure
+
+. On the secured cluster, follow the installation procedures as described in "Installing {product-title-short} on secured clusters by using the Operator". Choose one of these methods to enable Scanner V4:
+* In the *Scanner V4 Component Settings* section, in the *Scanner V4 Component* menu, select *AutoSense*.
+* In the SecuredCluster CR YAML, configure the following parameter:
++
+[source,yaml]
+----
+  scannerV4:
+    scannerComponent: AutoSense
+----
diff --git a/modules/secured-cluster-configuration-options-operator.adoc b/modules/secured-cluster-configuration-options-operator.adoc
@@ -83,7 +83,7 @@ The default value is `DoNotScanInline`.
 |===
 
 [id="scanner-configuration-settings_{context}"]
-== Scanner configuration
+== Scanner configuration settings for the Operator
 
 Use Scanner configuration settings to modify the local cluster scanner for the integrated OpenShift image registry.
 
diff --git a/operating/examine-images-for-vulnerabilities.adoc b/operating/examine-images-for-vulnerabilities.adoc
@@ -59,14 +59,75 @@ It might fail to identify installed components or vulnerabilities if the final i
 
 |===
 
+//About Scanner V4
 include::modules/consolidated-scanner.adoc[leveloffset=+1]
 
+[id="enabling_scanner_v4_{context}"]
+== Enabling Scanner V4
+
+Scanner V4 is not enabled by default, but you can enable Scanner V4 during or after installation. Because the StackRox Scanner provides information about Kubernetes system platform vulnerabilities and non-{op-system} vulnerabilities, you must keep the StackRox scanner enabled to continue receiving reports for that data.
+
+Scanner V4 is enabled in Central and is not required in secured clusters, unless you have specific needs, such as the need to access image registries that are located outside of the cluster and are not accessible from Central. For example, you enable Scanner V4 on secured clusters when using the OpenShift image registry, or in a {product-title-managed-short} system that only allows traffic to the registry from within its own firewalls. It is also required when using registry mirroring. For more information, see xref:../operating/examine-images-for-vulnerabilities.adoc#accessing-delegated-image-scanning_examine-images-for-vulnerabilities[Accessing delegated image scanning].
+
+[id="enabling-scanner-v4-operator_{context}"]
+=== Enabling Scanner V4 when installing by using the Operator
+
+To use Scanner V4, you can enable it during installation on the cluster where Central is installed. Optionally, you can enable it on secured clusters during installation.
+
+include::modules/enabling-scanner-v4-operator-central.adoc[leveloffset=+3]
+include::modules/enabling-scanner-v4-operator-secured-cluster.adoc[leveloffset=+3]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../installing/installing_ocp/install-central-ocp.adoc#install-central-operator_install-central-ocp[Installing Central using the Operator method]
+* xref:../installing/installing_ocp/install-secured-cluster-ocp.adoc#installing-sc-operator[Installing {product-title-short} on secured clusters by using the Operator]
+* xref:../installing/installing_ocp/install-central-config-options-ocp.adoc#scannerv4-settings_install-central-config-options-ocp[Scanner V4 settings for the Operator]
+* xref:../installing/installing_ocp/init-bundle-ocp.adoc#init-bundle-ocp[Generating and applying an init bundle or cluster registration secret for RHACS on Red Hat OpenShift]
+
+[id="enabling-scanner-v4-helm_{context}"]
+=== Enabling Scanner V4 when installing by using Helm
+
+To use Scanner V4, you can enable it during installation on the cluster where Central is installed. Optionally, you can enable it on secured clusters during installation.
+
+include::modules/enabling-scanner-v4-helm-central.adoc[leveloffset=+3]
+include::modules/enabling-scanner-v4-helm-secured-cluster.adoc[leveloffset=+3]
+
 [role="_additional-resources"]
 .Additional resources
 
-* xref:../installing/installing_ocp/install-central-config-options-ocp.adoc#scannerv4-settings_install-central-config-options-ocp[Scanner V4 settings for installing {product-title-short} for {ocp} by using the Operator]
-* xref:../installing/installing_ocp/install-central-ocp.adoc#central-services-public-configuration-file-scannerv4_install-central-ocp[Scanner V4 settings for installing {product-title-short} for {ocp} by using Helm]
-* xref:../installing/installing_other/install-central-other.adoc#central-services-public-configuration-file-scannerv4_install-central-other[Scanner V4 settings for installing {product-title-short} for Kubernetes by using Helm]
+* xref:../installing/installing_ocp/install-central-ocp.adoc#install-using-helm-customizations-ocp[Install Central using Helm charts with customizations]
+* xref:../installing/installing_ocp/install-secured-cluster-ocp.adoc#configure-secured-cluster-services-helm-chart-customizations[Configuring the secured-cluster-services Helm chart with customizations ({ocp})]
+* xref:../installing/installing_other/install-secured-cluster-other.adoc#configure-secured-cluster-services-helm-chart-customizations-other[Configuring the secured-cluster-services Helm chart with customizations (Kubernetes)]
+* xref:../installing/installing_ocp/install-central-ocp.adoc#central-services-public-configuration-file-scannerv4_install-central-ocp[Scanner V4 settings for installing {product-title-short} on Central by using Helm ({ocp})]
+* xref:../installing/installing_other/install-central-other.adoc#central-services-public-configuration-file-scannerv4_install-central-other[Scanner V4 settings for installing {product-title-short} on Central by using Helm (Kubernetes)]
+
+[id="enabling-scanner-v4-after-installation-operator_{context}"]
+=== Enabling Scanner V4 after installing by using the Operator
+
+To use Scanner V4, you can enable it after installation on the cluster where Central is installed. Optionally, you can enable it on secured clusters after installation.
+
+include::modules/enabling-scanner-v4-after-operator-installation-central.adoc[leveloffset=+3]
+
+include::modules/enabling-scanner-v4-after-operator-installation-secured-cluster.adoc[leveloffset=+3]
+
+[id="enabling-scanner-v4-after-installation-helm_{context}"]
+=== Enabling Scanner V4 after installing by using Helm
+
+To use Scanner V4, you can enable it after installation on the cluster where Central is installed. Optionally, you can enable it on secured clusters after installation.
+
+include::modules/enabling-scanner-v4-after-helm-installation-central.adoc[leveloffset=+3]
+
+include::modules/enabling-scanner-v4-after-helm-installation-secured-cluster.adoc[leveloffset=+3]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../installing/installing_ocp/install-central-ocp.adoc#change-config-options-after-deployment-central-services_install-central-ocp[Changing configuration options after deploying the central-services Helm chart]
+* xref:../installing/installing_ocp/install-central-ocp.adoc#automatically-generated-ca_install-central-ocp[Retrieving the automatically generated certificate authority]
+* xref:../upgrading/upgrade-helm.adoc#upgrade-helm[Upgrading using Helm charts]
+
+//roxctl cli?
 
 include::modules/scanning-images.adoc[leveloffset=+1]
 
