From 0c8b9f4c9be82acb757e68cdc3efd8e679e77b7d Mon Sep 17 00:00:00 2001 From: Alex Dellapenta Date: Fri, 28 Oct 2022 15:02:36 -0600 Subject: [PATCH] Include link to Operator upgrades Customer Portal Lab Apps Switch to using 'update' vs 'upgrade' & add NOTE to cluster update --- _topic_maps/_topic_map.yml | 2 +- .../distr-tracing-updating.adoc | 2 +- modules/olm-approving-pending-upgrade.adoc | 10 ++++----- modules/olm-changing-update-channel.adoc | 16 +++++--------- modules/olm-preparing-upgrade.adoc | 22 +++++++++++++++++++ .../olm-adding-operators-to-cluster.adoc | 2 +- operators/admin/olm-upgrading-operators.adoc | 5 +++-- .../osdk-working-bundle-images.adoc | 2 +- ...olm-installing-operators-in-namespace.adoc | 2 +- .../upgrading-sandboxed-containers.adoc | 2 +- updating/understanding-openshift-updates.adoc | 5 +++++ updating/updating-cluster-cli.adoc | 2 +- updating/updating-cluster-within-minor.adoc | 2 +- windows_containers/windows-node-upgrades.adoc | 2 +- 14 files changed, 50 insertions(+), 26 deletions(-) create mode 100644 modules/olm-preparing-upgrade.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index c97a28437d..6bb1b9cb7c 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -1496,7 +1496,7 @@ Topics: - Name: Adding Operators to a cluster File: olm-adding-operators-to-cluster Distros: openshift-enterprise,openshift-origin - - Name: Upgrading installed Operators + - Name: Updating installed Operators File: olm-upgrading-operators Distros: openshift-enterprise,openshift-origin - Name: Deleting Operators from a cluster diff --git a/distr_tracing/distr_tracing_install/distr-tracing-updating.adoc b/distr_tracing/distr_tracing_install/distr-tracing-updating.adoc index efb535eea7..9de6057bce 100644 --- a/distr_tracing/distr_tracing_install/distr-tracing-updating.adoc +++ b/distr_tracing/distr_tracing_install/distr-tracing-updating.adoc @@ -21,4 +21,4 @@ include::modules/distr-tracing-change-operator-20.adoc[leveloffset=+1] If you have not already updated your OpenShift Elasticsearch Operator as described in xref:../../logging/cluster-logging-upgrading.adoc[Updating OpenShift Logging] complete that update before updating your {JaegerName} Operator. ==== -For instructions on how to update the Operator channel, see xref:../../operators/admin/olm-upgrading-operators.adoc[Upgrading installed Operators]. +For instructions on how to update the Operator channel, see xref:../../operators/admin/olm-upgrading-operators.adoc[Updating installed Operators]. diff --git a/modules/olm-approving-pending-upgrade.adoc b/modules/olm-approving-pending-upgrade.adoc index 6788f0515b..744ca510d4 100644 --- a/modules/olm-approving-pending-upgrade.adoc +++ b/modules/olm-approving-pending-upgrade.adoc @@ -5,7 +5,7 @@ :_content-type: PROCEDURE [id="olm-approving-pending-upgrade_{context}"] -= Manually approving a pending Operator upgrade += Manually approving a pending Operator update If an installed Operator has the approval strategy in its subscription set to *Manual*, when new updates are released in its current update channel, the update must be manually approved before installation can begin. @@ -17,12 +17,12 @@ If an installed Operator has the approval strategy in its subscription set to *M . In the *Administrator* perspective of the {product-title} web console, navigate to *Operators -> Installed Operators*. -. Operators that have a pending upgrade display a status with *Upgrade available*. Click the name of the Operator you want to upgrade. +. Operators that have a pending update display a status with *Upgrade available*. Click the name of the Operator you want to update. -. Click the *Subscription* tab. Any upgrades requiring approval are displayed next to *Upgrade Status*. For example, it might display *1 requires approval*. +. Click the *Subscription* tab. Any update requiring approval are displayed next to *Upgrade Status*. For example, it might display *1 requires approval*. . Click *1 requires approval*, then click *Preview Install Plan*. -. Review the resources that are listed as available for upgrade. When satisfied, click *Approve*. +. Review the resources that are listed as available for update. When satisfied, click *Approve*. -. Navigate back to the *Operators -> Installed Operators* page to monitor the progress of the upgrade. When complete, the status changes to *Succeeded* and *Up to date*. +. Navigate back to the *Operators -> Installed Operators* page to monitor the progress of the update. When complete, the status changes to *Succeeded* and *Up to date*. diff --git a/modules/olm-changing-update-channel.adoc b/modules/olm-changing-update-channel.adoc index 1c96a805a7..cf688f7c35 100644 --- a/modules/olm-changing-update-channel.adoc +++ b/modules/olm-changing-update-channel.adoc @@ -6,24 +6,20 @@ [id="olm-changing-update-channel_{context}"] = Changing the update channel for an Operator -The subscription of an installed Operator specifies an update channel, which is used to track and receive updates for the Operator. To upgrade the Operator to start tracking and receiving updates from a newer channel, you can change the update channel in the subscription. +You can change the update channel for an Operator by using the {product-title} web console. -The names of update channels in a subscription can differ between Operators, but the naming scheme should follow a common convention within a given Operator. For example, channel names might follow a minor release update stream for the application provided by the Operator (`1.2`, `1.3`) or a release frequency (`stable`, `fast`). - -[NOTE] +[TIP] ==== -Installed Operators cannot change to a channel that is older than the current channel. +If the approval strategy in the subscription is set to *Automatic*, the update process initiates as soon as a new Operator version is available in the selected channel. If the approval strategy is set to *Manual*, you must manually approve pending updates. ==== -If the approval strategy in the subscription is set to *Automatic*, the upgrade process initiates as soon as a new Operator version is available in the selected channel. If the approval strategy is set to *Manual*, you must manually approve pending upgrades. - .Prerequisites * An Operator previously installed using Operator Lifecycle Manager (OLM). .Procedure -. In the *Administrator* perspective of the {product-title} web console, navigate to *Operators -> Installed Operators*. +. In the *Administrator* perspective of the web console, navigate to *Operators -> Installed Operators*. . Click the name of the Operator you want to change the update channel for. @@ -33,6 +29,6 @@ If the approval strategy in the subscription is set to *Automatic*, the upgrade . Click the newer update channel that you want to change to, then click *Save*. -. For subscriptions with an *Automatic* approval strategy, the upgrade begins automatically. Navigate back to the *Operators -> Installed Operators* page to monitor the progress of the upgrade. When complete, the status changes to *Succeeded* and *Up to date*. +. For subscriptions with an *Automatic* approval strategy, the update begins automatically. Navigate back to the *Operators -> Installed Operators* page to monitor the progress of the update. When complete, the status changes to *Succeeded* and *Up to date*. + -For subscriptions with a *Manual* approval strategy, you can manually approve the upgrade from the *Subscription* tab. +For subscriptions with a *Manual* approval strategy, you can manually approve the update from the *Subscription* tab. diff --git a/modules/olm-preparing-upgrade.adoc b/modules/olm-preparing-upgrade.adoc new file mode 100644 index 0000000000..6597f11f47 --- /dev/null +++ b/modules/olm-preparing-upgrade.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * operators/admin/olm-upgrading-operators.adoc + +:_content-type: CONCEPT +[id="olm-preparing-upgrade_{context}"] += Preparing for an Operator update + +The subscription of an installed Operator specifies an update channel that tracks and receives updates for the Operator. You can change the update channel to start tracking and receiving updates from a newer channel. + +The names of update channels in a subscription can differ between Operators, but the naming scheme typically follows a common convention within a given Operator. For example, channel names might follow a minor release update stream for the application provided by the Operator (`1.2`, `1.3`) or a release frequency (`stable`, `fast`). + +[NOTE] +==== +You cannot change installed Operators to a channel that is older than the current channel. +==== + +Red Hat Customer Portal Labs include the following application that helps administrators prepare to update their Operators: + +* link:https://access.redhat.com/labs/ocpouic/[Red Hat OpenShift Container Platform Operator Update Information Checker] + +You can use the application to search for Operator Lifecycle Manager-based Operators and verify the available Operator version per update channel across different versions of {product-title}. Cluster Version Operator-based Operators are not included. \ No newline at end of file diff --git a/operators/admin/olm-adding-operators-to-cluster.adoc b/operators/admin/olm-adding-operators-to-cluster.adoc index 2b5bbac61f..5074f1afbf 100644 --- a/operators/admin/olm-adding-operators-to-cluster.adoc +++ b/operators/admin/olm-adding-operators-to-cluster.adoc @@ -37,7 +37,7 @@ include::modules/olm-installing-specific-version-cli.adoc[leveloffset=+1] [role="_additional-resources"] .Additional resources -* xref:../../operators/admin/olm-upgrading-operators.adoc#olm-approving-pending-upgrade_olm-upgrading-operators[Manually approving a pending Operator upgrade] +* xref:../../operators/admin/olm-upgrading-operators.adoc#olm-approving-pending-upgrade_olm-upgrading-operators[Manually approving a pending Operator update] include::modules/olm-pod-placement.adoc[leveloffset=+1] diff --git a/operators/admin/olm-upgrading-operators.adoc b/operators/admin/olm-upgrading-operators.adoc index cc85092fc9..35f47ef98d 100644 --- a/operators/admin/olm-upgrading-operators.adoc +++ b/operators/admin/olm-upgrading-operators.adoc @@ -1,12 +1,13 @@ :_content-type: ASSEMBLY [id="olm-upgrading-operators"] -= Upgrading installed Operators += Updating installed Operators include::_attributes/common-attributes.adoc[] :context: olm-upgrading-operators toc::[] -As a cluster administrator, you can upgrade Operators that have been previously installed using Operator Lifecycle Manager (OLM) on your {product-title} cluster. +As a cluster administrator, you can update Operators that have been previously installed using Operator Lifecycle Manager (OLM) on your {product-title} cluster. +include::modules/olm-preparing-upgrade.adoc[leveloffset=+1] include::modules/olm-changing-update-channel.adoc[leveloffset=+1] include::modules/olm-approving-pending-upgrade.adoc[leveloffset=+1] diff --git a/operators/operator_sdk/osdk-working-bundle-images.adoc b/operators/operator_sdk/osdk-working-bundle-images.adoc index 89cd61c502..c0ad373583 100644 --- a/operators/operator_sdk/osdk-working-bundle-images.adoc +++ b/operators/operator_sdk/osdk-working-bundle-images.adoc @@ -38,7 +38,7 @@ include::modules/osdk-control-compat.adoc[leveloffset=+1] .Additional resources * link:https://redhat-connect.gitbook.io/certified-operator-guide/ocp-deployment/operator-metadata/bundle-directory/managing-openshift-versions[Managing OpenShift Versions] in the _Certified Operator Build Guide_ -* xref:../../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Upgrading installed Operators] +* xref:../../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Updating installed Operators] * xref:../../operators/understanding/olm-rh-catalogs.adoc#olm-rh-catalogs[Red Hat-provided Operator catalogs] [id="osdk-working-bundle-images-additional-resources"] diff --git a/operators/user/olm-installing-operators-in-namespace.adoc b/operators/user/olm-installing-operators-in-namespace.adoc index 724931cb6c..9c5e03db26 100644 --- a/operators/user/olm-installing-operators-in-namespace.adoc +++ b/operators/user/olm-installing-operators-in-namespace.adoc @@ -37,5 +37,5 @@ include::modules/olm-installing-specific-version-cli.adoc[leveloffset=+1] [role="_additional-resources"] .Additional resources -* xref:../../operators/admin/olm-upgrading-operators.adoc#olm-approving-pending-upgrade_olm-upgrading-operators[Manually approving a pending Operator upgrade] +* xref:../../operators/admin/olm-upgrading-operators.adoc#olm-approving-pending-upgrade_olm-upgrading-operators[Manually approving a pending Operator update] endif::[] diff --git a/sandboxed_containers/upgrading-sandboxed-containers.adoc b/sandboxed_containers/upgrading-sandboxed-containers.adoc index 9c597e893a..ebd4e29fce 100644 --- a/sandboxed_containers/upgrading-sandboxed-containers.adoc +++ b/sandboxed_containers/upgrading-sandboxed-containers.adoc @@ -38,7 +38,7 @@ For more information about upgrading {product-title}, see xref:../updating/index Use Operator Lifecycle Manager (OLM) to upgrade the {sandboxed-containers-operator} either manually or automatically. Selecting between manual or automatic upgrade during the initial deployment determines the future upgrade mode. For manual upgrades, the web console shows the available updates that can be installed by the cluster administrator. -For more information about upgrading the {sandboxed-containers-operator} in Operator Lifecycle Manager (OLM), see xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Upgrading installed Operators]. +For more information about upgrading the {sandboxed-containers-operator} in Operator Lifecycle Manager (OLM), see xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Updating installed Operators]. [id="sandboxed-containers-upgrading-monitor-pods"] == Upgrading the {sandboxed-containers-first} monitor pods diff --git a/updating/understanding-openshift-updates.adoc b/updating/understanding-openshift-updates.adoc index 3debaaf33f..d2536b15cc 100644 --- a/updating/understanding-openshift-updates.adoc +++ b/updating/understanding-openshift-updates.adoc @@ -12,6 +12,11 @@ The OpenShift Update Service (OSUS) builds a graph of update possibilities based The graph is based on recommended, tested update paths from a specific version. {product-title} clusters connect to the Red Hat Hybrid Cloud servers and identify which clusters the user is running, along with the version information. OSUS responds with information about known update targets. Either a cluster administrator or an automatic update controller edits the custom resource (CR) of the Cluster Version Operator (CVO) with the new version to update to. After the CVO receives the update image from the registry, the CVO then applies the changes. +[NOTE] +==== +Operators previously installed through Operator Lifecycle Manager (OLM) follow a different process for updates. See xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Updating installed Operators] for more information. +==== + include::modules/update-common-terms.adoc[leveloffset=+1] [role="_additional-resources"] diff --git a/updating/updating-cluster-cli.adoc b/updating/updating-cluster-cli.adoc index 0efddc3362..e016278164 100644 --- a/updating/updating-cluster-cli.adoc +++ b/updating/updating-cluster-cli.adoc @@ -19,7 +19,7 @@ You can update, or upgrade, an {product-title} cluster within a minor version by See xref:../authentication/using-rbac.adoc[Using RBAC to define and apply permissions]. * Have a recent xref:../backup_and_restore/control_plane_backup_and_restore/backing-up-etcd.adoc#backup-etcd[etcd backup] in case your update fails and you must xref:../backup_and_restore/control_plane_backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[restore your cluster to a previous state]. * Support for {op-system-base}7 workers is removed in {product-title} {product-version}. You must replace {op-system-base}7 workers with {op-system-base}8 or {op-system} workers before upgrading to {product-title} {product-version}. Red Hat does not support in-place {op-system-base}7 to {op-system-base}8 updates for {op-system-base} workers; those hosts must be replaced with a clean operating system install. -* Ensure all Operators previously installed through Operator Lifecycle Manager (OLM) are updated to their latest version in their latest channel. Updating the Operators ensures they have a valid update path when the default OperatorHub catalogs switch from the current minor version to the next during a cluster update. See xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Upgrading installed Operators] for more information. +* Ensure all Operators previously installed through Operator Lifecycle Manager (OLM) are updated to their latest version in their latest channel. Updating the Operators ensures they have a valid update path when the default OperatorHub catalogs switch from the current minor version to the next during a cluster update. See xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Updating installed Operators] for more information. * Ensure that all machine config pools (MCPs) are running and not paused. Nodes associated with a paused MCP are skipped during the update process. You can pause the MCPs if you are performing a canary rollout update strategy. * If your cluster uses manually maintained credentials, ensure that the Cloud Credential Operator (CCO) is in an upgradeable state. For more information, see xref:../updating/updating-cluster-cli.adoc#manually-maintained-credentials-upgrade_updating-cluster-cli[Upgrading clusters with manually maintained credentials]. * If your cluster uses manually maintained credentials with the AWS Secure Token Service (STS), obtain a copy of the `ccoctl` utility from the release image being updated to and use it to process any updated credentials. For more information, see xref:../authentication/managing_cloud_provider_credentials/cco-mode-sts.adoc#sts-mode-upgrading[Upgrading an OpenShift Container Platform cluster configured for manual mode with STS]. diff --git a/updating/updating-cluster-within-minor.adoc b/updating/updating-cluster-within-minor.adoc index c31b214776..161f559eae 100644 --- a/updating/updating-cluster-within-minor.adoc +++ b/updating/updating-cluster-within-minor.adoc @@ -19,7 +19,7 @@ Use the web console or `oc adm upgrade channel __` to change the update See xref:../authentication/using-rbac.adoc[Using RBAC to define and apply permissions]. * Have a recent xref:../backup_and_restore/control_plane_backup_and_restore/backing-up-etcd.adoc#backup-etcd[etcd backup] in case your update fails and you must xref:../backup_and_restore/control_plane_backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[restore your cluster to a previous state]. * Support for {op-system-base}7 workers is removed in {product-title} {product-version}. You must replace {op-system-base}7 workers with {op-system-base}8 or {op-system} workers before upgrading to {product-title} {product-version}. Red Hat does not support in-place {op-system-base}7 to {op-system-base}8 updates for {op-system-base} workers; those hosts must be replaced with a clean operating system install. -* Ensure all Operators previously installed through Operator Lifecycle Manager (OLM) are updated to their latest version in their latest channel. Updating the Operators ensures they have a valid update path when the default OperatorHub catalogs switch from the current minor version to the next during a cluster update. See xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Upgrading installed Operators] for more information. +* Ensure all Operators previously installed through Operator Lifecycle Manager (OLM) are updated to their latest version in their latest channel. Updating the Operators ensures they have a valid update path when the default OperatorHub catalogs switch from the current minor version to the next during a cluster update. See xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Updating installed Operators] for more information. * Ensure that all machine config pools (MCPs) are running and not paused. Nodes associated with a paused MCP are skipped during the update process. You can pause the MCPs if you are performing a canary rollout update strategy. //remove this???^ or maybe just add another bullet that you can break up the update? * To accommodate the time it takes to update, you are able to do a partial update by updating the worker or custom pool nodes. You can pause and resume within the progress bar of each pool. diff --git a/windows_containers/windows-node-upgrades.adoc b/windows_containers/windows-node-upgrades.adoc index bce4146a92..85a271a1a6 100644 --- a/windows_containers/windows-node-upgrades.adoc +++ b/windows_containers/windows-node-upgrades.adoc @@ -10,4 +10,4 @@ You can ensure your Windows nodes have the latest updates by upgrading the Windo include::modules/wmco-upgrades.adoc[leveloffset=+1] -For more information on Operator upgrades using the Operator Lifecycle Manager (OLM), see xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Upgrading installed Operators]. +For more information on Operator upgrades using the Operator Lifecycle Manager (OLM), see xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Updating installed Operators].