Chapter 1. Upgrading ROSA with HCP clusters

Procedure

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

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>

   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

3. Upgrade the cluster’s hosted control plane by running the following command:

   $ 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:

     $ 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:

     $ 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).

Procedure

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

   Example output

   OpenShift Version:     4.14.0

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>

   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.

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>

   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.

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>

   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.

Procedure

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

2. List the versions that you can upgrade your control plane and machine pools to by running the following commands:

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

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

      Note

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

3. 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> <machinepool_name> [--schedule-date=XX --schedule-time=XX] [--version <version_number>]

     Your machine pool is now scheduled for an upgrade.

Procedure

1. Log in to OpenShift Cluster Manager.
2. Select a cluster to upgrade.
3. Click the Settings tab.

4. In the Update strategy pane, select which type of update you want:

   • For individual updates, you can request the upgrade either immediately (to start within an hour) or at a future time.

   • For recurring updates, select a recurring date and time to start the upgrade automatically to the latest x.y.Z (z-stream) version available.

     Important

     Recurring updates are applicable only for z-stream updates. Minor version or y-stream updates need to be done manually. You will be notified when a new y-stream update is available.

5. In the Update strategy pane, click Save to apply your update strategy.

6. In the Update status pane, review the Update available information and click Update.

   Note

   The Update button is enabled only when an upgrade is available.

7. The Update cluster dialog opens. Recommended cluster upgrades appear in the Select version pane. Select the version you want to upgrade your cluster to, and click Next.

8. Optional: For ROSA clusters that use AWS Security Token Service (STS), the account-level and cluster-specific Operator roles might need to be updated, depending on the selected target version.

   1. In the ROSA CLI, run the rosa list account-roles command to list and verify that the account roles are compatible with the target minor version chosen for the upgrade. If the roles are not compatible, run the rosa upgrade account-roles command to upgrade the account roles to the latest OpenShift version.
   2. In the ROSA CLI, run the rosa list operator-roles command to list and verify that Operator roles associated with the cluster are compatible with the target minor version chosen for the upgrade. If not, run the rosa upgrade operators-roles command to upgrade the cluster’s Operator roles to the latest OpenShift version.
   3. If you select an update version that requires approval, provide an administrator’s acknowledgment by typing Acknowledge into the field provided, and click Next.

9. 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.
10. After reviewing the version and schedule summary, select Confirm update.
11. Click Close to exit out of the Update cluster dialog.

Procedure

1. Log in to OpenShift Cluster Manager.
2. Select the cluster with the scheduled upgrade.
3. Click the Settings tab.
4. In the Update status pane, click Cancel this update.
5. Review the update details in the Cancel update dialog and click Cancel this update.