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

[rhacs-docs-4.7] ROX-27142: clarify automatic upgrades for secured clusters

Author: kcarmichael08

_topic_maps/_topic_map.yml

@@ -168,7 +168,7 @@ Topics:
   File: enable-alert-data-retention
 - Name: Exposing the RHACS portal over HTTP
   File: expose-portal-over-http
-- Name: Configuring automatic upgrades for secured clusters
+- Name: Configuring automatic upgrades for manifest-installed secured clusters
   File: configure-automatic-upgrades
 - Name: Configuring automatic removal of nonactive clusters
   File: configure-inactive-cluster-deletion

configuration/configure-automatic-upgrades.adoc

@@ -1,18 +1,20 @@
 [id="configure-automatic-upgrades"]
-= Configuring automatic upgrades for secured clusters
+= Configuring automatic upgrades for manifest-installed secured clusters
 include::modules/common-attributes.adoc[]
 :context: configure-automatic-upgrades
 
 toc::[]
 
 [role="_abstract"]
-You can automate the upgrade process for each secured cluster and view the upgrade status from the {product-title-short} portal.
+If you installed {product-title} by using the manifest installation method, also known as the _`roxctl` CLI method_ or the _legacy installation method_, you can automate the upgrade process for each secured cluster. You can also view the upgrade status from the {product-title-short} portal.
 
-Automatic upgrades make it easier to stay up-to-date by automating the manual task of upgrading each secured cluster.
+[NOTE]
+====
+Automatic upgrades are only available for {product-title-short} systems that were installed by using the manifest installation method. If you installed {product-title-short} by using the Operator, upgrades are controlled by using {olm-first}. If you installed {product-title-short} by using Helm charts, you must use Helm to upgrade.
+====
 
-With automatic upgrades, after you upgrade Central;  Sensor, Collector, and Compliance services in all secured clusters, automatically upgrade to the latest version.
+Automatic upgrades make it easier to stay up-to-date by automating the manual task of upgrading each secured cluster. If you have automatic upgrades enabled, and the secured cluster is configured for receiving automated upgrades, the upgrader upgrades the entire secured cluster to the same version as Central.
 
-{product-title} also enables centralized management of all your secured clusters from within the {product-title-short} portal.
 The new *Clusters* view displays information about all your secured clusters, the Sensor version for every cluster, and upgrade status messages.
 You can also use this view to selectively upgrade your secured clusters or change their configuration.
 
@@ -21,8 +23,8 @@ You can also use this view to selectively upgrade your secured clusters or chang
 * The automatic upgrade feature is enabled by default.
 * If you are using a private image registry, you must first push the Sensor and Collector images to your private registry.
 * The Sensor must run with the default RBAC permissions.
-* Automatic upgrades do not preserve any patches that you have made to any {product-title} services running in your cluster.
-However, it preserves all labels and annotations that you have added to any {product-title} object.
+* Automatic upgrades do not preserve any patches that you have made to any {product-title-short} services running in your cluster.
+However, it preserves all labels and annotations that you have added to any {product-title-short} object.
 * By default, {product-title} creates a service account called `sensor-upgrader` in each secured cluster.
 This account is highly privileged but is only used during upgrades.
 If you remove this account, Sensor does not have enough permissions, and you must complete future upgrades manually.
@@ -36,4 +38,9 @@ include::modules/automatic-upgrade-status.adoc[leveloffset=+1]
 
 include::modules/automatic-upgrade-failure.adoc[leveloffset=+1]
 
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../upgrading/upgrade-roxctl.adoc#troubleshooting-upgrader_upgrade-roxctl[Troubleshooting the cluster upgrader]
+
 include::modules/manual-upgrade-secured-clusters.adoc[leveloffset=+1]

modules/automatic-upgrade-failure.adoc

@@ -3,22 +3,22 @@
 // * configuration/configure-automatic-upgrades.adoc
 :_mod-docs-content-type: CONCEPT
 [id="automatic-upgrade-failure_{context}"]
-= Automatic upgrade failure
+= Automatic upgrade failure for manifest-installed secured clusters
 
-Sometimes, {product-title} automatic upgrades might fail to install.
+Sometimes, {product-title-short} automatic upgrades might fail to install.
 When an upgrade fails, the status message for the secured cluster changes to `Upgrade failed. Retry upgrade`.
-To view more information about the failure and understand why the upgrade failed, you can check the secured cluster row in the *Clusters* view.
+To view more information about the failure and understand why the upgrade failed, you can check the secured cluster row in the *Clusters* view. For more information, see "Troubleshooting the cluster upgrader".
 
 Some common reasons for the failure are:
 
 * The sensor-upgrader deployment might not have run because of a missing or a non-schedulable image.
 * The pre-flight checks may have failed, either because of insufficient RBAC permissions or because the cluster state is not recognizable.
 This can happen if you have edited {product-title} service configurations or the `auto-upgrade.stackrox.io/component` label is missing.
 * There might be errors in executing the upgrade. If this happens, the upgrade installer automatically attempts to roll back the upgrade.
-+
+
 [NOTE]
 ====
-Sometimes, the rollback can fail as well. For such cases view the cluster logs to identify the issue or contact support.
+Sometimes, the rollback can also fail. For these cases, view the cluster logs to identify the issue or contact support. For more information, see "Troubleshooting the cluster upgrader".
 ====
 
 After you identify and fix the root cause for the upgrade failure, you can use the *Retry Upgrade* option to upgrade your secured cluster.

modules/automatic-upgrade-status.adoc

@@ -11,7 +11,7 @@ The *Clusters* view lists all clusters and their upgrade statuses.
 |===
 |Upgrade status |Description
 
-|Up to date with Central version
+|Up to date with Central
 |The secured cluster is running the same version as Central.
 
 |Upgrade available
@@ -27,4 +27,7 @@ The *Clusters* view lists all clusters and their upgrade statuses.
 |Pre-flight checks complete
 |The upgrade is in progress. Before performing automatic upgrade, the upgrade installer runs a pre-flight check. During the pre-flight check, the installer verifies if certain conditions are satisfied and then only starts the upgrade process.
 
+|Not applicable
+|{product-title-short} cannot communicate with the cluster.
+
 |===

modules/disable-automatic-upgrades.adoc

@@ -3,7 +3,7 @@
 // * configuration/configure-automatic-upgrades.adoc
 :_mod-docs-content-type: PROCEDURE
 [id="disable-automatic-upgrades_{context}"]
-= Disabling automatic upgrades
+= Disabling automatic upgrades of manifest-installed secured clusters
 
 If you want to manage your secured cluster upgrades manually, you can disable automatic upgrades.
 

modules/enable-automatic-upgrades.adoc

@@ -3,9 +3,9 @@
 // * configuration/configure-automatic-upgrades.adoc
 :_mod-docs-content-type: PROCEDURE
 [id="enable-automatic-upgrades_{context}"]
-= Enabling automatic upgrades
+= Enabling automatic upgrades for manifest-installed secured clusters
 
-You can enable automatic upgrades for all secured clusters to automatically upgrade Collector and Compliance services in all secured clusters to the latest version.
+You can enable automatic upgrades for all secured clusters that were installed by using the manifest installation method, also known as the `roxctl` CLI method. This feature automatically upgrades Sensor, Admission Controller, Collector, and Compliance in all secured clusters to the same version as Central.
 
 .Procedure
 

modules/manual-upgrade-secured-clusters.adoc

@@ -12,6 +12,6 @@ To manually trigger upgrades for your secured clusters:
 .Procedure
 
 . In the {product-title-short} portal, go to *Platform Configuration* -> *Clusters*.
-. Select the *Upgrade available* option under the *Upgrade status* column for the cluster you want to upgrade.
-. To upgrade multiple clusters at once, select the checkboxes in the *Cluster* column for the clusters you want to update.
-. Click *Upgrade*.
+. Take one of the following actions:
+* To upgrade a single cluster, select the *Upgrade available* option under the *Sensor Upgrade* column for the cluster you want to upgrade.
+* To upgrade multiple clusters at a time, select the checkboxes next to the *Name* column for the clusters you want to update, and then click *Upgrade*.