diff --git a/modules/install-acs-operator-cloud.adoc b/modules/install-acs-operator-cloud.adoc index 8fb936a58702..daa3cc62cfc9 100644 --- a/modules/install-acs-operator-cloud.adoc +++ b/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 diff --git a/modules/prepare-operator-upgrades.adoc b/modules/prepare-operator-upgrades.adoc index 86a91eb24736..7d964a74b39f 100644 --- a/modules/prepare-operator-upgrades.adoc +++ b/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: * 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`. \ No newline at end of file +* 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". diff --git a/modules/remove-central-attached-pv-helm.adoc b/modules/remove-central-attached-pv-helm.adoc index fc0b618f8565..c9fe951decb7 100644 --- a/modules/remove-central-attached-pv-helm.adoc +++ b/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. diff --git a/modules/remove-central-attached-pv-operator.adoc b/modules/remove-central-attached-pv-operator.adoc index 48cb5af3bd79..2be06837a799 100644 --- a/modules/remove-central-attached-pv-operator.adoc +++ b/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. diff --git a/modules/remove-central-attached-pv-overview.adoc b/modules/remove-central-attached-pv-overview.adoc index d52f4cb76107..848f0ec6e276 100644 --- a/modules/remove-central-attached-pv-overview.adoc +++ b/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] ==== diff --git a/modules/remove-central-attached-pv-roxctl.adoc b/modules/remove-central-attached-pv-roxctl.adoc index f6246951c9a3..c6ff65a82900 100644 --- a/modules/remove-central-attached-pv-roxctl.adoc +++ b/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. diff --git a/modules/updates-and-upgrades.adoc b/modules/updates-and-upgrades.adoc index bdaf79b56fb1..a1419924e137 100644 --- a/modules/updates-and-upgrades.adoc +++ b/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. \ No newline at end of file +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. \ No newline at end of file diff --git a/upgrading/upgrade-helm.adoc b/upgrading/upgrade-helm.adoc index 570c0d9df3e6..d89c8ba3b557 100644 --- a/upgrading/upgrade-helm.adoc +++ b/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] ==== diff --git a/upgrading/upgrade-operator.adoc b/upgrading/upgrade-operator.adoc index ed1b5c62a3fc..936f264f4439 100644 --- a/upgrading/upgrade-operator.adoc +++ b/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] @@ -25,7 +20,7 @@ include::modules/change-collection-method.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] @@ -38,6 +33,7 @@ include::modules/operator-upgrade-modify-central-custom-resource-tech-preview.ad 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] @@ -58,14 +54,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] diff --git a/upgrading/upgrade-roxctl.adoc b/upgrading/upgrade-roxctl.adoc index 4cbc2f401663..7c6062a4806f 100644 --- a/upgrading/upgrade-roxctl.adoc +++ b/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} to the latest version, you must perform the following: