OpenShift Cluster Upgrade Guide

By Avadhoot Patil | DevOps with Patil

Updating an OpenShift cluster is more than selecting a new version. The platform, its operators, nodes, and applications must all remain healthy as the update progresses.

This guide uses a cluster on OpenShift Container Platform 4.14.35 with a proposed target of 4.16.28 as an example. It is a planning and validation guide, not a claim that every cluster can move directly between those exact releases. The supported path must be checked against the update recommendations for the actual cluster.

Scope: These examples concern administrator-managed OpenShift Container Platform clusters. For a managed service such as Azure Red Hat OpenShift (ARO), follow that service’s supported upgrade process and division of responsibilities.

What to check before choosing a target version

Start with the current cluster state:

oc get clusterversion
oc adm upgrade
oc get clusteroperators
oc get machineconfigpools
oc get nodes

Review more than the version number:

• Are Cluster Operators Available and free of unexplained Degraded conditions?
• Are MachineConfigPools updated and not unexpectedly paused or degraded?
• Are control plane and worker nodes healthy?
• Does oc adm upgrade offer a recommended update toward the intended version?
• Do any conditional updates show risks that apply to this cluster?

Do not copy a version number from another environment and assume it is a valid target for yours. Update recommendations can differ based on the cluster and can change over time.

Understand the update path

A 4.14-to-4.16 plan may require steps through 4.15 and additional patch releases. Red Hat also documents an Extended Update Support (EUS) procedure for eligible clusters, with specific channel and machine-config-pool handling. That procedure must be followed in full if it applies; it is not a reason to run a direct, unverified command.

A planning sequence looks like this:

1. Check recommended updates from the current 4.14 release.
2. Select an update supported for this cluster.
3. Complete it and validate cluster and application health.
4. Repeat until the cluster is eligible for the next minor version.
5. Check the 4.15-to-4.16 requirements and recommendations.
6. Continue only when the intended 4.16 target is offered and approved for the cluster.

The exact intermediate versions are determined by the cluster’s update recommendations—not by the simplified version diagram in a blog post.

Pre-update checklist

Before the approved maintenance window, record the baseline:

oc get clusterversion
oc get clusteroperators
oc get machineconfigpools
oc get nodes -o wide
oc get csr
oc get pdb -A
oc get pods -A

Investigate unexpected degraded operators, unhealthy nodes, pending CSRs, and application failures before starting. A cluster update is a poor time to discover that an existing incident was never resolved.

Also review:

• The release notes and known issues for each planned update.
• Installed Operators and their compatibility with the target version.
• Deprecated or removed APIs used by workloads and external tools.
• Available capacity while nodes are drained and updated.
• PodDisruptionBudgets, replica counts, storage, and application availability during disruption.
• Registry and network access needed for update images.
• Monitoring, alerting, business checks, and communication plans.
• A tested recovery procedure appropriate to the platform.

Record the baseline health of critical applications: login, APIs, routes, database connections, and key transactions. You will compare these results after each update step.

Back up etcd and application data

For a self-managed OpenShift Container Platform cluster, follow the Red Hat backup instructions for the current release and take an etcd backup before updating. Verify where the backup is stored and how it would be used.

An etcd backup protects cluster state; it is not a substitute for application and persistent-data backups. Back up those workloads through the appropriate database, storage, or application procedure as well.

Do not describe etcd restore as a simple “undo” button for an upgrade. Restoring a cluster is a recovery operation with version-specific requirements and should follow the documented procedure.

Check the 4.16 administrator acknowledgement

Before the 4.15-to-4.16 update, Red Hat requires an administrator acknowledgement related to Kubernetes API removals.

First, assess whether workloads, installed components, idle manifests, or external tools use removed APIs. Migrate affected clients and resources. Only after that assessment is complete, an authorized cluster administrator can apply the documented acknowledgement:

oc -n openshift-config patch cm admin-acks \
  --patch '{"data":{"ack-4.15-kube-1.29-api-removals-in-4.16":"true"}}' \
  --type=merge

This command is specific to that transition. Do not apply an acknowledgement simply to make an Upgradeable=False condition disappear; read the condition and complete the required assessment first.

Apply one recommended update at a time

After approvals, backups, and prechecks, review the offered updates again:

oc adm upgrade

If the approved version appears as a recommended update for this cluster, the CLI syntax to select that specific offered version is:

oc adm upgrade --to=<recommended-version>

Replace the placeholder only with the approved version from the cluster’s recommendations. Do not use --force to bypass update guards as a routine procedure.

The OpenShift web console can also be used to select an available update. Follow the documented process for the cluster’s current version and update channel.

Monitor the update

Check the overall update and the components it affects:

oc adm upgrade
oc get clusterversion
oc get clusteroperators
oc get machineconfigpools
oc get nodes

For a closer look at a problem operator or pool:

oc describe clusteroperator <operator-name>
oc describe machineconfigpool <pool-name>

An operator may temporarily report progressing or unavailable while its components update. Investigate conditions that remain unhealthy, unexpected degradation, or a stalled pool rather than assuming every intermediate status is a failure.

Monitor application dashboards and alerts throughout the update. If a critical check fails, follow the change plan’s pause and escalation process before starting another update step.

Validate after each version step

Do not immediately start the next update when the version number changes. Confirm that the cluster and applications have settled.

Check:

oc get clusterversion
oc get clusteroperators
oc get machineconfigpools
oc get nodes -o wide
oc get pods -A
oc get csr

Compare these results with your pre-update baseline. Then verify the important user journeys:

• Application login and authentication
• Critical APIs and transactions
• Routes and ingress traffic
• Database and cache connectivity
• Persistent volumes and storage access
• Monitoring and logging
• CI/CD and GitOps reconciliation
• Alerts and operational dashboards

Record the result and obtain the required go-ahead before moving to the next recommended update.

Handle PodDisruptionBudgets carefully

PodDisruptionBudgets can affect node drains during an update. Review them together with replica counts and application availability:

oc get pdb -A
oc describe pdb <pdb-name> -n <namespace>

Do not run a command that changes every PDB in a production namespace. If a specific PDB blocks progress, identify the owning workload and understand why it has no allowed disruptions. Agree on a targeted change with the application owner, record the original settings, and restore the approved configuration afterward.

What if the update stalls?

Start with evidence rather than repeating the upgrade command:

1. Check oc adm upgrade and the clusterversion conditions.
2. Identify degraded or unavailable Cluster Operators.
3. Inspect MachineConfigPools and affected nodes.
4. Check events and logs for the component reporting the problem.
5. Compare application health with the pre-update baseline.
6. Follow the documented recovery path or engage Red Hat support when needed.

Avoid changing unrelated operators, nodes, or PDBs merely to clear a status message.

Interview questions

Can I upgrade directly from OpenShift 4.14 to 4.16?
Do not assume so. Check the recommended update path for the actual cluster. An eligible EUS update has its own documented procedure.

Why check Cluster Operators before updating?
They manage core cluster components. An existing degraded condition can make it harder to distinguish an old problem from an update problem.

Why take an etcd backup?
It preserves cluster state for a documented recovery scenario. Application data needs its own backup plan.

What does the administrator acknowledgement mean?
The administrator confirms that removed API usage has been assessed and affected components have been migrated. It is not merely a switch to bypass an upgrade block.

What do you validate after an update?
Cluster version, operators, pools, nodes, workloads, storage, monitoring, and critical application transactions—not just the version string.

Conclusion

A successful OpenShift update follows a supported path, begins with a healthy baseline, protects cluster and application data, and verifies business workloads after each step. The commands help collect evidence, but the cluster’s recommendations and the official procedure determine which update is safe to perform.

OpenShift Cluster Upgrade Checklist

Your checklist has useful prechecks, but remove steps 6 and the matching post-upgrade PDB patch. They set every PDB in prod to minAvailable: 0, then restore every one to 1 even if its original value was different. That can remove disruption protection and overwrite application-specific settings.

There are three other corrections:

• oc get cluster cluster -o yaml does not establish a “service principal status” check. Remove that item unless you identify the specific cloud credential or operator condition you intend to verify.
• The acknowledgement key shown is wrong. The documented 4.15 → 4.16 key is ack-4.15-kube-1.29-api-removals-in-4.16, and it is applied only after assessing and migrating removed API usage.
• Do not write “next jump is 4.14.35, then 4.16.35” as a universal path. Use the recommended updates for the actual cluster, with intermediate steps where required.

Corrected OpenShift upgrade checklist

Before each update step

# Current version, channel, and recommended updates
oc get clusterversion
oc adm upgrade

# Platform health
oc get co
oc get mcp
oc get nodes
oc get csr

# Workload and disruption baseline
oc get pods -A
oc get pdb -A

Review the output rather than relying on grep filters alone. For example, a pod in Pending during a rollout may be expected, while a pod repeatedly restarting may need investigation even though its status says Running. Record abnormal conditions, restart counts, and critical application health.

Check deprecated API usage using Red Hat’s APIRequestCount procedure for the target release. oc get apirequestcounts is a starting point, but awk '{if(NF==4)...}' depends on column formatting and does not establish that removed APIs are no longer used. Also inspect manifests and external clients that may not have made recent requests.

Take the required etcd backup under the procedure for your current release, and separately confirm application and persistent-data backups. Review installed Operator compatibility, update notes, capacity, and the supported path.

PDB review

oc get pdb -A
oc describe pdb <pdb-name> -n <namespace>

Check ALLOWED DISRUPTIONS, replicas, and the owning workload. If a specific PDB blocks a drain, investigate and agree on a targeted remedy with the application owner. Record its original configuration before any approved change. Do not lower every PDB as a routine upgrade step. PDBs are part of how workloads tolerate node disruption during an update.

Select and perform one supported update

Use oc adm upgrade or the console to choose an update offered for this cluster. After change approval, the CLI form is:

oc adm upgrade --to=<recommended-version>

Complete and validate that step before selecting another version. Do not use the article’s version numbers as commands for another cluster.

For the 4.15 → 4.16 transition only, after completing the removed-API assessment, Red Hat documents:

oc -n openshift-config patch cm admin-acks \
  --patch '{"data":{"ack-4.15-kube-1.29-api-removals-in-4.16":"true"}}' \
  --type=merge

This acknowledgement is not a general precheck or a way to bypass an unexplained upgrade block.

After each update step

oc adm upgrade
oc get clusterversion
oc get co
oc get mcp
oc get nodes
oc get pods -A
oc get csr
oc get pdb -A