From a3e442cb176be30ecaaf41805086dfc379ea4531 Mon Sep 17 00:00:00 2001 From: Kerry Carmichael Date: Tue, 3 Oct 2023 09:35:48 -0400 Subject: [PATCH] reorganize upgrade information --- _topic_map.yml | 10 +- .../set-rox-scanner-init-db-env-variable.adoc | 2 +- {upgrading => modules}/upgrade-helm.adoc | 18 +-- modules/upgrade-operator.adoc | 19 +++ modules/upgrade-roxctl.adoc | 26 ++++ upgrading/upgrade-374.adoc | 131 ++++++++++++++++++ upgrading/upgrade-operator.adoc | 24 ---- upgrading/upgrade-roxctl.adoc | 98 ------------- 8 files changed, 185 insertions(+), 143 deletions(-) rename {upgrading => modules}/upgrade-helm.adoc (54%) create mode 100644 modules/upgrade-operator.adoc create mode 100644 modules/upgrade-roxctl.adoc create mode 100644 upgrading/upgrade-374.adoc delete mode 100644 upgrading/upgrade-operator.adoc delete mode 100644 upgrading/upgrade-roxctl.adoc diff --git a/_topic_map.yml b/_topic_map.yml index 7e271abcf95c..9259cceba7fa 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -211,7 +211,7 @@ Topics: - Name: Configuring OpenShift Container Platform OAuth server as an identity provider File: configure-ocp-oauth - Name: Connecting Azure AD to RHACS using SSO configuration - File: connecting-azure-ad-to-rhacs-using-sso-configuration + File: connecting-azure-ad-to-rhacs-using-sso-configuration - Name: Using the system health dashboard File: use-system-health-dashboard --- @@ -265,12 +265,8 @@ Name: Upgrading Dir: upgrading Distros: openshift-acs Topics: -- Name: Upgrading using the Operator - File: upgrade-operator -- Name: Upgrading using Helm charts - File: upgrade-helm -- Name: Upgrading using the roxctl CLI - File: upgrade-roxctl +- Name: Upgrading from release 3.74 to 4.x + File: upgrade-374 --- Name: roxctl CLI Dir: cli diff --git a/modules/set-rox-scanner-init-db-env-variable.adoc b/modules/set-rox-scanner-init-db-env-variable.adoc index 1736e8818db9..83ed07c5340e 100644 --- a/modules/set-rox-scanner-init-db-env-variable.adoc +++ b/modules/set-rox-scanner-init-db-env-variable.adoc @@ -3,7 +3,7 @@ // * upgrade/upgrade-roxctl.adoc :_module-type: PROCEDURE [id="set-up-rox-scanner-env-variable_{context}"] -= Set up the `ROX_SCANNER_DB_INIT` environment variable += Setting up the `ROX_SCANNER_DB_INIT` environment variable ScannerDB's `initContainer` requires a new environment variable called `ROX_SCANNER_DB_INIT`. You must set its value to `true` before you upgrade. diff --git a/upgrading/upgrade-helm.adoc b/modules/upgrade-helm.adoc similarity index 54% rename from upgrading/upgrade-helm.adoc rename to modules/upgrade-helm.adoc index c94502b171d0..a2ab7bd53d03 100644 --- a/upgrading/upgrade-helm.adoc +++ b/modules/upgrade-helm.adoc @@ -1,10 +1,10 @@ -:_content-type: ASSEMBLY +// Module included in the following assemblies: +// +// * upgrading/upgrade-operator.adoc + +:_content-type: PROCEDURE [id="upgrade-helm"] = Upgrading using Helm charts -include::modules/common-attributes.adoc[] -:context: upgrade-helm - -toc::[] [role="_abstract"] If you have installed {product-title} by using Helm charts, to upgrade to the latest version of {product-title} you must perform the following: @@ -20,11 +20,3 @@ If you have installed {product-title} by using Helm charts, to upgrade to the la To ensure optimal functionality, use the same version for your secured-cluster-services Helm chart and central-services Helm chart. ==== -include::modules/updating-helm-repository.adoc[leveloffset=+1] - -[role="_additional-resources"] -== Additional resources - -* xref:../installing/installing_ocp/install-central-ocp.adoc#install-using-helm-no-customizations-ocp[Installing Central using Helm charts] - -* xref:../installing/installing_ocp/install-secured-cluster-ocp.adoc#installing-sc-helm[Installing {product-title-short} on secured clusters by using Helm charts] diff --git a/modules/upgrade-operator.adoc b/modules/upgrade-operator.adoc new file mode 100644 index 000000000000..fa57a55d84ff --- /dev/null +++ b/modules/upgrade-operator.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * upgrading/upgrade-operator.adoc + +:_content-type: CONCEPT +[id="upgrade-operator"] += Upgrading by using the Operator + + +[role="_abstract"] +Upgrades through the {rh-rhacs-first} Operator are performed automatically or manually, depending on the *Update approval* option you chose at installation. However, automatic upgrade is prevented for {product-title-short} version 4.0 from version 3.74. + +To prevent automatic upgrades when using the Operator, {product-title-short} 4.0 uses a new subscription channel. This update allows the {product-title-short} Operator to comply with Red Hat standards and provides consistency with other Red Hat Operators. You must explicitly change your subscription channel when upgrading. Customers who remain on the `latest` channel in the current {product-title-short} Operator channel will continue to receive 3.74 updates until it is no longer supported. + +The upgrade process includes automatically migrating the database, and requires no intervention. + +After Central is upgraded, upgrade the subscription channel on all Secured Clusters to `stable`. + +You are encouraged to evaluate the upgrade in a staging environment before pushing it to production to ensure that your unique environment does not present unforeseen issues. diff --git a/modules/upgrade-roxctl.adoc b/modules/upgrade-roxctl.adoc new file mode 100644 index 000000000000..0ec94aa37c60 --- /dev/null +++ b/modules/upgrade-roxctl.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * upgrading/upgrade-operator.adoc + +:_content-type: PROCEDURE +[id="upgrade-roxctl"] += Manually upgrading using the roxctl CLI + +[role="_abstract"] +You can upgrade to the latest version of {rh-rhacs-first} from a supported older version. + +[NOTE] +==== +You need to perform the manual upgrade procedure only if you used the `roxctl` CLI to deploy {product-title-short}. +==== + +To upgrade {product-title-short} to the latest version, you must perform the following steps: + +. Set the `ROX_SCANNER_DB_INIT` environment variable. +. Back up the Central database +. Upgrade Central. +, Upgrade the `roxctl` CLI. +. Upgrade Scanner. +. Verify that all secured clusters are upgraded. + + diff --git a/upgrading/upgrade-374.adoc b/upgrading/upgrade-374.adoc new file mode 100644 index 000000000000..d923afe42a31 --- /dev/null +++ b/upgrading/upgrade-374.adoc @@ -0,0 +1,131 @@ +:_content-type: ASSEMBLY +[id="upgrade-374"] += Upgrading from release 3.74 to 4.x +include::modules/common-attributes.adoc[] +:context: upgrade-374 + +toc::[] + +[role="_abstract"] +Upgrading from {product-title-short} 3.74 to 4.x requires some additional upgrade steps. You can upgrade by using the Operator (recommended) or by using Helm charts. Upgrading by using the `roxctl` CLI is not recommended. + +The documentation provides detailed instructions for rolling back to the previous version if necessary. Before the upgrade, back up the existing Central database following the documented backup procedure so that you can roll back to the previous version if necessary. You are encouraged to practice rolling back to the previous version in the staging environment to ensure that your backup was successful and that rolling back the previous version brings the system back to the expected operational state. + +[id="upgrade-overview"] +== Overview of upgrade procedure + +To upgrade {product-title-short} to 4.0, perform the following steps: + +. Upgrade to {product-title-short} version 3.74 if you have an earlier version installed by using one of these methods: +* xref:../upgrading/upgrade-374#upgrade-operator[Upgrade by using the Operator] +* xref:../upgrading/upgrade-374#upgrade-helm[Upgrade by using Helm charts] +* xref:../upgrading/upgrade-374#upgrade-roxctl[Upgrade by using the `roxctl` CLI] +. xref:../upgrading/upgrade-374#back-up-central-database_upgrade-374[Back up the database for Central]. +. xref:../upgrading//upgrading/upgrade-374#upgrade-central-cluster[Upgrade Central to version 4.0]. +. xref:../upgrading/upgrade-374#upgrade-secured-clusters[Upgrade secured clusters to version 4.0]. + +include::modules/back-up-central-database.adoc[leveloffset=+1] + +//Upgrading RHACS +//operator upgrades +include::modules/upgrade-operator.adoc[leveloffset=+1] +//Helm upgrades +include::modules/upgrade-helm.adoc[leveloffset=+1] +include::modules/updating-helm-repository.adoc[leveloffset=+2] + +.Additional resources + +* xref:../installing/installing_ocp/install-central-ocp.adoc#install-using-helm-no-customizations-ocp[Installing Central using Helm charts] +* xref:../installing/installing_ocp/install-secured-cluster-ocp.adoc#installing-sc-helm[Installing {product-title-short} on secured clusters by using Helm charts] + +//roxctl upgrades +include::modules/upgrade-roxctl.adoc[leveloffset=+1] + +//upgrade central + +[id="upgrade-central-cluster"] +== Upgrading the Central cluster + +After you have backed up the Central database, the next step is to upgrade the Central cluster. This step includes upgrading Central, the `roxctl` CLI, and the Scanner. + +[id="upgrade-central"] +=== Upgrading Central + +You can update Central to the latest version by downloading and deploying the updated images. + +include::modules/upgrade-central-openshift.adoc[leveloffset=+2] +include::modules/upgrade-central-kubernetes.adoc[leveloffset=+2] + +//upgrade roxctl cli +[id="upgrade-roxctl-cli"] +== Upgrading the roxctl CLI + +To upgrade the `roxctl` CLI to the latest version you must uninstall the existing version of `roxctl` CLI and then install the latest version of the `roxctl` CLI. + +include::modules/uninstall-roxctl-cli.adoc[leveloffset=+2] +include::modules/install-roxctl-cli-linux.adoc[leveloffset=+2] +include::modules/install-roxctl-cli-macos.adoc[leveloffset=+2] +include::modules/install-roxctl-cli-windows.adoc[leveloffset=+2] + +After you upgrade the `roxctl` CLI you can upgrade Scanner. + +include::modules/upgrade-scanner.adoc[leveloffset=+2] +include::modules/upgrade-scanner-roxctl-371.adoc[leveloffset=+3] + +include::modules/verify-central-cluster-upgrade.adoc[leveloffset=+2] + +[id="upgrade-secured-clusters"] +== Upgrading all secured clusters + +After upgrading Central services, you must upgrade all secured clusters. + +[IMPORTANT] +==== +* If you are using automatic upgrades: +** Update all your secured clusters by using automatic upgrades. +** Skip the instructions in this section and follow the instructions in the xref:../upgrading/upgrade-374.adoc#verify-upgrades_{context}[Verifying upgrades] and xref:../upgrading/upgrade-374.adoc#revoke-the-api-token_{context}[Revoking the API token] sections. +* If you are not using automatic upgrades, you must run the instructions in this section on all secured clusters including the Central cluster. +** To ensure optimal functionality, use the same {product-title-short} version for your secured clusters and the cluster on which Central is installed. +==== + +To complete manual upgrades of each secured cluster running Sensor, Collector, and Admission controller, follow the instructions in this section. + +include::modules/update-validating-webhook-configuration.adoc[leveloffset=+2] + +include::modules/update-other-images.adoc[leveloffset=+2] + +include::modules/verify-secured-cluster-upgrade.adoc[leveloffset=+2] + +include::modules/verify-upgrades.adoc[leveloffset=+1] + +[id="rollback"] +== Rolling back an Operator upgrade + +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]. + +To roll back an Operator upgrade, you must perform the steps described in one of the following sections. You can roll back an Operator upgrade by using the CLI or the {ocp} web console. + +include::modules/rollback-operator-upgrades-cli.adoc[leveloffset=+2] +include::modules/rollback-operator-upgrades-console.adoc[leveloffset=+2] + +.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] + +[id="rollback-central"] +== Rolling back Central + +You can roll back to a previous version of Central if the upgrade to a new version is unsuccessful. + +include::modules/rollback-central-normal.adoc[leveloffset=+2] + +include::modules/rollback-central-forced.adoc[leveloffset=+2] + +include::modules/revoke-the-api-token.adoc[leveloffset=+1] + +include::modules/set-rox-scanner-init-db-env-variable.adoc[leveloffset=+2] + +.Additional resources +* xref:../cli/getting-started-cli.adoc#cli-authentication_cli-getting-started[Authenticating using the `roxctl` CLI] \ No newline at end of file diff --git a/upgrading/upgrade-operator.adoc b/upgrading/upgrade-operator.adoc deleted file mode 100644 index 3f234f785dc4..000000000000 --- a/upgrading/upgrade-operator.adoc +++ /dev/null @@ -1,24 +0,0 @@ -:_content-type: ASSEMBLY -[id="upgrade-operator"] -= Upgrading by using the Operator -include::modules/common-attributes.adoc[] -:context: upgrade-operator - -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. - -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]. - -To roll back an Operator upgrade, you must perform the steps described in one of the following sections. You can roll back an Operator upgrade by using the CLI or the {ocp} web console. - -include::modules/rollback-operator-upgrades-cli.adoc[leveloffset=+1] -include::modules/rollback-operator-upgrades-console.adoc[leveloffset=+1] - -[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] \ No newline at end of file diff --git a/upgrading/upgrade-roxctl.adoc b/upgrading/upgrade-roxctl.adoc deleted file mode 100644 index efadd32b6b74..000000000000 --- a/upgrading/upgrade-roxctl.adoc +++ /dev/null @@ -1,98 +0,0 @@ -:_content-type: ASSEMBLY -[id="upgrade-roxctl"] -= Manually upgrading using the roxctl CLI -include::modules/common-attributes.adoc[] -:context: upgrade-roxctl - -toc::[] - -[role="_abstract"] -You can upgrade to the latest version of {rh-rhacs-first} from a supported older version. - -[NOTE] -==== -You need to perform the manual upgrade procedure only if you used the `roxctl` CLI to deploy {product-title-short}. -==== - -To upgrade {product-title-short} to the latest version, you must perform the following: - -* Set the `ROX_SCANNER_DB_INIT` environment variable -* Backup the Central database -* Upgrade Central -* Upgrade the `roxctl` CLI -* Upgrade Scanner -* Verify that all secured clusters are upgraded - -include::modules/set-rox-scanner-init-db-env-variable.adoc[leveloffset=+1] - -include::modules/back-up-central-database.adoc[leveloffset=+1] - -[role="_additional-resources"] -.Additional resources -* xref:../cli/getting-started-cli.adoc#cli-authentication_cli-getting-started[Authenticating using the `roxctl` CLI] - -[id="upgrade-central-cluster"] -== Upgrading the Central cluster - -After you have backed up the Central database, the next step is to upgrade the Central cluster. This step includes upgrading Central, the `roxctl` CLI, and the Scanner. - -[id="upgrade-central"] -=== Upgrading Central - -You can update Central to the latest version by downloading and deploying the updated images. - -include::modules/upgrade-central-openshift.adoc[leveloffset=+3] - -include::modules/upgrade-central-kubernetes.adoc[leveloffset=+3] - -[id="upgrade-roxctl-cli"] -=== Upgrading the roxctl CLI - -To upgrade the `roxctl` CLI to the latest version you must uninstall the existing version of `roxctl` CLI and then install the latest version of the `roxctl` CLI. - -include::modules/uninstall-roxctl-cli.adoc[leveloffset=+3] -include::modules/install-roxctl-cli-linux.adoc[leveloffset=+3] -include::modules/install-roxctl-cli-macos.adoc[leveloffset=+3] -include::modules/install-roxctl-cli-windows.adoc[leveloffset=+3] - -After you upgrade the `roxctl` CLI you can upgrade Scanner. - -include::modules/upgrade-scanner.adoc[leveloffset=+2] -include::modules/upgrade-scanner-roxctl-371.adoc[leveloffset=+3] - -include::modules/verify-central-cluster-upgrade.adoc[leveloffset=+2] - -[id="upgrade-secured-clusters"] -== Upgrading all secured clusters - -After upgrading Central services, you must upgrade all secured clusters. - -[IMPORTANT] -==== -* If you are using automatic upgrades: -** Update all your secured clusters by using automatic upgrades. -** Skip the instructions in this section and follow the instructions in the xref:../upgrading/upgrade-roxctl.adoc#verify-upgrades_{context}[Verify upgrades] and xref:../upgrading/upgrade-roxctl.adoc#revoke-the-api-token_{context}[Revoking the API token] sections. -* If you are not using automatic upgrades, you must run the instructions in this section on all secured clusters including the Central cluster. -** To ensure optimal functionality, use the same {product-title-short} version for your secured clusters and the cluster on which Central is installed. -==== - -To complete manual upgrades of each secured cluster running Sensor, Collector, and Admission controller, follow the instructions in this section. - -include::modules/update-validating-webhook-configuration.adoc[leveloffset=+2] - -include::modules/update-other-images.adoc[leveloffset=+2] - -include::modules/verify-secured-cluster-upgrade.adoc[leveloffset=+2] - -[id="rollback-central"] -== Rolling back Central - -You can roll back to a previous version of Central if the upgrade to a new version is unsuccessful. - -include::modules/rollback-central-normal.adoc[leveloffset=+2] - -include::modules/rollback-central-forced.adoc[leveloffset=+2] - -include::modules/verify-upgrades.adoc[leveloffset=+1] - -include::modules/revoke-the-api-token.adoc[leveloffset=+1]