Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

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.

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

You can control the impact of updates to your workload by controlling which parts of the cluster are updated, for example:

Update only the hosted control plane
This initiates update of the hosted control plane. It does not impact your worker nodes.
Update nodes in a machine pool
Red Hat OpenShift Service on AWS machine pool updates are designed to fully replace each node in a machine pool during the update process. This provides additional security and stability benefits over performing an in-place update. Updating 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 update multiple machine pools concurrently.
Important

You cannot update the hosted control plane at the same time as any machine pool update. You will need to update the hosted control plane first, and then update 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 updated to a given version before any machine pools are updated to the same version.

You can further control the time required for a machine pool update, and the impact of an update 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 updated simultaneously on a machine pool, and whether an update 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 update speed by updating 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.

1.2. Life cycle policies and planning
Copy link

To plan an upgrade, see the Red Hat OpenShift Service on AWS update life cycle in the "Additional resources" section. The life cycle page includes release definitions, support and update requirements, installation policy information and life cycle dates.

Updates are manually initiated or automatically scheduled. Red Hat Site Reliability Engineers (SREs) monitor update progress and remedy any issues encountered.

You can use update channels to decide which Red Hat OpenShift Service on AWS minor version to update your clusters to. Red Hat OpenShift Service on AWS supports updates through the stable-4.y, eus-4.y, and fast-4.y channels.

Note

If your control plane is not currently multi-architecture enabled, the update process will first migrate the cluster to a multi-architecture image and then apply the version update. 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.

You can use Red Hat OpenShift Service on AWS channels to view available cluster update options and apply patches or z-stream updates in your existing channel. You can also view the update path to newer y-stream versions if available.

1.3.1. Channel groups and channels
Copy link

Channel groups in Red Hat OpenShift Service on AWS are similar to channels, but there is no specific version with channel groups. When you select a channel group, your Red Hat OpenShift Service on AWS cluster receives z-stream updates for your current channel group. These channel groups typically include:

  • fast: cluster receives the latest updates as soon as they are available.
  • stable: cluster receives updates after they have been thoroughly tested.
  • eus: Extended Update Support channel, allowing for extended support for even-numbered versions, for example, 4.16, 4.18, or 4.20.

By moving from channel groups to channels, you can have more control over your cluster updates. Instead of receiving patch/z-stream updates only for a particular channel group, by using channels you can view the available updates associated with a minor release version, and determine if there is a path available to that minor/y+1/y+2 version.

Important

The channel group option is being deprecated. If you set a channel group only, Red Hat OpenShift Service on AWS will default to preserving the current channel’s target version. For example, a stable-4.20 cluster moving to the eus channel group will use the eus-4.20 channel by default, if the current cluster version is a member of the eus-4.20 channel.

1.3.2. Cluster update options
Copy link

The process for updating your cluster is based on the updates that are available for your current version, and what level of release you are interested in, such as z-stream or y-stream updates.

  • Patch (z-stream) updates: You do not need to change the channel when performing a patch update within your current minor version. For example, if you have your cluster at version 4.19.12, you can stay within your current stable-4.19 channel, and decide to update your cluster when there are updates available, such as 4.19.13, 4.19.14, 4.19.17, 4.19.20 until you have the latest updates for that minor version.

  • Minor version (y-stream) updates: To update to a new minor release, you must change the channel to the next release channel.

    For example, if you have your cluster at version 4.19.12, you can switch the channel to stable-4.20 or stable-4.21 and check if there is an update path available for those versions.

    If stable-4.20 has an update path available, it shows you the z-stream updates for your current version, as well as the updates to the y+1 version, such as 4.19.14, 4.19.17, 4.19.20, 4.19.23, 4.19.27, 4.20.0.

    If you select stable-4.21, the available updates might be 4.19.14, 4.19.17, 4.19.20, 4.19.23, 4.19.27, 4.20.0, 4.20.3, 4.20.4, 4.20.6, 4.20.7, with all the z-stream/patch updates displayed right through to the y+2 version of 4.21.0.

You can change your cluster’s channel either through the Cluster Overview → Details page in the web console or by using the rosa edit cluster command in ROSA CLI.

When you have set the channel and an update is initiated, the Cluster Version Operator (CVO) retrieves the target release image and begins applying the changes to the cluster.

You can switch the channel on a Red Hat OpenShift Service on AWS cluster to access update options within a current minor version (y-stream), or the subsequent minor versions (y+1, y+2). The version number in the channel represents the target minor version.

For example, if your cluster is on stable-4.18, switching the channel to stable-4.19 shows update paths from 4.18.z to 4.19.z, if such paths are available. This strategy ensures that administrators must explicitly initiate minor version updates, and they never occur automatically.

Procedure

  1. Log in to OpenShift Cluster Manager.
  2. Click Fleet Management > Clusters.
  3. Select the cluster for which you want to see the update options.

  4. To view the cluster details, click the Overview tab.

    • The Channel field displays the current update channel for the cluster.

  5. Select the new update channel.

    1. In the Channel field, click the Edit channel icon next to the current channel name.
    2. On the Edit channel dialog, select the required channel version.

    3. Click Save.

      • The Channel field updates to display the new update channel.
      • The Version field displays the Update link if updates are available for your selected channel.

You can manually update the hosted control plane of a Red Hat OpenShift Service on AWS cluster by using the ROSA command-line interface (CLI) (rosa). This method schedules the control plane for an update 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.17.z supports machine pools with version 4.15.z and 4.16.z, but the control plane does not support machine pools using version 4.14.z.

Prerequisites

  • You have installed and configured the latest version of the ROSA CLI.
  • No machine pool updates are in progress or scheduled to take place at the same time as the hosted control plane update.

Procedure

  1. 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.

  2. List the versions that you can update 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.18.18   recommended
4.18.17
4.18.16

  3. Set the update channel. For more information about channels, refer to "Channels in Red Hat OpenShift Service on AWS clusters". 

    $ rosa edit cluster -c <cluster_name_or_id> --channel <channel>

    For example, to set the channel to stable-4.19: 

    $ rosa edit cluster -c <cluster_name_or_id> --channel stable-4.19

  4. Update 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 update 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 update.

    • To schedule an update 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 update at the specified time in Coordinated Universal Time (UTC).

Troubleshooting

1.6. Updating machine pools with the ROSA CLI
Copy link

You can manually update one or more machine pools in a Red Hat OpenShift Service on AWS cluster by using the ROSA command-line interface (CLI) (rosa). This method schedules the specified machine pool for an update 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.19.z supports machine pools with version 4.17.z and 4.18.z, but the control plane does not support machine pools using version 4.16.z.

Prerequisites

  • You have installed and configured the latest version of the ROSA CLI.
  • No updates for the hosted control plane are in progress on the cluster, or scheduled to occur at the same time as the machine pool update.
Note

Machine pool configurations such as node drain timeout, max-unavailable, and max-surge can affect the timing and success of updates.

Procedure

  1. 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.17.0

  2. List the versions that you can update 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.17.5   recommended
4.17.4
4.17.3
    Important

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

  3. Verify the update behavior of the machine pools you intend to update 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 update:
- 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 update. This machine pool can therefore update 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 updates 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. Update 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 update multiple machine pools concurrently by running this command for each machine pool you want to update.

    • To schedule the immediate update 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 update, which initiates a rolling replacement of all nodes in the specified machine pool.

    • To schedule an update 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 update at the specified time and date in Coordinated Universal Time (UTC). This initiates a rolling replacement of all nodes in the specified machine pool, beginning at the specified time.

Legal Notice
Copy link

Copyright © Red Hat

OpenShift documentation is licensed under the Apache License 2.0 (https://www.apache.org/licenses/LICENSE-2.0).

Modified versions must remove all Red Hat trademarks.

Portions adapted from https://github.com/kubernetes-incubator/service-catalog/ with modifications by Red Hat.

Red Hat, Red Hat Enterprise Linux, the Red Hat logo, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

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

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of the OpenJS Foundation.

The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation’s permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Legal Notice

Theme

© 2026 Red HatBack to top