Upgrading

Procedure

1. Verify the current version of your cluster by running the following command:

   $ rosa describe cluster --cluster=<cluster_name_or_id> 1

   1

   Replace <cluster_name_or_id> with the cluster name or the cluster ID.

2. List the versions that you can upgrade your control plane to by running the following command:

   $ rosa list upgrade --cluster=<cluster_name_or_id>

   The command returns a list of available updates, including the recommended version.

   Example output

   VERSION  NOTES
   4.14.8   recommended
   4.14.7
   4.14.6

3. Upgrade the cluster’s hosted control plane by running the following command:

   $ rosa upgrade cluster -c <cluster_name_or_id> --control-plane [--schedule-date=<yyyy-mm-dd> --schedule-time=<HH:mm>] --version <version_number>

   • To schedule an immediate upgrade to the specified version, run the following command:

     $ rosa upgrade cluster -c <cluster_name_or_id> --control-plane --version <version_number>

     Your hosted control plane is scheduled for an immediate upgrade.

   • To schedule an upgrade to the specified version at a future date, run the following command:

     $ rosa upgrade cluster -c <cluster_name_or_id> --control-plane --schedule-date=<yyyy-mm-dd> --schedule-time=<HH:mm> --version=<version_number>

     Your hosted control plane is scheduled for an upgrade at the specified time in Coordinated Universal Time (UTC).

Procedure

1. Verify the current version of your cluster by running the following command:

   $ rosa describe cluster --cluster=<cluster_name_or_id> 1

   1

   Replace <cluster_name_or_id> with the cluster name or the cluster ID.

   Example output

   OpenShift Version:     4.14.8

2. List the versions that you can upgrade your machine pools to by running the following command:

   $ rosa list upgrade --cluster <cluster-name> --machinepool <machinepool_name>

   The command returns a list of available updates, including the recommended version.

   Example output

   VERSION  NOTES
   4.14.5   recommended
   4.14.4
   4.14.3

   Important

   Do not upgrade your machine pool to a version higher than your control plane. If you want to move to a higher version, upgrade the control plane to that version first.

3. Verify the upgrade behavior of the machine pools you intend to upgrade by running the following command:

   $ rosa describe machinepool --cluster=<cluster_name_or_id> <machinepool_name>

   Example output

   Replicas: 5
   Node drain grace period:   30 minutes
   
   Management upgrade:
   - Type: Replace
   - Max surge: 20%
   - Max unavailable: 20%

   In the example, these settings allow the machine pool to provision one excess node (max-surge of 20% of replicas) and to have up to one node unavailable (max-unavailable of 20% of replicas) during an upgrade. This machine pool can therefore upgrade two nodes at a time, by provisioning one new node in excess of the replica count, and by making one node unavailable and replacing it. Node upgrades may be delayed by up to 30 minutes (node-drain-grace-period of 30 minutes) if necessary to protect workloads that have a pod disruption budget.

4. Upgrade a machine pool by running the following command:

   $ rosa upgrade machinepool -c <cluster_name> <machinepool_name> [--schedule-date=<yyyy-mm-dd> --schedule-time=<HH:mm>] --version <version_number>

   You can upgrade multiple machine pools concurrently by running this command for each machine pool you want to upgrade.

   • To schedule the immediate upgrade of a machine pool, run the following command:

     $ rosa upgrade machinepool -c <cluster_name> <machinepool_name> --version <version_number>

     The machine pool is scheduled for immediate upgrade, which initiates a rolling replacement of all nodes in the specified machine pool.

   • To schedule an upgrade to start at a future time, run the following command:

     $ rosa upgrade machinepool -c <cluster_name> <machinepool_name> --schedule-date=<yyyy-mm-dd> --schedule-time=<HH:mm> --version <version_number>

     The machine pool is scheduled to begin an upgrade at the specified time and date in Coordinated Universal Time (UTC). This will initiate a rolling replacement of all nodes in the specified machine pool, beginning at the specified time.

Procedure

1. To verify the current version of your cluster, enter the following command:

   $ rosa describe cluster --cluster=<cluster_name|cluster_id> 1

   1

   Replace <cluster_name|cluster_id> with the cluster name or the ID of the cluster.

2. To verify that an upgrade is available, enter the following command:

   $ rosa list upgrade --cluster=<cluster_name|cluster_id>

   The command returns a list of versions to which the cluster can be upgraded, including a recommended version. The recommendation is based on the conditional update risks. Each known risk might apply to all clusters or only clusters matching certain conditions. Refer to the OpenShift release notes to evaluate, validate and determine the appropriate version to upgrade to.

3. To upgrade the cluster to a specified version immediately within the next hour, enter the following command:

   $ rosa upgrade cluster --cluster=<cluster_name|cluster_id> --version <version-id>

   Note

   If you are upgrading an AWS Security Token Service (STS) cluster, this command starts an interactive IAM Roles/policies upgrade mode process that verifies the account and operator role policies for the chosen cluster are compatible with the target version of the upgrade. If the policies are not compatible with the chosen upgrade version, the CLI automatically upgrades them in auto mode.

   The cluster is scheduled for an immediate upgrade as denoted by the Scheduled Time. The upgrade will begin within one hour from the scheduled time.

4. Alternatively, to upgrade the cluster at a future time in UTC, enter the following command:

   $ rosa upgrade cluster --cluster=<cluster_name|cluster_id>   \
             --version <version-id>   \
             --schedule-date yyyy-mm-dd \
             --schedule-time HH:mm

5. To customize the grace period for every node to be drained during the cluster upgrade, enter the following command:

   $ rosa upgrade cluster --cluster=<cluster_name|cluster_id>   \
             --version <version-id>   \
             --node-drain-grace-period 15 minutes

6. You can view the status of the upgrade by entering the following command, which shows both the status (scheduled or started) and the scheduled time.

   $ rosa list upgrade --cluster=<cluster_name|cluster_id>

   Example output

   VERSION  NOTES
   4.15.14  recommended - scheduled for 2024-06-02 15:00 UTC
   4.15.13

Procedure

1. Verify the cluster update has not started using the following command:

   $ rosa list upgrades --cluster=<cluster_name|cluster_id>

   Example output

   VERSION  NOTES
   4.15.14  recommended - scheduled for 2024-06-02 15:00 UTC
   4.15.13

2. Delete a scheduled update by running the following command:

   $ rosa delete upgrade --cluster=<cluster_name|cluster_id>

3. Confirm the deletion by entering Yes at the confirmation prompt.

   Example output

   I: Successfully canceled scheduled upgrade on cluster 'my-cluster'

Procedure

1. Log in to OpenShift Cluster Manager.
2. Select a cluster to upgrade.
3. Click the Settings tab.

4. In the Update strategy pane, select which type of update you want:

   • For individual updates, you can request the upgrade either immediately (to start within an hour) or at a future time.

   • For recurring updates, select a recurring date and time to start the upgrade automatically to the latest x.y.Z (z-stream) version available.

     Important

     Recurring updates are applicable only for z-stream updates. Minor version or y-stream updates need to be done manually. You will be notified when a new y-stream update is available.

5. Optional: In the Node draining pane, select a grace period interval from the list. The grace period enables the nodes to gracefully drain before forcing the pod eviction. The default is 1 hour.

   Important

   You cannot change the node drain grace period after you start the upgrade process.

6. In the Update strategy pane, click Save to apply your update strategy.

7. In the Update status pane, review the Update available information and click Update.

   Note

   The Update button is enabled only when an upgrade is available.

8. The Update cluster dialog opens. Recommended cluster upgrades appear in the Select version pane. Select the version you want to upgrade your cluster to, and click Next.

9. Optional: For ROSA clusters that use AWS Security Token Service (STS), the account-level and cluster-specific Operator roles might need to be updated, depending on the selected target version.

   1. In the ROSA CLI, run the rosa list account-roles command to list and verify that the account roles are compatible with the target minor version chosen for the upgrade. If the roles are not compatible, run the rosa upgrade account-roles command to upgrade the account roles to the latest OpenShift version.
   2. In the ROSA CLI, run the rosa list operator-roles command to list and verify that Operator roles associated with the cluster are compatible with the target minor version chosen for the upgrade. If not, run the rosa upgrade operators-roles command to upgrade the cluster’s Operator roles to the latest OpenShift version.
   3. If you select an update version that requires approval, provide an administrator’s acknowledgment by typing Acknowledge into the field provided, and click Next.

10. In the Schedule update dialog, schedule your cluster upgrade.

    • To upgrade within an hour, select Update now and click Next.
    • To upgrade at a later time, select Schedule a different time and set a time and date for your upgrade. Click Next to proceed to the confirmation dialog.
11. After reviewing the version and schedule summary, select Confirm update.
12. Click Close to exit out of the Update cluster dialog.

Procedure

1. Log in to OpenShift Cluster Manager.
2. Select the cluster with the scheduled upgrade.
3. Click the Settings tab.
4. In the Update status pane, click Cancel this update.
5. Review the update details in the Cancel update dialog and click Cancel this update.