// Module included in the following assemblies:
//
// * upgrading/rosa-hcp-upgrading.adoc

// NOTE: This module is included several times in the same update assembly.

:_mod-docs-content-type: PROCEDURE
[id="rosa-hcp-upgrading-cli-control-plane_{context}"]
// HCP-ONLY: Conditions for updating the hosted control plane WITHOUT updating any machine pools
ifeval::["{context}" != "rosa-hcp-upgrading-whole-cluster"]
= Updating the hosted control plane with the {rosa-cli}

[role="_abstract"]
You can manually update the hosted control plane of a {product-title} cluster by using the {rosa-cli-first}. This method schedules the control plane for an update if a more recent version is available, either immediately, or at a specified future time.

[NOTE]
====
Your control plane only supports machine pools within two minor y-stream versions. For example, a {product-title} cluster with a control plane using version 4.17.z supports machine pools with version 4.15.z and 4.16.z, but the control plane does not support machine pools using version 4.14.z.
====

endif::[]
//END HCP-ONLY conditions

// WHOLE CLUSTER: Condition for updating hosted control plane as part of updating the whole cluster in sequence
ifeval::["{context}" == "rosa-hcp-upgrading-whole-cluster"]
= Updating the hosted control plane

When you need to update the whole cluster, update the hosted control plane first.
endif::[]


.Prerequisites
* You have installed and configured the latest version of the ROSA CLI.
* No machine pool updates are in progress or scheduled to take place at the same time as the hosted control plane update.

//END WHOLE CLUSTER conditions

.Procedure

. Verify the current version of your cluster by running the following command:
+
[source,terminal]
----
$ rosa describe cluster --cluster=<cluster_name_or_id>
----
Replace `<cluster_name_or_id>` with the cluster name or the cluster ID.

. List the versions that you can update your control plane to by running the following command:
+
[source,terminal]
----
$ rosa list upgrade --cluster=<cluster_name_or_id>
----
+
The command returns a list of available updates, including the recommended version.
+
*Example output*
+
[source,terminal]
----
VERSION  NOTES
4.18.18   recommended
4.18.17
4.18.16
----

. Set the update channel. For more information about channels, refer to "Channels in {product-title} clusters".
+
[source,terminal]
----
$ rosa edit cluster -c <cluster_name_or_id> --channel <channel>
----
For example, to set the channel to `stable-4.19`:
+
[source,terminal]
----
$ rosa edit cluster -c <cluster_name_or_id> --channel stable-4.19
----

. Update the cluster's hosted control plane by running the following command:
+
[source,terminal]
----
$ rosa upgrade cluster -c <cluster_name_or_id> [--schedule-date=<yyyy-mm-dd> --schedule-time=<HH:mm>] --version <version_number>
----

** To schedule an immediate update to the specified version, run the following command:
+
[source,terminal]
----
$ rosa upgrade cluster -c <cluster_name_or_id> --version <version_number>
----
+
Your hosted control plane is scheduled for an immediate update.

** To schedule an update to the specified version at a future date, run the following command:
+
[source,terminal]
----
$ rosa upgrade cluster -c <cluster_name_or_id> --schedule-date=<yyyy-mm-dd> --schedule-time=<HH:mm> --version=<version_number>
----
+
Your hosted control plane is scheduled for an update at the specified time in Coordinated Universal Time (UTC).

ifeval::["{context}" != "rosa-hcp-upgrading-whole-cluster"]
.Troubleshooting
* Sometimes a scheduled update does not initiate. See link:https://access.redhat.com/solutions/6648291[Upgrade maintenance canceled] for more information.
endif::[]
