Updates to upgrade procedures

modules/install-acs-operator-cloud.adoc

@@ -30,6 +30,8 @@ Using the OperatorHub provided with {ocp} is the easiest way to install the {pro
 If you select automatic updates, when a new version of the Operator is available, Operator Lifecycle Manager (OLM) automatically upgrades the running instance of your Operator.
 +
 If you select manual updates, when a newer version of the Operator is available, OLM creates an update request. As a cluster administrator, you must manually approve the update request to update the Operator to the latest version.
++
+Red{nbsp}Hat recommends enabling automatic upgrades for Operator in {product-title-managed-short}. See the link:https://access.redhat.com/articles/7045053[Red Hat Advanced Cluster Security for Kubernetes Support Matrix] for more information.
 . Click *Install*.
 
 .Verification

modules/prepare-operator-upgrades.adoc

@@ -6,8 +6,8 @@
 = Preparing to upgrade
 
 [role="_abstract"]
-Before you upgrade {rh-rhacs-first} version, you must:
+Before you upgrade the {rh-rhacs-first} version, you must perform the following steps:
 
 * If you are upgrading from version 3.74, verify that you are running the latest patch release version of the {product-title-short} Operator 3.74.
 * Backup your existing Central database.
-* If the cluster you are upgrading contains the `SecuredCluster` custom resource (CR), change the collection method to `EBPF` or `CORE_BPF`.
+* If the cluster you are upgrading contains the `SecuredCluster` custom resource (CR), change the collection method to EBPF or CORE_BPF. For more information, see "Changing the collection method".

modules/remove-central-attached-pv-helm.adoc

@@ -3,7 +3,7 @@
 // * upgrading/upgrade-helm.adoc
 :_mod-docs-content-type: PROCEDURE
 [id="remove-central-attached-pv-operator_{context}"]
-= Remove Central-attached PV using Helm
+= Removing Central-attached PV using Helm
 
 [role="_abstract"]
 Remove the Central-attached persistent volume claim (PVC) `stackrox-db` to free up storage space.

modules/remove-central-attached-pv-operator.adoc

@@ -3,7 +3,7 @@
 // * upgrading/upgrade-operator.adoc
 :_mod-docs-content-type: PROCEDURE
 [id="remove-central-attached-pv-operator_{context}"]
-= Remove Central-attached PV using the {product-title-short} Operator
+= Removing Central-attached PV using the {product-title-short} Operator for {product-title-short} version 4.1 and later
 
 [role="_abstract"]
 Remove the Central-attached persistent volume claim (PVC) `stackrox-db` to free up storage space.

modules/remove-central-attached-pv-overview.adoc

@@ -3,14 +3,14 @@
 // * upgrading/upgrade-operator.adoc
 :_mod-docs-content-type: CONCEPT
 [id="remove-central-attached-pv-overview_{context}"]
-= Remove Central-attached PV
+= Removing Central-attached PV after upgrading to version 4.1 and later
 
 [role="_abstract"]
 Kubernetes and {ocp} do not delete persistent volumes (PV) automatically. When you upgrade {product-title-short} from earlier versions, the Central PV called `stackrox-db` remains mounted. However, in {product-title-short} 4.1, Central does not need the previously attached PV anymore.
 
 The PV has data and persistent files used by earlier {product-title-short} versions. You can use the PV to roll back to an earlier version before {product-title-short} 4.1. Or, if you have a large RocksDB backup bundle for Central, you can use the PV to restore that data.
 
-If you do not plan to roll back or restore from earlier RocksDB backups, you can remove the Central-attached persistent volume claim (PVC) to free up the storage.
+After you complete the upgrade to 4.1, you can remove the Central-attached persistent volume claim (PVC) to free up the storage. Only remove the PVC if you do not plan to roll back or restore from earlier RocksDB backups.
 
 [WARNING]
 ====

modules/remove-central-attached-pv-roxctl.adoc

@@ -3,7 +3,7 @@
 // * upgrading/upgrade-helm.adoc
 :_mod-docs-content-type: PROCEDURE
 [id="remove-central-attached-pv-roxctl_{context}"]
-= Remove Central-attached PV using the `roxctl` CLI
+= Removing Central-attached PV using the `roxctl` CLI
 
 [role="_abstract"]
 Remove the Central-attached persistent volume claim (PVC) `stackrox-db` to free up storage space.

modules/updates-and-upgrades.adoc

@@ -11,5 +11,8 @@ The decision regarding the need for a Service update to the Central instance and
 Customers have no control over when a Central service update occurs. For more information, see link:https://www.redhat.com/licenses/Appendix_4_Red_Hat_Online_Services_20221213.pdf[PRODUCT APPENDIX 4 RED HAT ONLINE SERVICES].
 Upgrades to the version of {rh-rhacscs-first} are considered part of the service update.
 
-The version of {product-title-managed-short} used on Secured Clusters must match the version of the Central instance of {product-title-managed-short} to ensure compatibility.
-Customers are responsible for Secured Cluster services upgrades required to maintain this version compatibility.
+Customers are responsible for timely {product-title-short} Secured Cluster services upgrades that are required to maintain compatibility with {product-title-managed-short}.
+
+Red{nbsp}Hat recommends enabling automatic upgrades for Secured Clusters that are connected to {product-title-managed-short}.
+
+See the link:https://access.redhat.com/articles/7045053[Red Hat Advanced Cluster Security for Kubernetes Support Matrix] for more information about upgrade versions.

upgrading/upgrade-helm.adoc

@@ -7,15 +7,23 @@ include::modules/common-attributes.adoc[]
 toc::[]
 
 [role="_abstract"]
-You can upgrade to the latest version of {product-title} from a supported older version. For upgrading to {product-title-short} 4.0, you must be using the latest patch release of {product-title-short} 3.74. If you are using an older version, you must first upgrade to {product-title-short} 3.74.
+You must follow a specific upgrade path for {product-title-short} depending on the release of {product-title-short} that you are running. You must also back up your Central database before updating the Helm chart and peforming the upgrade.
 
-If you have installed {product-title} by using Helm charts, to upgrade to the latest version of {product-title} you must perform the following:
+[id="upgrading-from-374_{context}"]
+== Upgrade sequence from {product-title-short} release 3.74 and earlier
 
-* Backup the Central database.
-* (Optional) Optimize Central database and Persistent Volume Claims (PVC).
-* (Optional) Generate `values-private.yaml` configuration file containing root certificates for the central-services Helm chart.
-* Update the Helm chart.
-* Run the `helm upgrade` command.
+When upgrading from earlier releases, follow this guidance:
+
+* If the release for Central is earlier than 3.74, you must upgrade to the latest 3.74 patch before upgrading to a 4.x release. See the link:https://access.redhat.com/documentation/en-us/red_hat_advanced_cluster_security_for_kubernetes/3.74/html/upgrading/index[upgrade documentation for version 3.74] for information about upgrades from earlier versions to 3.74.
+* When upgrading Helm-based installations from release 3.74, you can upgrade to any latest patch of {product-title-short} version 4.0 through 4.4. However, for full functionality, upgrade to release 4.4.
+
+If you have installed {product-title-short} by using Helm charts, to upgrade to the latest version of {product-title-short} perform the following steps:
+
+. Back up the Central database.
+. Optionally, optimize Central's database and Persistent Volume Claims (PVC).
+. Optionally, generate a `values-private.yaml` configuration file containing root certificates for the central-services Helm chart.
+. Update the Helm chart.
+. Run the `helm upgrade` command.
 
 [IMPORTANT]
 ====

upgrading/upgrade-operator.adoc

@@ -9,15 +9,10 @@ toc::[]
 [role="_abstract"]
 Upgrades through the {rh-rhacs-first} Operator are performed automatically or manually, depending on the *Update approval* option you chose at installation.
 
-{product-title-short} 4.0 includes a significant architectural change, moving Central’s database to PostgreSQL. Because of this change, {product-title-short} 4.0 Operator is published by a new subscription channel. Therefore, as part of the upgrade instructions, you must manually change the subscription channel to upgrade from {product-title-short} 3.74 to {product-title-short} 4.0.
+Follow these guidelines when upgrading:
 
-//If you installed {product-title-short} using the Operator and selected *Automatic* in the *Update approval* field, {product-title-short} is automatically updated when a new software version is released. If you selected *Manual*, you must approve subsequent Operator updates by using Operator Lifecycle Manager (OLM). For more information, see link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.12/html/operators/administrator-tasks#olm-approving-pending-upgrade_olm-upgrading-operators[Manually approving a pending Operator update].
-
-[IMPORTANT]
-====
-* Because of the database related changes introduced in {product-title-short} 4.0, even if you have selected *Automatic* in the *Update approval* field, you must manually upgrade to {product-title-short} 4.0.
-* You must be using {product-title-short} 3.74 to upgrade to {product-title-short} 4.0. If you are using a version older than 3.74, you must first upgrade to {product-title-short} 3.74 and then upgrade to {product-title-short} 4.0.
-====
+* If the version for Central is earlier than 3.74, you must upgrade to 3.74 before upgrading to a 4.x version. For upgrading Central to version 3.74, see the link:https://access.redhat.com/documentation/en-us/red_hat_advanced_cluster_security_for_kubernetes/3.74/html/upgrading/index[upgrade documentation for version 3.74].
+* When upgrading Operator-based Central deployments from version 3.74, first ensure the Operator upgrade mode is set to `Manual`. Then, upgrade the Operator to version 4.0 following the procedure in the link:https://access.redhat.com/documentation/en-us/red_hat_advanced_cluster_security_for_kubernetes/4.0/html/upgrading/upgrade-operator[upgrade documentation for version 4.0] and ensure that Central is online. After the upgrade to version 4.0 is complete, Red{nbsp}Hat recommends upgrading Central to the latest version for full functionality.
 
 include::modules/prepare-operator-upgrades.adoc[leveloffset=+1]
 include::modules/change-collection-method.adoc[leveloffset=+2]
@@ -26,7 +21,7 @@ include::modules/set-force-collection.adoc[leveloffset=+2]
 [role="_additional-resources"]
 .Additional resources
 * link:https://docs.openshift.com/container-platform/latest/operators/admin/olm-upgrading-operators.html[Updating installed Operators]
-* xref:../backup_and_restore/backing-up-acs.adoc[Backing up {product-title}]
+* xref:../backup_and_restore/backing-up-acs.adoc#backing-up-acs[Backing up {product-title}]
 
 include::modules/operator-upgrade-modify-central-custom-resource.adoc[leveloffset=+1]
 
@@ -39,6 +34,7 @@ include::modules/operator-upgrade-modify-central-custom-resource-external-db.ado
 
 include::modules/operator-upgrade-change-subscription-channel.adoc[leveloffset=+1]
 
+//these pv sections are only for 4.1 and later
 include::modules/remove-central-attached-pv-overview.adoc[leveloffset=+1]
 
 include::modules/remove-central-attached-pv-operator.adoc[leveloffset=+2]
@@ -59,14 +55,14 @@ include::modules/rollback-operator-upgrades-console.adoc[leveloffset=+2]
 [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]
-* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.12/html/operators/understanding-operators#olm-workflow[Operator Lifecycle Manager workflow]
-* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.12/html/operators/administrator-tasks#olm-approving-pending-upgrade_olm-upgrading-operators[Manually approving a pending Operator update]
+* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.15/html/operators/understanding-operators#olm-workflow[Operator Lifecycle Manager workflow]
+* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.15/html/operators/administrator-tasks#olm-approving-pending-upgrade_olm-upgrading-operators[Manually approving a pending Operator update]
 
 [id="operator-upgrade-troubleshooting_{context}"]
 == Troubleshooting Operator upgrade issues
 
 [role="_abstract"]
-Follow the instructions in this section to investigate and resolve upgrade-related issues for the {product-title-short} Operator.
+Follow these instructions to investigate and resolve upgrade-related issues for the {product-title-short} Operator.
 
 include::modules/operator-upgrade-centraldb-cannot-be-scheduled.adoc[leveloffset=+2]
 

upgrading/upgrade-roxctl.adoc

@@ -12,7 +12,7 @@ You can upgrade to the latest version of {rh-rhacs-first} from a supported older
 [IMPORTANT]
 ====
 * You need to perform the manual upgrade procedure only if you used the `roxctl` CLI to install {product-title-short}.
-* For upgrading to {product-title-short} 4.0, you must be using the latest patch release of {product-title-short} 3.74. If you are using an older version, you must first upgrade to {product-title-short} 3.74 before upgrading to {product-title-short} 4.0.
+* There are manual steps for each version upgrade that must be followed, for example, from version 3.74 to version 4.0, and from version 4.0 to version 4.1. Therefore, Red{nbsp}Hat recommends upgrading first from 3.74 to 4.0, then from 4.0 to 4.1, then 4.1 to 4.2, until the selected version is installed. For full functionality, Red{nbsp}Hat recommends upgrading to the most recent version.
 ====
 
 To upgrade {product-title-short} to the latest version, perform the following steps: