diff --git a/modules/upgrade/examples/snip_che-upgrading-the-chectl-management-tool.adoc b/modules/upgrade/examples/snip_che-upgrading-the-chectl-management-tool.adoc index 68b0e5992b..cca6dd9ac1 100644 --- a/modules/upgrade/examples/snip_che-upgrading-the-chectl-management-tool.adoc +++ b/modules/upgrade/examples/snip_che-upgrading-the-chectl-management-tool.adoc @@ -1,6 +1,7 @@ :_content-type: SNIPPET -This section describes how to upgrade the `{prod-cli}` management tool. +[role="_abstract"] +Update the `{prod-cli}` management tool to the latest version before upgrading {prod-short} from the command line. .Prerequisites diff --git a/modules/upgrade/nav.adoc b/modules/upgrade/nav.adoc index 9925902a06..9743229638 100644 --- a/modules/upgrade/nav.adoc +++ b/modules/upgrade/nav.adoc @@ -2,7 +2,7 @@ * xref:upgrading-che.adoc[] ** xref:specifying-the-update-approval-strategy.adoc[] ** xref:upgrading-che-using-the-web-console.adoc[] +** xref:upgrading-the-chectl-management-tool.adoc[] ** xref:upgrading-che-using-the-cli-management-tool.adoc[] ** xref:upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc[] -** xref:upgrading-the-chectl-management-tool.adoc[] ** xref:repairing-the-devworkspace-operator-on-openshift.adoc[] diff --git a/modules/upgrade/pages/repairing-the-devworkspace-operator-on-openshift.adoc b/modules/upgrade/pages/repairing-the-devworkspace-operator-on-openshift.adoc index fd3eb98de7..9623956169 100644 --- a/modules/upgrade/pages/repairing-the-devworkspace-operator-on-openshift.adoc +++ b/modules/upgrade/pages/repairing-the-devworkspace-operator-on-openshift.adoc @@ -1,15 +1,14 @@ :_content-type: PROCEDURE -:description: Repairing the {devworkspace} Operator on OpenShift -:keywords: devworkspace, operator, repair +:description: Fix a duplicate DevWorkspace Operator after an OLM restart or cluster upgrade. +:keywords: devworkspace, operator, repair, duplicate :navtitle: Fix a duplicate {devworkspace} Operator after a cluster upgrade :page-aliases: administration-guide:repairing-the-devworkspace-operator-on-openshift.adoc [id="repairing-the-devworkspace-operator-on-openshift"] = Fix a duplicate {devworkspace} Operator after a cluster upgrade -Under certain conditions, such as link:https://docs.openshift.com/container-platform/{ocp4-ver}/operators/understanding/olm/olm-understanding-olm.html[OLM] restart or cluster upgrade, the {prod2} Operator for {prod-short} might automatically install the {devworkspace} Operator even when it is already present on the cluster. In that case, you can repair the {devworkspace} Operator on OpenShift as follows: - -include::partial$snip_persona-admin.adoc[] +[role="_abstract"] +Fix a duplicate {devworkspace} Operator installation that can occur when an link:https://docs.openshift.com/container-platform/{ocp4-ver}/operators/understanding/olm/olm-understanding-olm.html[OLM] restart or cluster upgrade leaves multiple Operator entries in a *Replacing* or *Pending* loop. .Prerequisites diff --git a/modules/upgrade/pages/specifying-the-update-approval-strategy.adoc b/modules/upgrade/pages/specifying-the-update-approval-strategy.adoc index 20fbc70663..64bd6d9fab 100644 --- a/modules/upgrade/pages/specifying-the-update-approval-strategy.adoc +++ b/modules/upgrade/pages/specifying-the-update-approval-strategy.adoc @@ -1,25 +1,23 @@ -:_content-type: ASSEMBLY -:description: Specifying the update approval strategy -:keywords: administration guide, upgrading-che-using-operatorhub +:_content-type: PROCEDURE +:description: Choose between automatic and manual update approval for the Operator. +:keywords: upgrade, approval, automatic, manual :navtitle: Choose how updates are applied :page-aliases: administration-guide:specifying-the-update-approval-strategy.adoc, installation-guide:upgrading-che-using-operatorhub.adoc [id="specifying-the-{prod-id-short}-operator-update-approval-strategy-using-the-web-console"] = Choose how updates are applied +[role="_abstract"] +Choose between automatic and manual update approval for the {prod} Operator so that you control when new versions are installed on your cluster. The {prod} Operator supports two upgrade strategies: -include::partial$snip_persona-admin.adoc[] - `Automatic`:: The Operator installs new updates when they become available. `Manual`:: New updates need to be manually approved before installation begins. -You can specify the update approval strategy for the {prod} Operator by using the OpenShift web console. - .Prerequisites * An OpenShift web console session by a cluster administrator. See link:https://docs.openshift.com/container-platform/{ocp4-ver}/web_console/web-console.html[Accessing the web console]. diff --git a/modules/upgrade/pages/upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc b/modules/upgrade/pages/upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc index 1e10babdc0..d9a0c0f06a 100644 --- a/modules/upgrade/pages/upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc +++ b/modules/upgrade/pages/upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc @@ -1,15 +1,14 @@ :_content-type: PROCEDURE -:description: Upgrading {prod-short} in a restricted environment -:keywords: Upgrading {prod-short} in a restricted environment +:description: Upgrade in a restricted environment by mirroring images and Operator catalogs. +:keywords: upgrade, restricted, air-gapped, disconnected, mirror :navtitle: Upgrade in an air-gapped environment :page-aliases: administration-guide:upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc, installation-guide:upgrading-che-using-the-cli-management-tool-in-restricted-environment.adoc, installation-guide:upgrading-che-in-restricted-environment.adoc [id="upgrading-{prod-id-short}-using-the-cli-management-tool-in-restricted-environment"] = Upgrade in an air-gapped environment -This section describes how to upgrade {prod} and perform minor version updates by using the CLI management tool in a restricted environment. - -include::partial$snip_persona-admin.adoc[] +[role="_abstract"] +Upgrade {prod-short} on a cluster with no internet access by mirroring updated container images and Operator catalogs to your private registry before running the upgrade. .Prerequisites diff --git a/modules/upgrade/pages/upgrading-che-using-the-cli-management-tool.adoc b/modules/upgrade/pages/upgrading-che-using-the-cli-management-tool.adoc index 265b353251..6351a9ef1c 100644 --- a/modules/upgrade/pages/upgrading-che-using-the-cli-management-tool.adoc +++ b/modules/upgrade/pages/upgrading-che-using-the-cli-management-tool.adoc @@ -1,15 +1,14 @@ :_content-type: PROCEDURE -:description: Upgrading {prod-short} using the CLI management tool -:keywords: administration guide, upgrading-che-using-the-cli-management-tool +:description: Upgrade from the previous minor version using the CLI management tool. +:keywords: upgrade, cli, chectl, command line :navtitle: Upgrade {prod-short} from the command line :page-aliases: administration-guide:upgrading-che-using-the-cli-management-tool.adoc, installation-guide:upgrading-che-using-the-cli-management-tool.adoc [id="upgrading-{prod-id-short}-using-the-cli-management-tool"] = Upgrade {prod-short} from the command line -This section describes how to upgrade from the previous minor version using the CLI management tool. - -include::partial$snip_persona-admin.adoc[] +[role="_abstract"] +Upgrade {prod-short} from the previous minor version using the `{prod-cli}` management tool so that your deployment receives the latest bug fixes, security patches, and features. .Prerequisites diff --git a/modules/upgrade/pages/upgrading-che-using-the-web-console.adoc b/modules/upgrade/pages/upgrading-che-using-the-web-console.adoc index 263681c71e..5b8475a6e2 100644 --- a/modules/upgrade/pages/upgrading-che-using-the-web-console.adoc +++ b/modules/upgrade/pages/upgrading-che-using-the-web-console.adoc @@ -1,15 +1,14 @@ -:_content-type: ASSEMBLY -:description: Upgrading {prod-short} using the OpenShift web console -:keywords: administration guide, upgrading-che-using-operatorhub +:_content-type: PROCEDURE +:description: Approve a pending Operator upgrade in the OpenShift web console. +:keywords: upgrade, web console, approve, manual :navtitle: Approve a pending upgrade in the web console :page-aliases: administration-guide:upgrading-che-using-the-web-console.adoc [id="upgrading-{prod-id-short}-using-the-openshift-web-console"] = Approve a pending upgrade in the web console -You can manually approve an upgrade from an earlier minor version using the {prod} Operator from the Red Hat Ecosystem Catalog in the OpenShift web console. - -include::partial$snip_persona-admin.adoc[] +[role="_abstract"] +Approve a pending {prod} Operator upgrade in the OpenShift web console so that your deployment receives the latest features, bug fixes, and security patches at the time you choose. .Prerequisites diff --git a/modules/upgrade/pages/upgrading-che.adoc b/modules/upgrade/pages/upgrading-che.adoc index e4080283fc..d0645bffc1 100644 --- a/modules/upgrade/pages/upgrading-che.adoc +++ b/modules/upgrade/pages/upgrading-che.adoc @@ -1,6 +1,6 @@ -:_content-type: ASSEMBLY -:description: Keep your {prod-short} deployment current by upgrading to the latest version. -:keywords: upgrade, update, migrate +:_content-type: CONCEPT +:description: Plan your upgrade by reviewing supported paths, choosing an approval strategy, and completing the pre-upgrade checklist. +:keywords: upgrade, update, plan, checklist :navtitle: Upgrade {prod-short} :page-aliases: administration-guide:upgrading-che.adoc, installation-guide:upgrading-che.adoc, installation-guide:upgrading-che-known-issues.adoc, installation-guide:rolling-back-a-che-upgrade.adoc, installation-guide:upgrading-che-namespace-strategies-other-than-per-user.adoc, upgrading-che-namespace-strategies-other-than-per-user.adoc, upgrading-che-7-41-on-openshift.adoc @@ -9,7 +9,31 @@ = Upgrade {prod-short} [role="_abstract"] -Keep your {prod-short} deployment current by upgrading to the latest version. Upgrading delivers bug fixes, security patches, and new capabilities to your developers with minimal disruption. +Upgrade your {prod-short} deployment to the latest version to receive bug fixes, security patches, and new capabilities with minimal disruption. -Before you upgrade, save and push all work in running workspaces, then stop all workspaces. The Operator handles the server component upgrade automatically. Workspaces resume normally after the upgrade completes. +== How the upgrade works + +When you upgrade {prod-short}, the Operator handles the server component upgrade automatically. You do not need to manually update individual pods or configurations. The Operator: + +* Replaces the {prod-short} server, dashboard, gateway, and plug-in registry pods with the new version. +* Upgrades the {devworkspace} Operator to the version bundled with the new release. +* Preserves the existing `CheCluster` custom resource configuration. + +Running workspaces are not automatically restarted during the upgrade. Developers must stop their workspaces before the upgrade and restart them after the upgrade completes. + +== Supported upgrade path + +{prod-short} supports upgrading from the previous minor version to the current version. + +Direct upgrades that skip minor versions are not supported. If your deployment is more than one minor version behind, upgrade one minor version at a time. + +== Pre-upgrade checklist + +Complete the following steps before upgrading: + +. Review the release notes for breaking changes and new features. +. Notify developers to save and push all uncommitted work in their running workspaces. +. Stop all running workspaces. The upgrade does not automatically stop workspaces, and running workspaces might encounter errors during the upgrade. +. Choose an update approval strategy. See xref:specifying-the-update-approval-strategy.adoc[]. +. If you plan to upgrade from the command line, update `{prod-cli}` to the latest version. See xref:upgrading-the-chectl-management-tool.adoc[]. diff --git a/modules/upgrade/pages/upgrading-the-chectl-management-tool.adoc b/modules/upgrade/pages/upgrading-the-chectl-management-tool.adoc index 340f057163..a85406ffac 100644 --- a/modules/upgrade/pages/upgrading-the-chectl-management-tool.adoc +++ b/modules/upgrade/pages/upgrading-the-chectl-management-tool.adoc @@ -1,12 +1,10 @@ :_content-type: PROCEDURE -:description: Upgrading the chectl management tool -:keywords: overview, upgrading, chectl, cli +:description: Update the CLI management tool to the latest version before upgrading. +:keywords: upgrade, chectl, cli, update :navtitle: Update the {prod-cli} management tool :page-aliases: administration-guide:upgrading-the-chectl-management-tool.adoc [id="upgrading-the-{prod-cli}-management-tool"] -= Upgrading the {prod-cli} management tool - -include::partial$snip_persona-admin.adoc[] += Update the {prod-cli} management tool include::example$snip_{project-context}-upgrading-the-chectl-management-tool.adoc[] diff --git a/modules/upgrade/partials/snip_installing-che-in-a-restricted-environment-additional-resources.adoc b/modules/upgrade/partials/snip_installing-che-in-a-restricted-environment-additional-resources.adoc index 72880389fe..9ad91a40d2 100644 --- a/modules/upgrade/partials/snip_installing-che-in-a-restricted-environment-additional-resources.adoc +++ b/modules/upgrade/partials/snip_installing-che-in-a-restricted-environment-additional-resources.adoc @@ -1,5 +1,6 @@ :_content-type: SNIPPET +[role="_additional-resources"] .Additional resources * link:https://docs.openshift.com/container-platform/{ocp4-ver}/operators/understanding/olm-rh-catalogs.html[Red Hat-provided Operator catalogs] diff --git a/modules/upgrade/partials/snip_persona-admin.adoc b/modules/upgrade/partials/snip_persona-admin.adoc deleted file mode 100644 index 9857252bbf..0000000000 --- a/modules/upgrade/partials/snip_persona-admin.adoc +++ /dev/null @@ -1 +0,0 @@ -This page is for platform administrators who install, configure, and manage {prod-short} on {orch-name} clusters. To learn more about common roles and example tasks referenced in {prod-short} documentation, see xref:discover:roles-and-tasks.adoc[].