Upgrading

Red Hat OpenShift Service on AWS 4

Understanding upgrading options for Red Hat OpenShift Service on AWS

Red Hat OpenShift Documentation Team

Abstract

This document provides information about upgrading Red Hat OpenShift Service on AWS (ROSA) clusters.

Chapter 1. Upgrading Red Hat OpenShift Service on AWS clusters

In Red Hat OpenShift Service on AWS, upgrading provisions a new component with updated software and uses it to replace an existing component that has outdated software.

1.1. Upgrade options for Red Hat OpenShift Service on AWS clusters

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: Red Hat OpenShift Service on AWS machine pool upgrades are designed to fully replace each node in a machine pool during the upgrade process. This provides additional security and stability benefits over performing an in-place upgrade. Upgrading the nodes in a machine pool 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. You will need to upgrade the hosted control plane first, and then upgrade machine pools.

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

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 Red Hat OpenShift Service on AWS 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 Red Hat OpenShift Service on AWS 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:
```
$ rosa describe cluster --cluster=<cluster_name_or_id>
```
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:
```
$ 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:
```
$ rosa upgrade cluster -c <cluster_name_or_id> [--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> --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> --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:
```
$ rosa describe cluster --cluster=<cluster_name_or_id>
```
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:
```
$ 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:
```
$ 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:
```
$ 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.

Legal Notice

Except as otherwise noted below, the text of and illustrations in this documentation are licensed by Red Hat under the Creative Commons Attribution–Share Alike 3.0 Unported license . If you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, the Red Hat logo, JBoss, Hibernate, and RHCE are trademarks or registered trademarks of Red Hat, LLC. or its subsidiaries in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

XFS is a trademark or registered trademark of Hewlett Packard Enterprise Development LP or its subsidiaries in the United States and other countries.

The OpenStack® Word Mark and OpenStack logo are trademarks or registered trademarks of the Linux Foundation, used under license.

All other trademarks are the property of their respective owners.