OpenShift Container Platform API compatibility

OpenShift Container Platform API compatibility
- About Kubernetes version skew
Determining the cluster version update path
Selecting the target release

APIs change over time as components are updated. It is important to verify that cloud-native network function (CNF) APIs are compatible with the updated cluster version.

When considering what z-stream release to update to as part of a new y-stream update, you must be sure that all the patches that are in the z-stream version you are moving from are in the new z-stream version. If the version you update to does not have all the required patches, the built-in compatibility of Kubernetes is broken.

For example, if the cluster version is 4.15.32, you must update to 4.16 z-stream release that has all of the patches that are applied to 4.15.32.

About Kubernetes version skew

Each cluster Operator supports specific API versions. Kubernetes APIs evolve over time, and newer versions can be deprecated or change existing APIs. This is referred to as "version skew". For every new release, you must review the API changes. The APIs might be compatible across several releases of an Operator, but compatibility is not guaranteed. To mitigate against problems that arise from version skew, follow a well-defined update strategy.

Additional resources

Determining the cluster version update path

Use the Red Hat OpenShift Container Platform Update Graph tool to determine if the path is valid for the z-stream release you want to update to. Verify the update with your Red Hat Technical Account Manager to ensure that the update path is valid for telco implementations.

The <4.y+1.z> or <4.y+2.z> version that you update to must have the same patch level as the <4.y.z> release you are updating from.

The OpenShift update process mandates that if a fix is present in a specific <4.y.z> release, then the that fix must be present in the <4.y+1.z> release that you update to.

Figure 1. Bug fix backporting and the update graph

OpenShift development has a strict backport policy that prevents regressions. For example, a bug must be fixed in 4.16.z before it is fixed in 4.15.z. This means that the update graph does not allow for updates to chronologically older releases even if the minor version is greater, for example, updating from 4.15.24 to 4.16.2.

Additional resources

Understanding update channels and releases

Selecting the target release

Use the Red Hat OpenShift Container Platform Update Graph or the cincinnati-graph-data repository to determine what release to update to.

Determining what z-stream updates are available

Before you can update to a new z-stream release, you need to know what versions are available.

You do not need to change the channel when performing a z-stream update.

Procedure

Determine which z-stream releases are available. Run the following command:

$ oc adm upgrade

Example output

Cluster version is 4.14.34

Upstream is unset, so the cluster will use an appropriate default.
Channel: stable-4.14 (available channels: candidate-4.14, candidate-4.15, eus-4.14, eus-4.16, fast-4.14, fast-4.15, stable-4.14, stable-4.15)

Recommended updates:

  VERSION     IMAGE
  4.14.37     quay.io/openshift-release-dev/ocp-release@sha256:14e6ba3975e6c73b659fa55af25084b20ab38a543772ca70e184b903db73092b
  4.14.36     quay.io/openshift-release-dev/ocp-release@sha256:4bc4925e8028158e3f313aa83e59e181c94d88b4aa82a3b00202d6f354e8dfed
  4.14.35     quay.io/openshift-release-dev/ocp-release@sha256:883088e3e6efa7443b0ac28cd7682c2fdbda889b576edad626769bf956ac0858

Changing the channel for a Control Plane Only update

You must change the channel to the required version for a Control Plane Only update.

You do not need to change the channel when performing a z-stream update.

Procedure

Determine the currently configured update channel:

$ oc get clusterversion -o=jsonpath='{.items[*].spec}' | jq

Example output

{
  "channel": "stable-4.14",
  "clusterID": "01eb9a57-2bfb-4f50-9d37-dc04bd5bac75"
}

Change the channel to point to the new channel you want to update to:
```
$ oc adm upgrade channel eus-4.16
```

Confirm the updated channel:

$ oc get clusterversion -o=jsonpath='{.items[*].spec}' | jq

Example output

{
  "channel": "eus-4.16",
  "clusterID": "01eb9a57-2bfb-4f50-9d37-dc04bd5bac75"
}

Changing the channel for an early EUS to EUS update

The update path to a brand new release of OpenShift Container Platform is not available in either the EUS channel or the stable channel until 45 to 90 days after the initial GA of a minor release.

To begin testing an update to a new release, you can use the fast channel.

Procedure

Change the channel to fast-<y+1>. For example, run the following command:
```
$ oc adm upgrade channel fast-4.16
```

Check the update path from the new channel. Run the following command:

$ oc adm upgrade

Cluster version is 4.15.33

upgradeable=False

  Reason: AdminAckRequired
  Message: Kubernetes 1.28 and therefore OpenShift 4.16 remove several APIs which require admin consideration. Please see the knowledge article https://access.redhat.com/articles/6958394 for details and instructions.

Upstream is unset, so the cluster will use an appropriate default.
Channel: fast-4.16 (available channels: candidate-4.15, candidate-4.16, eus-4.15, eus-4.16, fast-4.15, fast-4.16, stable-4.15, stable-4.16)

Recommended updates:

  VERSION     IMAGE
  4.16.14     quay.io/openshift-release-dev/ocp-release@sha256:6618dd3c0f5
  4.16.13     quay.io/openshift-release-dev/ocp-release@sha256:7a72abc3
  4.16.12     quay.io/openshift-release-dev/ocp-release@sha256:1c8359fc2
  4.16.11     quay.io/openshift-release-dev/ocp-release@sha256:bc9006febfe
  4.16.10     quay.io/openshift-release-dev/ocp-release@sha256:dece7b61b1
  4.15.36     quay.io/openshift-release-dev/ocp-release@sha256:c31a56d19
  4.15.35     quay.io/openshift-release-dev/ocp-release@sha256:f21253
  4.15.34     quay.io/openshift-release-dev/ocp-release@sha256:2dd69c5

Follow the update procedure to get to version 4.16 (<y+1> from version 4.15)

You can keep your worker nodes paused between EUS releases even if you are using the fast channel.
When you get to the required <y+1> release, change the channel again, this time to fast-<y+2>.
Follow the EUS update procedure to get to the required <y+2> release.

Changing the channel for a y-stream update

In a y-stream update you change the channel to the next release channel.

Use the stable or EUS release channels for production clusters.

Procedure

Change the update channel:
```
$ oc adm upgrade channel stable-4.15
```

Check the update path from the new channel. Run the following command:

$ oc adm upgrade

Example output

Cluster version is 4.14.34

upgradeable=False

  Reason: AdminAckRequired
  Message: Kubernetes 1.27 and therefore OpenShift 4.15 remove several APIs which require admin consideration. Please see the knowledge article https://access.redhat.com/articles/6958394 for details and instructions.

Upstream is unset, so the cluster will use an appropriate default.
Channel: stable-4.15 (available channels: candidate-4.14, candidate-4.15, eus-4.14, eus-4.15, fast-4.14, fast-4.15, stable-4.14, stable-4.15)

Recommended updates:

  VERSION     IMAGE
  4.15.33     quay.io/openshift-release-dev/ocp-release@sha256:7142dd4b560
  4.15.32     quay.io/openshift-release-dev/ocp-release@sha256:cda8ea5b13dc9
  4.15.31     quay.io/openshift-release-dev/ocp-release@sha256:07cf61e67d3eeee
  4.15.30     quay.io/openshift-release-dev/ocp-release@sha256:6618dd3c0f5
  4.15.29     quay.io/openshift-release-dev/ocp-release@sha256:7a72abc3
  4.15.28     quay.io/openshift-release-dev/ocp-release@sha256:1c8359fc2
  4.15.27     quay.io/openshift-release-dev/ocp-release@sha256:bc9006febfe
  4.15.26     quay.io/openshift-release-dev/ocp-release@sha256:dece7b61b1
  4.14.38     quay.io/openshift-release-dev/ocp-release@sha256:c93914c62d7
  4.14.37     quay.io/openshift-release-dev/ocp-release@sha256:c31a56d19
  4.14.36     quay.io/openshift-release-dev/ocp-release@sha256:f21253
  4.14.35     quay.io/openshift-release-dev/ocp-release@sha256:2dd69c5

Verifying cluster API versions between update versions