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 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
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
Copy link

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.

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

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

    $ rosa describe cluster --cluster=<cluster_name_or_id>
    1
    Copy to Clipboard Toggle word wrap
    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>
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

  3. 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>
    Copy to Clipboard Toggle word wrap

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

      $ rosa upgrade cluster -c <cluster_name_or_id> --version <version_number>
      Copy to Clipboard Toggle word wrap

      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>
      Copy to Clipboard Toggle word wrap

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

Troubleshooting

1.4. Upgrading machine pools with the ROSA CLI
Copy link

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

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

    $ rosa describe cluster --cluster=<cluster_name_or_id>
    1
    Copy to Clipboard Toggle word wrap
    1
    Replace <cluster_name_or_id> with the cluster name or the cluster ID.

    Example output

    OpenShift Version:     4.14.0
    Copy to Clipboard Toggle word wrap

  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>
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

    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>
    Copy to Clipboard Toggle word wrap

    Example output

    Replicas: 5
Node drain grace period:   30 minutes

Management upgrade:
- Type: Replace
- Max surge: 20%
- Max unavailable: 20%
    Copy to Clipboard Toggle word wrap

    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>
    Copy to Clipboard Toggle word wrap

    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>
      Copy to Clipboard Toggle word wrap

      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>
      Copy to Clipboard Toggle word wrap

      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
Copy link

Copyright © 2025 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 Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.

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.

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

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.

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

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

Theme

© 2025 Red Hat