--- name: openshift-update-master title: Updating the cluster master description: Update the Kubernetes API server and associated master components to a new major, minor, or patch version. Update the master before you update your worker nodes. last-updated: 2026-11-06 --- > ## Documentation Index > The table of contents for this documentation set is at https://cloud.ibm.com/docs/openshift?format=markdown > The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt > Use these files to discover more information as needed. # Updating the cluster master {: #update-master} Update the Kubernetes API server and associated master components to a new major, minor, or patch version. Update the master before you update your worker nodes. {: shortdesc} ## How master updates work {: #master-update-faq} How do I know when to update the master? : You are notified in the console, announcements, and the CLI when updates are available. You can also periodically check the [supported versions page](https://cloud.ibm.com/docs/openshift?topic=openshift-openshift_versions&format=markdown). How many versions behind the latest can the master be? : You can update the API server only to the next version ahead of its current version (`n+1`). Can my worker nodes run a later version than the master? : Your worker nodes can't run a later `major.minor` Kubernetes version than the master. Additionally, your worker nodes can only be one minor version behind the master version (`n-1`). First, [update your master](#master-steps) to the latest Kubernetes version. Then, update the worker nodes in your cluster by following the steps for [VPC](https://cloud.ibm.com/docs/openshift?topic=openshift-update-workers-vpc&format=markdown) or [classic](https://cloud.ibm.com/docs/openshift?topic=openshift-update-workers-classic&format=markdown) worker nodes. Worker nodes can run later patch versions than the master, such as patch versions that are specific to worker nodes for security updates. How are patch updates applied? : By default, patch updates for the master are applied automatically over the course of several days, so a master patch version might show up as available before it is applied to your master. The update automation also skips clusters that are in an unhealthy state or have operations currently in progress. Occasionally, IBM might disable automatic updates for a specific master fix pack, such as a patch that is only needed if a master is updated from one minor version to another. In any of these cases, you can check the [Red Hat OpenShift on IBM Cloud version information](https://cloud.ibm.com/docs/openshift?topic=openshift-openshift_versions&format=markdown) for any potential impact and choose to safely use the `ibmcloud oc cluster master update` [command](https://cloud.ibm.com/docs/openshift?topic=openshift-kubernetes-service-cli&format=markdown#cluster-master-update-cli) yourself without waiting for the update automation to apply. Unlike the master, you must update your workers for each patch version. What happens during the master update? : Your master is highly available with three replica master pods. The master pods have a rolling update, during which only one pod is unavailable at a time. Two instances are up and running so that you can access and change the cluster during the update. Your worker nodes, apps, and resources continue to run. Can I roll back the update? : No, you can't roll back a cluster to a previous version after the update process takes place. Be sure to use a test cluster and follow the instructions to address potential issues before you update your production master. What process can I follow to update the master? : The following diagram shows the process that you can take to update your master. ![Master update process diagram](/images/updating-master2.svg "Flow diagram of the process to update the cluster master"){: caption="Updating Kubernetes master process diagram" caption-side="bottom"} ## Steps to update the cluster master {: #master-steps} Before you update the master, complete the checks in [Preparing to update your cluster](https://cloud.ibm.com/docs/openshift?topic=openshift-update-prepare&format=markdown). To update the Red Hat OpenShift master _major_ or _minor_ version: 1. Update your API server and associated master components by using the [IBM Cloud console](https://cloud.ibm.com/login){: external} or running the CLI `ibmcloud oc cluster master update` [command](https://cloud.ibm.com/docs/openshift?topic=openshift-kubernetes-service-cli&format=markdown#cluster-master-update-cli). 2. Wait for the update to complete, which typically takes 30 - 60 minutes, then confirm that it is complete. Review the API server version on the IBM Cloud clusters dashboard or run `ibmcloud oc cluster ls`. While the update runs, the cluster shows the [**Updating**](https://cloud.ibm.com/docs/openshift?topic=openshift-cluster-states-reference&format=markdown#cluster-state-updating) state. If the update fails, the cluster shows the [**Update failed**](https://cloud.ibm.com/docs/openshift?topic=openshift-cluster-states-reference&format=markdown#cluster-state-failed) state. During the update, you can still access and change the cluster, but you can't start concurrent master operations, such as enabling API server auditing. If the cluster stays in the **Update failed** state for more than 1 day, [open a support case](https://cloud.ibm.com/docs/openshift?topic=openshift-get-help&format=markdown). 3. Install the version of the [`oc cli`](https://cloud.ibm.com/docs/openshift?topic=openshift-cli-install&format=markdown) that matches the API server version that runs in the master. Kubernetes does not support `oc` client versions that are two or more versions apart from the server version (n +/- 2). To refresh your local configuration, run `ibmcloud oc cluster config -c CLUSTER_NAME_OR_ID`, then verify with `oc version --client`. ## Next steps {: #update-master-next} When the master update is complete, update your worker nodes. The method depends on your infrastructure type: * [Updating VPC worker nodes](https://cloud.ibm.com/docs/openshift?topic=openshift-update-workers-vpc&format=markdown) uses `worker reload` for VPC bare metal workers, and `worker replace --update` for VPC VSI workers. The ConfigMap rolling update procedure is not yet supported for VPC worker nodes. * [Updating classic worker nodes](https://cloud.ibm.com/docs/openshift?topic=openshift-update-workers-classic&format=markdown) uses a rolling update that is controlled by a ConfigMap and the `worker update` command. ## Related links {: #update-master-related} * [Updating clusters, worker nodes, and cluster components](https://cloud.ibm.com/docs/openshift?topic=openshift-update&format=markdown) * [Cluster states and statuses](https://cloud.ibm.com/docs/openshift?topic=openshift-cluster-states-reference&format=markdown) * [Reviewing master health](https://cloud.ibm.com/docs/openshift?topic=openshift-debug_master&format=markdown)