Merge pull request #75715 from xenolinux/simplify-upgrade-scenarios

OSDOCS#10239: Simplify upgrading scenarios for hosted control planes

Author: snarayan-redhat

hosted_control_planes/hcp-updating.adoc

@@ -8,6 +8,14 @@ toc::[]
 
 Updates for {hcp} involve updating the hosted cluster and the node pools. For a cluster to remain fully operational during an update process, you must meet the requirements of the link:https://kubernetes.io/releases/version-skew-policy/[Kubernetes version skew policy] while completing the control plane and node updates.
 
+include::modules/hcp-updating-requirements.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../updating/updating_a_cluster/updating-cluster-web-console.adoc#updating-cluster-web-console[Updating a cluster using the web console]
+* xref:../updating/updating_a_cluster/updating-cluster-cli.adoc#updating-cluster-cli[Updating a cluster using the CLI]
+* xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Updating installed Operators]
+
 // Updates for the hosted cluster
 include::modules/hcp-updates-hosted-cluster.adoc[leveloffset=+1]
 
@@ -16,3 +24,6 @@ include::modules/hcp-updates-node-pools.adoc[leveloffset=+1]
 
 // Updating node pools for hosted control planes
 include::modules/updating-node-pools-for-hcp.adoc[leveloffset=+1]
+
+// Updating a hosted cluster
+include::modules/updating-hosted-cluster.adoc[leveloffset=+1]

modules/hcp-updating-requirements.adoc

@@ -6,13 +6,13 @@
 [id="hosted-control-planes-upgrading-requirements_{context}"]
 = Requirements to upgrade {hcp}
 
-The multicluster engine for Kubernetes operator can manage one or more {product-title} clusters. After you create a hosted cluster on {product-title}, you must import your hosted cluster in the multicluster engine for Kubernetes operator as a managed cluster. Then, you can use the {product-title} cluster as a management cluster.
+The multicluster engine for Kubernetes operator can manage one or more {product-title} clusters. After you create a hosted cluster on {product-title}, you must import your hosted cluster in the multicluster engine operator as a managed cluster. Then, you can use the {product-title} cluster as a management cluster.
 
 Consider the following requirements before you start updating {hcp}:
 
 * You must use the bare metal platform for an {product-title} cluster when using {VirtProductName} as a provider.
 
-* You must use bare metal or {VirtProductName} as the cloud platform for the hosted cluster. You can find the platform type of your hosted cluster in the `spec.Platform.type` specification of the `HostedCluster` custom resource(CR).
+* You must use bare metal or {VirtProductName} as the cloud platform for the hosted cluster. You can find the platform type of your hosted cluster in the `spec.Platform.type` specification of the `HostedCluster` custom resource (CR).
 
 You must upgrade the {product-title} cluster, multicluster engine for Kubernetes operator, hosted cluster, and node pools by completing the following tasks:
 

modules/updating-hosted-cluster.adoc

@@ -0,0 +1,57 @@
+// Module included in the following assemblies:
+//
+// * upgrades/updating_a_cluster/updating-hosted-control-planes.adoc
+// * hosted_control_planes/hcp-updating.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="updating-hosted-cluster_{context}"]
+= Updating the hosted cluster for {hcp}
+
+On {hcp}, you can upgrade your version of {product-title} by updating the hosted cluster.
+
+.Procedure
+
+. Add the `hypershift.openshift.io/force-upgrade-to=<openshift_release_image>` annotation to the hosted cluster by entering the following command:
++
+[source,terminal]
+----
+$ oc annotate hostedcluster -n <hosted_cluster_namespace> <hosted_cluster_name> "hypershift.openshift.io/force-upgrade-to=<openshift_release_image>" --overwrite <1> <2>
+----
++
+<1> Replace `<hosted_cluster_name>` and `<hosted_cluster_namespace>` with your hosted cluster name and hosted cluster namespace, respectively.
+<2> The `<openshift_release_image>` variable specifies the new {product-title} release image that you want to upgrade to.
+
+
+. Change the `spec.release.image` value in the hosted cluster by entering the following command:
++
+[source,terminal]
+----
+$ oc patch hostedcluster <hosted_cluster_name> -n <hosted_cluster_namespace> --type=merge -p '{"spec":{"release":{"image":"<openshift_release_image>"}}}'
+----
+
+
+.Verification
+
+* To verify that the new version was rolled out, check the `.status.conditions` and `.status.version` values in the hosted cluster by running the following command:
++
+[source,terminal]
+----
+$ oc get -n <hosted_cluster_namespace> hostedcluster <hosted_cluster_name> -o yaml
+----
++
+.Example output
+[source,yaml]
+----
+status:
+  conditions:
+  - lastTransitionTime: "2024-05-20T15:01:01Z"
+	       message: Payload loaded version="4.15.14" image="quay.io/openshift-release-dev/ocp-release:4.15.14-x86_64"
+	       status: "True"
+	       type: ClusterVersionReleaseAccepted
+#...
+version:
+	   availableUpdates: null
+	   desired:
+  	 image: quay.io/openshift-release-dev/ocp-release:4.15.14-x86_64
+  	 version: 4.15.14
+----

modules/updating-node-pools-for-hcp.adoc

@@ -7,22 +7,37 @@
 [id="updating-node-pools-for-hcp_{context}"]
 = Updating node pools for {hcp}
 
-On {hcp}, you update your version of {product-title} by updating the node pools. The node pool version must not surpass the hosted control plane version.
+On {hcp}, you can update your version of {product-title} by updating the node pools. The node pool version must not surpass the hosted control plane version.
 
 .Procedure
 
-* To start the process to update to a new version of {product-title}, change the `spec.release.image` value of the node pool by entering the following command:
+* Change the `spec.release.image` value in the node pool by entering the following command:
 +
 [source,terminal]
 ----
-$ oc -n <hosted_cluster_namespace> patch hostedcluster <hosted_cluster_name> --patch '{"spec":{"release":{"image": "<image_name>"}}}' --type=merge
+$ oc patch nodepool <node_pool_name> -n <hosted_cluster_namespace> --type=merge -p '{"spec":{"nodeDrainTimeout":"60s","release":{"image":"<openshift_release_image>"}}}' <1> <2>
 ----
++
+<1> Replace `<node_pool_name>` and `<hosted_cluster_namespace>` with your node pool name and hosted cluster namespace, respectively.
+<2> The `<openshift_release_image>` variable specifies the new {product-title} release image that you want to upgrade to.
 
 .Verification
 
-* To verify that the new version was rolled out, check the `.status.version` and `.status.conditions` values in the `HostedCluster` custom resource (CR) by running the following command:
+* To verify that the new version was rolled out, check the `.status.conditions` value in the node pool by running the following command:
 +
 [source,terminal]
 ----
-$ oc get hostedcluster <hosted_cluster_name> -o yaml
+$ oc get -n <hosted_cluster_namespace> nodepool <node_pool_name> -o yaml
+----
++
+.Example output
+[source,yaml]
+----
+status:
+  conditions:
+  - lastTransitionTime: "2024-05-20T15:00:40Z"
+         message: 'Using release image: quay.io/openshift-release-dev/ocp-release:4.15.14-x86_64'
+         reason: AsExpected
+         status: "True"
+         type: ValidReleaseImage
 ----