eclipse-che · gtrivedi88 · Jul 7, 2026
@@ -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
 
@@ -32,6 +33,7 @@ To move to a different channel, start the update with the name of the channel as
 ----
 ====
 
+[role="_additional-resources"]
 .Additional resources
 
 * {link-prod-cli-documentation}
@@ -1,8 +1,10 @@
 .Upgrade
 * xref:upgrading-che.adoc[]
-** xref:specifying-the-update-approval-strategy.adoc[]
-** xref:upgrading-che-using-the-web-console.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[]
+* xref:specifying-the-update-approval-strategy.adoc[]
+* xref:pre-upgrade-checklist.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:verify-upgrade-completed.adoc[]
+* xref:repairing-the-devworkspace-operator-on-openshift.adoc[]
@@ -0,0 +1,34 @@
+:_content-type: REFERENCE
+:description: Complete this checklist before upgrading to ensure no work is lost.
+:keywords: upgrade, checklist, pre-upgrade, prerequisites
+:navtitle: Pre-upgrade checklist
+:page-aliases:
+
+[id="pre-upgrade-checklist"]
+= Pre-upgrade checklist
+
+[role="_abstract"]
+Complete the following checklist before upgrading {prod-short} so that no work is lost and the upgrade proceeds without errors.
+
+[cols="1,3",options="header"]
+|===
+| Step | Action
+
+| 1
+| Review the release notes for breaking changes and new features.
+
+| 2
+| Verify that your {platforms-name} cluster version is supported. See xref:upgrading-che.adoc[].
+
+| 3
+| Notify developers to save and push all uncommitted work in their running workspaces.
+
+| 4
+| Stop all running workspaces. The upgrade does not automatically stop workspaces, and running workspaces might encounter errors during the upgrade.
+
+| 5
+| If you plan to upgrade from the command line, update `{prod-cli}` to the latest version. See xref:upgrading-the-chectl-management-tool.adoc[].
+
+| 6
+| Verify the current {prod-short} Operator subscription and update approval strategy. See xref:specifying-the-update-approval-strategy.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
 
@@ -33,32 +32,40 @@ status:
 ...
 ----
 +
-TIP: You can find and edit the `DevWorkspace` and `DevWorkspaceTemplate` CRDs in the *Administrator* perspective of the OpenShift web console by searching for `DevWorkspace` in menu:Administration[CustomResourceDefinitions].
+[TIP]
+====
+You can find and edit the `DevWorkspace` and `DevWorkspaceTemplate` CRDs in the *Administrator* perspective of the OpenShift web console by searching for `DevWorkspace` in menu:Administration[CustomResourceDefinitions].
+====
 +
-NOTE: The `DevWorkspaceOperatorConfig` and `DevWorkspaceRouting` CRDs  have the conversion strategy set to `None` by default.
+[NOTE]
+====
+The `DevWorkspaceOperatorConfig` and `DevWorkspaceRouting` CRDs have the conversion strategy set to `None` by default.
+====
 
 . Remove the {devworkspace} Operator subscription:
 +
+[subs="+quotes,+attributes"]
 ----
-$ oc delete sub devworkspace-operator \
--n openshift-operators <1>
+$ {orch-cli} delete sub devworkspace-operator \
+-n __<devworkspace_operator_namespace>__ <1>
 ----
-<1> `openshift-operators` or an OpenShift {orch-namespace} where the {devworkspace} Operator is installed.
+<1> The {orch-namespace} where the {devworkspace} Operator is installed, such as `openshift-operators`.
 
 . Get the {devworkspace} Operator CSVs in the __<devworkspace_operator.vX.Y.Z>__ format:
 +
+[subs="+attributes"]
 ----
-$ oc get csv | grep devworkspace
+$ {orch-cli} get csv | grep devworkspace
 ----
 
 . Remove each {devworkspace} Operator CSV:
 +
-[subs="+quotes"]
+[subs="+quotes,+attributes"]
 ----
-$ oc delete csv __<devworkspace_operator.vX.Y.Z>__ \
--n openshift-operators <1>
+$ {orch-cli} delete csv __<devworkspace_operator.vX.Y.Z>__ \
+-n __<devworkspace_operator_namespace>__ <1>
 ----
-<1> `openshift-operators` or an OpenShift {orch-namespace} where the {devworkspace} Operator is installed.
+<1> The {orch-namespace} where the {devworkspace} Operator is installed, such as `openshift-operators`.
 
 . Re-create the {devworkspace} Operator subscription:
 +
@@ -75,13 +82,24 @@ spec:
   name: devworkspace-operator
   source: redhat-operators
   sourceNamespace: openshift-marketplace
-  installPlanApproval: Automatic <1>
+  installPlanApproval: Automatic
   startingCSV: devworkspace-operator.v{devworkspace-operator-version-patch}
 EOF
 ----
 +
-<1> `Automatic` or `Manual`.
+`installPlanApproval`:: `Automatic` or `Manual`.
 +
-IMPORTANT: For `installPlanApproval: Manual`, in the *Administrator* perspective of the OpenShift web console, go to menu:Operators[Installed Operators] and select the following for the *{devworkspace} Operator*: menu:Upgrade available[Preview InstallPlan > Approve].
+[IMPORTANT]
+====
+For `installPlanApproval: Manual`, in the *Administrator* perspective of the OpenShift web console, go to menu:Operators[Installed Operators] and select the following for the *{devworkspace} Operator*: menu:Upgrade available[Preview InstallPlan > Approve].
+====
+
+.Verification
+
+* In the *Administrator* perspective of the OpenShift web console, go to menu:Operators[Installed Operators] and verify the *Succeeded* status of the *{devworkspace} Operator*.
+
+[role="_additional-resources"]
+.Additional resources
 
-. In the *Administrator* perspective of the OpenShift web console, go to menu:Operators[Installed Operators] and verify the *Succeeded* status of the *{devworkspace} Operator*.
+* xref:specifying-the-update-approval-strategy.adoc[]
+* xref:upgrading-che-using-the-web-console.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].
@@ -36,6 +34,7 @@ You can specify the update approval strategy for the {prod} Operator by using th
 
 . Configure the *Update approval* strategy to `Automatic` or `Manual`.
 
+[role="_additional-resources"]
 .Additional resources
 
 * link:https://docs.openshift.com/container-platform/{ocp4-ver}/operators/admin/olm-upgrading-operators.html#olm-changing-update-channel_olm-upgrading-operators[Changing the update channel for an Operator]
@@ -1,22 +1,38 @@
 :_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
 
 * The {prod-short} instance was installed on OpenShift using the `{prod-cli} --installer operator` method in the `{prod-namespace}` project. See xref:install:proc_installing-che-in-a-restricted-environment.adoc[].
 
 include::install:partial$snip_preparing-images-for-a-restricted-environment.adoc[]
 
+.Procedure
+
+. Download and execute the mirroring script to install a custom Operator catalog and mirror the related images: xref:administration-guide:attachment$restricted-environment/prepare-restricted-environment.sh[prepare-restricted-environment.sh].
++
+[source,bash,subs="+attributes,+quotes"]
+----
+$ bash prepare-restricted-environment.sh \
+  --devworkspace_operator_index {devworkspace-operator-index-disconnected-install}\
+  --devworkspace_operator_version "v{devworkspace-operator-version-patch}" \
+  --prod_operator_index "{prod-operator-index}" \
+  --prod_operator_package_name "{prod-operator-package-name}" \
+  --prod_operator_bundle_name "{prod-operator-bundle-name}" \
+  --prod_operator_version "v{prod-ver-patch}" \
+  --my_registry "__<my_registry>__" <1>
+----
+<1> The private Docker registry where the images will be mirrored
+
 . In all running workspaces in the {prod-prev-short} {prod-prev-ver} instance, save and push changes back to the Git repositories.
 
 . Stop all workspaces in the {prod-prev-short} {prod-prev-ver} instance.
@@ -28,7 +44,7 @@ include::install:partial$snip_preparing-images-for-a-restricted-environment.adoc
 $ {prod-cli} server:update --che-operator-image="$TAG" -n {prod-namespace} --k8spodwaittimeout=1800000
 ----
 
-.Verification steps
+.Verification
 
 . Navigate to the {prod-short} instance.
 

@@ -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
-:navtitle: Upgrade {prod-short} from the command line
+:description: Upgrade by using the CLI management tool from the previous minor version.
+:keywords: upgrade, cli, chectl, command line
+:navtitle: Upgrade by using the {prod-cli} management tool
 :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
+= Upgrade by using the {prod-cli} management tool
 
-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 by using the `{prod-cli}` management tool so that your deployment receives the latest bug fixes, security patches, and features.
 
 .Prerequisites
 
@@ -37,8 +36,15 @@ $ {prod-cli} server:update -n {prod-namespace}
 For slow systems or internet connections, add the `--k8spodwaittimeout=1800000` flag option to extend the Pod timeout period to 1800000 ms or longer.
 ====
 
-.Verification steps
+.Verification
 
 . Navigate to the {prod-short} instance.
 
 . The {prod-ver} version number is visible at the bottom of the page.
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:upgrading-the-chectl-management-tool.adoc[]
+* xref:specifying-the-update-approval-strategy.adoc[]
+* xref: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
 
@@ -23,12 +22,13 @@ include::partial$snip_persona-admin.adoc[]
 
 * Manually approve the pending {prod} Operator upgrade. See link:https://docs.openshift.com/container-platform/{ocp4-ver}/operators/admin/olm-upgrading-operators.html#olm-approving-pending-upgrade_olm-upgrading-operators[Manually approving a pending Operator upgrade].
 
-.Verification steps
+.Verification
 
 . Navigate to the {prod-short} instance.
 
 . The {prod-ver} version number is visible at the bottom of the page.
 
+[role="_additional-resources"]
 .Additional resources
 
 * link:https://docs.openshift.com/container-platform/{ocp4-ver}/operators/admin/olm-upgrading-operators.html#olm-approving-pending-upgrade_olm-upgrading-operators[Manually approving a pending Operator upgrade]
@@ -1,15 +1,41 @@
-:_content-type: ASSEMBLY
-:description: Keep your {prod-short} deployment current by upgrading to the latest version.
-:keywords: upgrade, update, migrate
-:navtitle: Upgrade {prod-short}
+:_content-type: CONCEPT
+:description: Understand how the upgrade works, supported paths, and platform version compatibility.
+:keywords: upgrade, update, overview, supported path
+:navtitle: How the upgrade works
 :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
 
 
 [id="upgrading-{prod-id-short}"]
-= Upgrade {prod-short}
+= How the upgrade works
 
 [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.
+Understand what happens during a {prod-short} upgrade so that you can plan the timing, communicate downtime expectations, and verify the result.
 
-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.
+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 plugin 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.
+
+== {platforms-name} version compatibility
+
+{prod-short} {prod-ver} is supported on {platforms-name} {platforms-ver}. Before you upgrade {prod-short}, verify that your {platforms-name} cluster version is within the supported range.
+
+== Review the release notes
+
+Review the release notes before upgrading to understand new features, bug fixes, and any changes that might affect your deployment. For a complete pre-upgrade checklist, see Additional resources.
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:pre-upgrade-checklist.adoc[]
+* xref:specifying-the-update-approval-strategy.adoc[]