Upgrade an Azure Red Hat OpenShift with hosted control planes cluster (preview)

Upgrade your Azure Red Hat OpenShift with hosted control planes cluster to access new OpenShift features, security updates, and bug fixes. Azure Red Hat OpenShift with hosted control planes uses a decoupled upgrade model where the control plane and node pools upgrade independently. Use this upgrade model to plan y-stream control plane upgrades and node pool upgrades that align with your maintenance windows.

Prerequisites

An existing Azure Red Hat OpenShift with hosted control planes cluster.
Azure CLI version 2.67.0 or later. To install or update, see Install the Azure CLI.

The ARO HCP CLI extension is installed. If you need to install it, download the wheel file for the ARO HCP CLI extension.

The Contributor role and the User Access Administrator role (or the Owner role) on the resource group or subscription that contains the cluster.

How upgrades work

Azure Red Hat OpenShift with hosted control planes uses a decoupled upgrade model where the control plane and node pools upgrade independently, with version compatibility rules that govern which combinations are supported.

Control plane upgrades

Two types of control plane upgrades exist:

Z-stream (patch) upgrades: Red Hat site reliability engineers (SREs) apply these upgrades automatically. Z-stream upgrades are maintenance updates within the same minor version, such as upgrading from 4.22.1 to 4.22.2. These upgrades apply security and bug fixes without blocking cluster operations. You can continue creating node pools, scaling workloads, and deploying applications while the SREs upgrade the control plane to a new z-stream version. You don't need to take any action for z-stream control plane upgrades.
Y-stream (minor version) upgrades: You initiate these upgrades by using the Azure CLI. Y-stream upgrades move the control plane to a new minor version, such as upgrading from 4.21 to 4.22. You control when y-stream upgrades happen so that you can align upgrades with your change management processes and maintenance windows.

Node pool upgrades

You always initiate node pool upgrades, for both z-stream and y-stream versions. Node pool upgrades use a rolling replacement strategy that replaces each node in the node pool during the upgrade process. You can upgrade multiple node pools concurrently.

Supported version combinations

Before you upgrade your cluster, understand the version skew constraints between the control plane and node pools. Violating these constraints can leave your cluster in an unsupported state.

The following rules apply:

Node pool minor version must not exceed the control plane minor version. A node pool can run a higher z-stream (patch) version than the control plane within the same minor version. Always upgrade the control plane to a target minor version before upgrading any node pools to that minor version.
Two minor version support window. The control plane supports node pools within two minor y-stream versions. For example, a control plane running version 4.22 supports node pools running version 4.21 and 4.20, but doesn't support node pools running version 4.19.
Up to two minor version jumps. You can upgrade a node pool to a newer z-stream release within the same minor version, or jump up to two minor versions. For example, you can upgrade a node pool from 4.20.z to 4.22.z, but not from 4.20.z to 4.23.z. The target version must not exceed the control plane minor version.

The following table shows examples of allowed and disallowed version combinations:

Control plane version	Node pool version	Supported	Reason
4.22	4.22	Yes	Node pool matches control plane
4.22	4.21	Yes	Within two minor versions (N-1)
4.22	4.20	Yes	Within two minor versions (N-2)
4.22	4.19	No	Exceeds two minor version skew (N-3)
4.21	4.22	No	Node pool newer than control plane

Check the current cluster version

Before you upgrade, check the current OpenShift version of your cluster.

oc get clusterversion version

The output shows the current OpenShift version:

NAME      VERSION   AVAILABLE   PROGRESSING   SINCE   STATUS
version   4.20.26   True        False         70s     Cluster version is 4.20.26

Upgrade the control plane

To upgrade the control plane to a new minor version (y-stream), list the available versions and then initiate the upgrade by using Azure CLI.

Important

Red Hat SREs automatically apply z-stream control plane upgrades, so you don't need to take any action. Use the following procedure only for y-stream (minor version) upgrades.

Set the environment variables for your resource group, cluster name, and Azure region if you haven't already:
```
CUSTOMER_RG_NAME="<resource-group-name>"
CLUSTER_NAME="<cluster-name>"
LOCATION="<azure-region>"
```

List the available OpenShift versions in your Azure region by running the following command:

az aro hcp version list \
  --location "${LOCATION}" \
  --query "[].{name:name, channelGroup:properties.channelGroup, enabled:properties.enabled}"
  --output table

The output lists the available versions:

Name     ChannelGroup    Enabled
-------  --------------  ---------
4.22.0   stable          True
4.22.1   stable          True
4.22.2   stable          True
4.22.3   stable          True
...

Identify the target version for your upgrade. You can only upgrade to the next minor version. For example, if your control plane is running version 4.20, you can upgrade to version 4.21, but not directly to version 4.22.

Upgrade the control plane by running the following command. Replace <target-version> with the desired OpenShift version, such as 4.22:

az aro hcp cluster update \
  --name "${CLUSTER_NAME}" \
  --resource-group "${CUSTOMER_RG_NAME}" \
  --version "<target-version>"

Verify the upgrade request was accepted by checking the provisioning state:
```
az aro hcp cluster show \
  --name "${CLUSTER_NAME}" \
  --resource-group "${CUSTOMER_RG_NAME}" \
  --query "{version:properties.version, provisioningState:properties.provisioningState}"
```
When the provisioningState returns Succeeded, the service validates the upgrade path from the current version to the target version and triggers the upgrade. The upgrade runs in the background without blocking other operations on the cluster. If the provisioningState returns Failed, the service couldn't validate the upgrade path.

Upgrade a node pool

After you upgrade the control plane, you can upgrade one or more node pools to a compatible version. Node pool upgrades use a rolling replacement strategy that replaces each node during the upgrade process.

Caution

Don't upgrade a node pool to a higher minor version than the control plane minor version. If you want to upgrade a node pool to a specific version, the control plane must already be running that version or a later version.

Set the environment variables for your resource group, cluster name, node pool name, and Azure region if you haven't already:

CUSTOMER_RG_NAME="<resource-group-name>"
CLUSTER_NAME="<cluster-name>"
NODE_POOL_NAME="<node-pool-name>"
LOCATION="<azure-region>"

Verify the current version of the node pool by running the following command:

az aro hcp cluster nodepool show \
  --cluster-name "${CLUSTER_NAME}" \
  --name "${NODE_POOL_NAME}" \
  --resource-group "${CUSTOMER_RG_NAME}" \
  --query "properties.version"

List the available OpenShift versions in your Azure region:

az aro hcp version list \
  --location "${LOCATION}" \
  --query "[].{name:name, channelGroup:properties.channelGroup, enabled:properties.enabled}"
  --output table

Select a target version for the node pool that meets the following criteria:
- The target minor version is less than or equal to the control plane minor version. The node pool can run a higher patch version than the control plane within the same minor version.
- The target version is a newer z-stream release within the same minor version, or up to two minor versions ahead. You can't jump more than two minor versions. For example, if the node pool is running version 4.19.3, you can upgrade to 4.19.5 (z-stream), 4.20.x (one minor version), or 4.21.x (two minor versions), but not directly to 4.22.0.
Upgrade the node pool by running the following command. Replace <target-version> with the desired OpenShift version, such as 4.22.3:
```
az aro hcp cluster nodepool update \
  --cluster-name "${CLUSTER_NAME}" \
  --name "${NODE_POOL_NAME}" \
  --resource-group "${CUSTOMER_RG_NAME}" \
  --version "<target-version>"
```
The upgrade begins immediately. During the rolling replacement, nodes in the node pool temporarily run at both the old and new versions.

Note

The nodeDrainTimeoutMinutes property on a node pool controls how long the cluster respects Pod Disruption Budget-protected workloads during the upgrade. After this grace period, the cluster forcibly evicts remaining workloads. The default value inherits from the cluster-level setting. You can set this value from 0 (drain without time limitation until complete) to 10080 minutes (one week).
Verify the upgrade request was accepted by checking the provisioning state:
```
az aro hcp cluster nodepool show \
  --cluster-name "${CLUSTER_NAME}" \
  --name "${NODE_POOL_NAME}" \
  --resource-group "${CUSTOMER_RG_NAME}" \
  --query "{version:properties.version, provisioningState:properties.provisioningState}"
```
When provisioningState returns Succeeded, the service has validated the upgrade path and triggered the node pool upgrade. The upgrade runs in the background without blocking other operations on the node pool.
Repeat steps 2 through 6 for each node pool you want to upgrade. You can upgrade multiple node pools concurrently.

Feedback

Was this page helpful?

Last updated on 2026-09-15