Upgrading OpenShift 4 cluster.md

Upgrading OpenShift 4 cluster

Related OpenShift documentation is Updating a cluster within a minor version by using the CLI.

Available upgrades are managed by https://github.com/openshift/cincinnati-graph-data/tree/master/channels.

Individual graph edges can be blocked by https://github.com/openshift/cincinnati-graph-data/tree/master/blocked-edges.

KCS that is dynamically built and communicates why edges are blocked: https://access.redhat.com/node/6103381

Available upgrades in a graphical form: https://graph.openshift.tips/

Let's assume an OCP 4.5.4 cluster. Showing just important parts of the output:

$ oc get clusterversion version --output yaml
apiVersion: config.openshift.io/v1                                                                                                                    [5/45474]
kind: ClusterVersion
metadata:
  name: version
spec:
  channel: stable-4.5
  clusterID: d5434d70-2887-4685-ac23-c350b70ff48c
  upstream: https://api.openshift.com/api/upgrades_info/v1/graph
status:
  availableUpdates:
    - force: false
      image: quay.io/openshift-release-dev/ocp-release@sha256:ea89ed06f4a5c38dde36f053b250df4bab184729c1adf60afa43d0de8b1930f3
      version: 4.5.35
    - force: false
      image: quay.io/openshift-release-dev/ocp-release@sha256:8d104847fc2371a983f7cb01c7c0a3ab35b7381d6bf7ce355d9b32a08c0031f0
      version: 4.5.13
    - force: false
      image: quay.io/openshift-release-dev/ocp-release@sha256:6dde1b3ad6bec35364b2b89172cfea0459df75c99a4031f6f7b2a94eb9b166cf
      version: 4.5.17
    - force: false
      image: quay.io/openshift-release-dev/ocp-release@sha256:7ad540594e2a667300dd2584fe2ede2c1a0b814ee6a62f60809d87ab564f4425
      version: 4.5.9
    - force: false
      image: quay.io/openshift-release-dev/ocp-release@sha256:a58573e1c92f5258219022ec104ec254ded0a70370ee8ed2aceea52525639bd4
      version: 4.5.5
      
...

  conditions:
    - lastTransitionTime: "2021-04-09T00:59:46Z"
      message: Done applying 4.5.4
      status: "True"
      type: Available
    - lastTransitionTime: "2021-04-10T13:47:40Z"
      status: "False"
      type: Failing
    - lastTransitionTime: "2021-04-09T00:59:46Z"
      message: Cluster version is 4.5.4
      status: "False"
      type: Progressing
    - lastTransitionTime: "2021-04-09T00:38:52Z"
      status: "True"
      type: RetrievedUpdates
  desired:
    force: false
    image: quay.io/openshift-release-dev/ocp-release@sha256:02dfcae8f6a67e715380542654c952c981c59604b1ba7f569b13b9e5d0fbbed3
    version: 4.5.4
  history:
    - completionTime: "2021-04-09T00:59:46Z"
      image: quay.io/openshift-release-dev/ocp-release@sha256:02dfcae8f6a67e715380542654c952c981c59604b1ba7f569b13b9e5d0fbbed3
      startedTime: "2021-04-09T00:38:52Z"
      state: Completed
      verified: false
      version: 4.5.4
  observedGeneration: 1
  versionHash: qSkCqxZtYDI=

Upgrading patch version

Create a version-clusterversion.yaml file with the following content:

apiVersion: config.openshift.io/v1
kind: ClusterVersion
metadata:
  name: version
spec:
  channel: stable-4.5
  desiredUpdate:
    version: 4.5.35

Note that the above file will upgrade the cluster from current version to version 4.5.35. For patch upgrade, the spec.channel field remains unchanged (stable-4.5 in our case).

Trigger the cluster upgrade:

$ oc apply --filename version-clusterversion.yaml

Upgrading minor version

Create a version-clusterversion.yaml file with the following content:

apiVersion: config.openshift.io/v1
kind: ClusterVersion
metadata:
  name: version
spec:
  channel: stable-4.6
  desiredUpdate:
    version: 4.5.35

Apply the above file to the cluster:

$ oc apply --filename version-clusterversion.yaml

Note that the above file changes the channel to stable-4.6. The desired cluster version remains the same 4.5.35. Cluster version operator will fetch updates available on the stable-4.6 channel. Wait for the spec.availableUpdates list to be updated with the versions from the stable-4.6 channel.

Create a version-clusterversion.yaml file for upgrading to version 4.6.21:

apiVersion: config.openshift.io/v1
kind: ClusterVersion
metadata:
  name: version
spec:
  channel: stable-4.6
  desiredUpdate:
    version: 4.6.21

After the desired target version shows up in the status.availableUpdates list, trigger the cluster upgrade:

$ oc apply --filename version-clusterversion.yaml

Forcing upgrade

You can upgrade to any OpenShift release you want, including releases which were blocked for automated upgrades. You can also downgrade your cluster. Note that cluster downgrades are not supported by Red Hat. List of available OCP release images that you can choose for upgrading your cluster can be found at https://quay.io/repository/openshift-release-dev/ocp-release?tab=tags

In this example we are going to forcefully upgrade to version 4.7.4. This upgrade path was blocked at the time of this writing due to known issues. As these issues didn't affect our cluster, we decided to upgrade.

Create a version-clusterversion.yaml file for upgrading to version 4.7.4:

apiVersion: config.openshift.io/v1
kind: ClusterVersion
metadata:
  name: version
spec:
  channel: stable-4.7
  desiredUpdate:
    force: true
    version: 4.7.4
    image: quay.io/openshift-release-dev/ocp-release:4.7.4-x86_64

$ oc apply --filename version-clusterversion.yaml