Upgrading
Understanding upgrading options for Red Hat OpenShift Service on AWS
Abstract
Chapter 1. Upgrading ROSA clusters with STS
1.1. 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.
1.2. Upgrading a ROSA cluster that uses STS
There are two methods to upgrade Red Hat OpenShift Service on AWS (ROSA) clusters that uses the AWS Security Token Service (STS):
-
Individual upgrades through the ROSA CLI (
rosa
) - Individual upgrades through the OpenShift Cluster Manager console
For steps to upgrade a ROSA cluster that does not use the AWS Security Token Service (STS), see Upgrading ROSA clusters.
1.2.1. Upgrading with the ROSA CLI
You can upgrade a Red Hat OpenShift Service on AWS (ROSA) cluster that uses the AWS Security Token Service (STS) manually by using the ROSA CLI (rosa
).
This method schedules the cluster for an immediate upgrade, if a more recent version is available.
Prerequisites
- You have installed and configured the latest ROSA CLI on your installation host.
Procedure
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.
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.
To upgrade a cluster to the latest available version, enter the following command:
$ rosa upgrade cluster --cluster=<cluster_name|cluster_id>
The cluster is scheduled for an immediate upgrade. This action can take an hour or longer, depending on your workload configuration, such as pod disruption budgets.
You will receive an email when the upgrade is complete. You can also check the status by running the
rosa describe cluster
command again from the ROSA CLI or view the status in OpenShift Cluster Manager console. :!sts:
Troubleshooting
- Sometimes a scheduled upgrade does not trigger. See Upgrade maintenance cancelled for more information.
1.2.2. Scheduling individual upgrades through the OpenShift Cluster Manager console
You can schedule upgrades for a Red Hat OpenShift Service on AWS cluster that uses the AWS Security Token Service (STS) manually one time by using OpenShift Cluster Manager console.
Procedure
- Log in to OpenShift Cluster Manager.
- Select a cluster to upgrade.
- Click the Settings tab.
- In the Update strategy pane, select Individual Updates.
- Select the version you want to upgrade your cluster to. Recommended cluster upgrades appear in the UI.
- If you select an update version that requires approval, provide an administrator’s acknowledgment and click Approve and continue.
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.
NoteYou cannot change the node drain grace period after you start the upgrade process.
- In the Update strategy pane, click Save to apply your update strategy.
In the Update status pane, review the Update available information and click Update.
NoteThe Update button is enabled only when an upgrade is available.
- In the Select version dialog, choose a target upgrade version and click Next.
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.
After reviewing the version and schedule summary, select Confirm update.
The cluster is scheduled for an upgrade to the target version. This action can take an hour or longer, depending on the selected upgrade schedule and your workload configuration, such as pod disruption budgets.
The status is displayed in the Update status pane.
Troubleshooting
- Sometimes a scheduled upgrade does not trigger. See Upgrade maintenance cancelled for more information.
Chapter 2. Upgrading ROSA clusters
2.1. 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.
2.2. Upgrading a ROSA cluster
There are three methods to upgrade Red Hat OpenShift Service on AWS (ROSA) clusters:
-
Individual upgrades through the ROSA CLI (
rosa
) - Individual upgrades through the OpenShift Cluster Manager
- Recurring upgrades through the OpenShift Cluster Manager
For steps to upgrade a ROSA cluster that uses the AWS Security Token Service (STS), see Upgrading ROSA clusters with STS.
When following a scheduled upgrade policy, there might be a delay of an hour or more before the upgrade process begins, even if it is an immediate upgrade. Additionally, the duration of the upgrade might vary based on your workload configuration.
2.2.1. Upgrading with the ROSA CLI
You can upgrade a Red Hat OpenShift Service on AWS (ROSA) cluster manually by using the ROSA CLI (rosa
).
This method schedules the cluster for an immediate upgrade, if a more recent version is available.
Prerequisites
- You have installed and configured the latest ROSA CLI on your installation host.
Procedure
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.
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.
To upgrade a cluster to the latest available version, enter the following command:
$ rosa upgrade cluster --cluster=<cluster_name|cluster_id>
The cluster is scheduled for an immediate upgrade. This action can take an hour or longer, depending on your workload configuration, such as pod disruption budgets.
You will receive an email when the upgrade is complete. You can also check the status by running the
rosa describe cluster
command again from the ROSA CLI or view the status in OpenShift Cluster Manager console.
Troubleshooting
- Sometimes a scheduled upgrade does not trigger. See Upgrade maintenance cancelled for more information.
2.2.2. Scheduling individual upgrades through the OpenShift Cluster Manager console
You can schedule upgrades for a Red Hat OpenShift Service on AWS cluster manually one time by using OpenShift Cluster Manager console.
Procedure
- Log in to OpenShift Cluster Manager.
- Select a cluster to upgrade.
- Click the Settings tab.
- In the Update strategy pane, select Individual Updates.
- Select the version you want to upgrade your cluster to. Recommended cluster upgrades appear in the UI.
- If you select an update version that requires approval, provide an administrator’s acknowledgment and click Approve and continue.
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.
NoteYou cannot change the node drain grace period after you start the upgrade process.
- In the Update strategy pane, click Save to apply your update strategy.
In the Update status pane, review the Update available information and click Update.
NoteThe Update button is enabled only when an upgrade is available.
- In the Select version dialog, choose a target upgrade version and click Next.
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.
After reviewing the version and schedule summary, select Confirm update.
The cluster is scheduled for an upgrade to the target version. This action can take an hour or longer, depending on the selected upgrade schedule and your workload configuration, such as pod disruption budgets.
The status is displayed in the Update status pane.
Troubleshooting
- Sometimes a scheduled upgrade does not trigger. See Upgrade maintenance cancelled for more information.
2.2.3. Scheduling recurring upgrades for your cluster
You can schedule recurring, automatic upgrades for z-stream patch versions for your Red Hat OpenShift Service on AWS cluster through the OpenShift Cluster Manager console.
Procedure
- Log in to OpenShift Cluster Manager.
- Select a cluster to upgrade.
- Click the Settings tab.
- In the Update strategy pane, select Recurring updates.
- Select a preferred day of the week and start time for the upgrade, when updates are available.
- Provide an administrator’s acknowledgment and click Approve and continue. OpenShift Cluster Manager does not start scheduled y-stream updates for minor versions without receiving an administrator’s acknowledgment.
- 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.
In the Update strategy pane, click Save to apply your update strategy.
When upgrades are available, they are automatically applied to the cluster on the preferred day of the week and start time.
Chapter 3. Upgrading ROSA with HCP
You can upgrade Red Hat OpenShift Service on AWS (ROSA) with hosted control planes (HCP) clusters by individually upgrading the hosted control plane and the machine pools with the ROSA command line interface (CLI), rosa
.
Use one of the following methods to upgrade your HCP clusters:
- Upgrade only your hosted control plane. This does not impact your worker nodes.
- Upgrade only your machine pool. This initiates a rolling reboot of a specific machine pool and temporarily impacts the worker nodes on the specific machine pool. It does not impact all your worker nodes if you have multiple machine pools.
Upgrade your hosted control plane first and then your machine pool.
NoteIf you want to upgrade both your hosted control plane and your machine pool to the same version, you must upgrade the hosted control plane first.
To plan an upgrade, review the ROSA with HCP update life cycle documentation. The life cycle page includes release definitions, support and upgrade requirements, installation policy information, and life cycle dates.
Hosted control plane upgrade duration varies based on your workload configuration, and machine pool upgrade duration varies based on the number of worker nodes.
3.1. Upgrading with the ROSA CLI
You can manually upgrade a ROSA with HCP cluster by using the ROSA CLI. This method schedules the cluster for an immediate upgrade if a more recent version is available.
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.
Procedure
Verify the current version of your cluster by running the following command:
$ 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 and machine pools to by running the following commands:
For the control plane versions, run the following command:
$ rosa list upgrade --cluster=<cluster_name|cluster_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
For the machine pool versions, run 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 4.14.2 4.14.1
NoteThe latest available update for machine pools is limited to the current current version of the control plane. Ensure your control plane is up to date first.
Upgrade your cluster with one of the following options:
Upgrade the cluster’s hosted control plane by running the following command:
$ rosa upgrade cluster -c <cluster_name> --control-plane [--schedule-date=XX --schedule-time=XX] [--version <version_number>]
Your hosted control plane is now scheduled for an upgrade.
Upgrade a specific machine pool on your cluster by running the following command:
$ rosa upgrade machinepool -c <cluster_name> <your_machine_pool_id> [--schedule-date=XX --schedule-time=XX] [--version <version_number>]
Your machine pool is now scheduled for an upgrade.
Troubleshooting
- Sometimes a scheduled upgrade does not initiate. See Upgrade maintenance cancelled for more information.