Chapter 1. Upgrading ROSA with HCP clusters 1.1. Upgrade options for ROSA with HCP clusters In OpenShift, upgrading means provisioning a new component with updated software and using it to replace an existing component that has outdated software. You can control the impact of upgrades to your workload by controlling which parts of the cluster are upgraded, for example: Upgrade only the hosted control plane This initiates upgrade of the hosted control plane. It does not impact your worker nodes. Upgrade nodes in a machine pool This initiates a rolling replacement of nodes in the specified machine pool, and temporarily impacts the worker nodes on that machine pool. You can also upgrade multiple machine pools concurrently. Important You cannot upgrade the hosted control plane at the same time as any machine pool upgrade. Important To maintain compatibility between nodes in the cluster, nodes in machine pools cannot use a newer version than the hosted control plane. This means that the hosted control plane should always be upgraded to a given version before any machine pools are upgraded to the same version. You can further control the time required for a machine pool upgrade, and the impact of an upgrade to your workload, by editing the --max-surge and --max-unavailable values for each machine pool. These options control the number of nodes that can be upgraded simultaneously on a machine pool, and whether an upgrade provisions excess nodes or makes some existing nodes unavailable or both, for example: To prioritize high workload availability , you can provision excess nodes instead of making existing nodes unavailable by setting a higher value for --max-surge and setting --max-unavailable to 0 . To prioritize lower infrastructure costs , you can make some existing nodes unavailable and avoid provisioning excess nodes by setting a higher value for --max-unavailable and setting --max-surge to 0 . To prioritize upgrade speed by upgrading multiple nodes simultaneously , you can provision excess nodes and allow some existing nodes to be made unavailable by configuring moderate values for both --max-surge and --max-unavailable . For more information about these parameters and their usage, see the ROSA CLI reference for rosa edit machinepool . Additional resources ROSA CLI reference: rosa edit machinepool 1.2. Life cycle policies and planning To plan an upgrade, review the Red Hat OpenShift Service on AWS update life cycle . The life cycle page includes release definitions, support and upgrade requirements, installation policy information and life cycle dates. Upgrades are manually initiated or automatically scheduled. Red Hat Site Reliability Engineers (SREs) monitor upgrade progress and remedy any issues encountered. Note If your control plane is not currently multi-architecture enabled, the upgrade process will first migrate the cluster to a multi-architecture image and then apply the version upgrade. Multi-architecture clusters are capable of running both x86-based and Arm-based workloads. Clusters created after 25 July, 2024 are multi-architecture enabled by default. 1.3. Upgrading the hosted control plane with the ROSA CLI You can manually upgrade the hosted control plane of a ROSA with HCP cluster by using the ROSA CLI. This method schedules the control plane for an upgrade 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 ROSA with HCP cluster with a control plane using version 4.15.z supports machine pools with version 4.13.z and 4.14.z, but the control plane does not support machine pools using version 4.12.z. Prerequisites You have installed and configured the latest version of the ROSA CLI. No machine pool upgrades are in progress or scheduled to take place at the same time as the hosted control plane upgrade. Procedure Verify the current version of your cluster by running the following command: USD rosa describe cluster --cluster=<cluster_name_or_id> 1 1 Replace <cluster_name_or_id> with the cluster name or the cluster ID. List the versions that you can upgrade your control plane to by running the following command: USD 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 Upgrade the cluster's hosted control plane by running the following command: USD 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: USD 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: USD 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). Troubleshooting Sometimes a scheduled upgrade does not initiate. See Upgrade maintenance canceled for more information. 1.4. Upgrading machine pools with the ROSA CLI You can manually upgrade one or more machine pools in a ROSA with HCP cluster by using the ROSA CLI. This method schedules the specified machine pool for an upgrade 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 ROSA with HCP cluster with a control plane using version 4.15.z supports machine pools with version 4.13.z and 4.14.z, but the control plane does not support machine pools using version 4.12.z. Prerequisites You have installed and configured the latest version of the ROSA CLI. No upgrades for the hosted control plane are in progress on the cluster, or scheduled to occur at the same time as the machine pool upgrade. Note Machine pool configurations such as node drain timeout, max-unavailable, and max-surge can affect the timing and success of upgrades. Procedure Verify the current version of your cluster by running the following command: USD 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.0 List the versions that you can upgrade your machine pools to by running the following command: USD 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. Verify the upgrade behavior of the machine pools you intend to upgrade by running the following command: USD 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. Upgrade a machine pool by running the following command: USD 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: USD 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: USD 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.

Commands:
rosa describe cluster --cluster=<cluster_name_or_id> 1
rosa list upgrade --cluster=<cluster_name_or_id>
VERSION NOTES 4.14.8 recommended 4.14.7 4.14.6
rosa upgrade cluster -c <cluster_name_or_id> --control-plane [--schedule-date=<yyyy-mm-dd> --schedule-time=<HH:mm>] --version <version_number>
rosa upgrade cluster -c <cluster_name_or_id> --control-plane --version <version_number>
rosa upgrade cluster -c <cluster_name_or_id> --control-plane --schedule-date=<yyyy-mm-dd> --schedule-time=<HH:mm> --version=<version_number>
rosa describe cluster --cluster=<cluster_name_or_id> 1
OpenShift Version: 4.14.0
rosa list upgrade --cluster <cluster-name> --machinepool <machinepool_name>
VERSION NOTES 4.14.5 recommended 4.14.4 4.14.3
rosa describe machinepool --cluster=<cluster_name_or_id> <machinepool_name>
Replicas: 5 Node drain grace period: 30 minutes Management upgrade: - Type: Replace - Max surge: 20% - Max unavailable: 20%
rosa upgrade machinepool -c <cluster_name> <machinepool_name> [--schedule-date=<yyyy-mm-dd> --schedule-time=<HH:mm>] --version <version_number>
rosa upgrade machinepool -c <cluster_name> <machinepool_name> --version <version_number>
rosa upgrade machinepool -c <cluster_name> <machinepool_name> --schedule-date=<yyyy-mm-dd> --schedule-time=<HH:mm> --version <version_number>