Updating a cluster within a minor version by using the CLI

You can update, or upgrade, an OKD cluster within a minor version by using the OpenShift CLI (oc).

Prerequisites

• Have access to the cluster as a user with admin privileges. See Using RBAC to define and apply permissions.

• Have a recent etcd backup in case your upgrade fails and you must restore your cluster to a previous state.

• Ensure all Operators previously installed through Operator Lifecycle Manager (OLM) are updated to their latest version in their latest channel. Updating the Operators ensures they have a valid upgrade path when the default OperatorHub catalogs switch from the current minor version to the next during a cluster upgrade. See Upgrading installed Operators for more information.

• Ensure that all machine config pools (MCPs) are running and not paused. Nodes associated with a paused MCP are skipped during the update process. You can pause the MCPs if you are performing a canary rollout update strategy.

• If your cluster uses manually maintained credentials, ensure that the Cloud Credential Operator (CCO) is in an upgradeable state. For more information, see Upgrading clusters with manually maintained credentials for AWS, Azure, or GCP.

About the OpenShift Update Service

The OpenShift Update Service (OSUS) provides over-the-air updates to OKD, including Fedora CoreOS (FCOS). It provides a graph, or diagram, that contains the vertices of component Operators and the edges that connect them. The edges in the graph show which versions you can safely update to. The vertices are update payloads that specify the intended state of the managed cluster components.

The Cluster Version Operator (CVO) in your cluster checks with the OpenShift Update Service to see the valid updates and update paths based on current component versions and information in the graph. When you request an update, the CVO uses the release image for that update to upgrade your cluster. The release artifacts are hosted in Quay as container images.

To allow the OpenShift Update Service to provide only compatible updates, a release verification pipeline drives automation. Each release artifact is verified for compatibility with supported cloud platforms and system architectures, as well as other component packages. After the pipeline confirms the suitability of a release, the OpenShift Update Service notifies you that it is available.

Two controllers run during continuous update mode. The first controller continuously updates the payload manifests, applies the manifests to the cluster, and outputs the controlled rollout status of the Operators to indicate whether they are available, upgrading, or failed. The second controller polls the OpenShift Update Service to determine if updates are available.

During the upgrade process, the Machine Config Operator (MCO) applies the new configuration to your cluster machines. The MCO cordons the number of nodes as specified by the maxUnavailable field on the machine configuration pool and marks them as unavailable. By default, this value is set to 1. The MCO then applies the new configuration and reboots the machine.

If you use Fedora machines as workers, the MCO does not update the kubelet because you must update the OpenShift API on the machines first.

With the specification for the new version applied to the old kubelet, the Fedora machine cannot return to the Ready state. You cannot complete the update until the machines are available. However, the maximum number of unavailable nodes is set to ensure that normal cluster operations can continue with that number of machines out of service.

The OpenShift Update Service is composed of an Operator and one or more application instances.

Additional resources

• Support policy for unmanaged Operators

OKD upgrade channels and releases

In OKD 4.1, Red Hat introduced the concept of channels for recommending the appropriate release versions for cluster upgrades. By controlling the pace of upgrades, these upgrade channels allow you to choose an upgrade strategy. Upgrade channels are tied to a minor version of OKD. For instance, OKD 4.7 upgrade channels recommend upgrades to 4.7 and upgrades within 4.7. They also recommend upgrades within 4.6 and from 4.6 to 4.7, to allow clusters on 4.6 to eventually upgrade to 4.7. They do not recommend upgrades to 4.8 or later releases. This strategy ensures that administrators explicitly decide to upgrade to the next minor version of OKD.

Upgrade channels control only release selection and do not impact the version of the cluster that you install; the openshift-install binary file for a specific version of OKD always installs that version.

OKD 4.7 offers the following upgrade channel:

• stable-4

stable-4 channel

Releases are added to the stable-4 channel after passing all tests.

You can use the stable-4 channel to upgrade from a previous minor version of OKD.

Upgrade version paths

OKD maintains an upgrade recommendation service that understands the version of OKD you have installed as well as the path to take within the channel you choose to get you to the next release.

You can imagine seeing the following in the stable-4 channel:

• 4.7.0

• 4.7.1

• 4.7.3

• 4.7.4

The service recommends only upgrades that have been tested and have no serious issues. It will not suggest updating to a version of OKD that contains known vulnerabilities. For example, if your cluster is on 4.7.1 and OKD suggests 4.7.4, then it is safe for you to update from 4.7.1 to 4.7.4. Do not rely on consecutive patch numbers. In this example, 4.7.2 is not and never was available in the channel.

The presence of an update recommendation in the stable-4 channel at any point is a declaration that the update is supported. While releases will never be removed from the channel, update recommendations that exhibit serious issues will be removed from the channel. Updates initiated after the update recommendation has been removed are still supported.