Merge pull request #94628 from kcarmichael08/ROX-29590-annotations

[ROX-29590] annotations for Operator runtime defaults

Author: kcarmichael08

cloud_service/installing_cloud_ocp/install-secured-cluster-cloud-ocp.adoc

@@ -20,6 +20,10 @@ You can install {product-title-managed-short} on your secured clusters by using
 [id="installing-sc-operator-cloud-ocp"]
 == Installing {product-title-short} on secured clusters by using the Operator
 
+To install {product-title-short} by using the Operator, you first install the Operator and then use it to install {product-title-short} on the secured cluster.
+
+include::modules/install-acs-operator-annotations.adoc[leveloffset=+2]
+
 include::modules/install-secured-cluster-operator.adoc[leveloffset=+2]
 
 [id="installing-sc-helm-cloud-ocp"]

installing/installing_ocp/install-central-ocp.adoc

@@ -21,6 +21,10 @@ You can install Central on your {ocp} or Kubernetes cluster by using one of the
 [id="install-central-using-operator"]
 == Install Central using the Operator
 
+To install Central by using the Operator, you first install the Operator and then use it to install {product-title-short} on the cluster where you want Central to be installed.
+
+include::modules/install-acs-operator-annotations.adoc[leveloffset=+2]
+
 include::modules/install-acs-operator.adoc[leveloffset=+2]
 
 include::modules/install-central-operator.adoc[leveloffset=+2]

installing/installing_ocp/install-secured-cluster-ocp.adoc

@@ -17,6 +17,10 @@ You can install {product-title-short} on your secured clusters by using one of t
 [id="installing-sc-operator"]
 == Installing {product-title-short} on secured clusters by using the Operator
 
+To install {product-title-short} by using the Operator, you first install the Operator and then use it to install {product-title-short} on the secured cluster.
+
+include::modules/install-acs-operator-annotations.adoc[leveloffset=+2]
+
 include::modules/install-secured-cluster-operator.adoc[leveloffset=+2]
 
 [id="installing-sc-helm"]

modules/install-acs-operator-annotations.adoc

@@ -0,0 +1,20 @@
+// Module included in the following assemblies:
+//
+// * installing/install-ocp-operator.adoc
+:_mod-docs-content-type: CONCEPT
+[id="install-acs-operator-annotations_{context}"]
+= Operator annotations used during installation
+
+[role="_abstract"]
+{product-title-short} uses annotations attached to the custom resource (CR) so that for installations performed by using the Operator, the default values for certain configuration items are decided at runtime by the Operator based on the current environment, allowing the previously configured value of an item to persist.
+
+For some configuration items, using a static default value for the installation is not ideal. Beginning with {product-title-short} version 4.8, the Operator can add annotations that are attached to the CR that you apply to clusters. These annotations allow a default decision that the Operator previously made to persist and be reapplied in the future, even if the default behavior for a fresh installation has changed. In summary, {product-title-short} uses annotations to persist runtime defaults. This means that the default value for a certain configuration setting is decided by the Operator at runtime.
+
+For example, in release 4.8 and later, if a value is not specified for enabling Scanner V4, the default behavior is to enable Scanner V4. However, if a value is configured in the CR, such as `disable`, then {product-title-short} uses that value. In the Scanner V4 example, Scanner V4 was disabled by default in version 4.7; when updating to version 4.8 by using the Operator, that disabled setting persists and Scanner V4 is disabled.
+
+Annotations are in the form `feature-defaults.platform.stackrox.io/<identifier>`. For example, `feature-defaults.platform.stackrox.io/scannerV4` is the annotation that allows the Operator to keep the default Scanner V4 enablement toggle stable during updating to {product-title-short} version 4.8.
+
+[IMPORTANT]
+====
+Do not change or delete these annotations.
+====