Chapter 2. Upgrading ROSA (classic architecture) clusters

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.