Upgrade a cluster with managed identities enabled (preview)

2025-04-10

This article shows you how to upgrade an Azure Red Hat OpenShift cluster with managed identities enabled using the OpenShift web console or the managed-upgrade-operator (MUO).

Important

Currently, this Azure Red Hat OpenShift feature is offered in preview only. Preview features are available on a self-service, opt-in basis. Previews are provided "as is" and "as available" and are excluded from the service-level agreements and limited warranty. Azure Red Hat OpenShift previews are partially covered by customer support on a best-effort basis. The features aren't meant for production use.

As part of the Azure Red Hat OpenShift cluster lifecycle, you need to perform periodic upgrades to the latest version of the OpenShift platform. Upgrading your Azure Red Hat OpenShift clusters enables you to obtain the latest features and functionalities and apply the latest security releases.

Prerequisites

Before you begin, verify you meet the following requirements needed to be successful in upgrading an ARO cluster.

You're running the Azure CLI version 2.67.0 or later. Run az --version to find your current version. If you need to install or upgrade the Azure CLI, see Install Azure CLI.
You have access to an existing Azure Red Hat OpenShift cluster as a user with admin privileges.
You updated your Azure Red Hat OpenShift pull secret for an existing Azure Red Hat OpenShift 4.x cluster, including the cloud.openshift.com entry from your pull secret enables your cluster to start sending telemetry data to Red Hat.
For more information, see Add or update your Red Hat pull secret on an Azure Red Hat OpenShift 4 cluster.
Verify the federated identity credentials used by the cluster's managed identities are valid/updated before starting the upgrade. For more information, see Reconcile federated identity credentials for your Azure Red Hat OpenShift cluster with managed identities enabled (preview).

Download Azure Red Hat OpenShift extension wheel file (Preview only)

To run the commands in this article, you need to download the ARO extension wheel file from https://aka.ms/az-aroext-latest. To install the extension, run the following command:

az extension add -s <path to downloaded whl file>

Set the upgradeable-to annotation on the Azure Red Hat OpenShift cluster's CloudCredential resource

Before you can upgrade an Azure Red Hat OpenShift cluster with managed identity enabled, set the upgradeable-to annotation on the cluster's CloudCredential resource using the az aro update command:

az aro update --name <CLUSTER_NAME> --resource-group <RESOURCE_GROUP> --upgradeable-to <VERSION>

Where:

--name is the name of the cluster
--resource-group is the name of the network resource group. You can configure the default group using az-config --defaults group=<name>.
--upgradeable-to is the OpenShift version number you intend to upgrade to, specified in the format x.y.z

For more information about the upgradeable-to annotation, see Preparing to update a cluster.

Note

The previously shown az aro update command doesn't trigger the OpenShift version update. To complete the OpenShift version update, finish the remaining steps in this article.

Check for Azure Red Hat OpenShift cluster upgrades using the web console

From the left navigation menu of the OpenShift web console (the default when you sign in as the kubeadmin), select the Administration tab.
Select Cluster Settings and open the Details tab. You should see the version, update status, and channel. The channel isn't configured by default.
Select the Channel link, and at the prompt enter the desired update channel, for example stable-4.16. Once the desired channel is chosen, a graph that shows available releases and channels is displayed. If the Update Status for your cluster shows Updates Available, you can update your cluster.

Upgrade your Azure Red Hat OpenShift cluster with the OpenShift web console

From the OpenShift web console in the previous step, set the channel according to the version that you want to update to, such as stable-4.16. For more information, see Update channels.

Selection a version to update to, and select Update. You see the update status change to:
Update to <product-version> in progress. You can review the progress of the cluster update by watching the progress bars for the operators and nodes.

Schedule individual upgrades using the managed-upgrade-operator

Use the managed-upgrade-operator (MUO) to upgrade your Azure Red Hat OpenShift cluster.

The MUO manages automated cluster upgrades. The MUO starts the cluster upgrade, but it doesn't perform any activities of the cluster upgrade process itself. The OpenShift Container Platform (OCP) is responsible for upgrading the clusters. The goal of the MUO is to satisfy the operating conditions that a managed cluster must hold, both before and after starting the cluster upgrade.

Prepare the configuration file, as shown in the following example for upgrading to OpenShift 4.16.
```
apiVersion: upgrade.managed.openshift.io/v1alpha1
kind: UpgradeConfig
metadata:
  name: managed-upgrade-config
  namespace: openshift-managed-upgrade-operator
spec:
  type: "ARO"
  upgradeAt: "2025-04-08T03:20:00Z"
  PDBForceDrainTimeout: 60
  desired:
    channel: "stable-4.16"
    version: "4.16.37"
```
Where:
- channel is the channel the configuration file pulls from, according to the lifecycle policy.
- version is the version that you wish to upgrade to, such as 4.16.37.
- upgradeAT is the time when the upgrade takes place.
Apply the configuration file:
```
$ oc create -f <file_name>.yaml
```

Next steps

Learn to upgrade an Azure Red Hat OpenShift cluster using the OC CLI.
You can find information about available OpenShift Container Platform advisories and updates in the errata section of the Customer Portal.

Share via