Skip to content

Upgrades

Draft: not yet run against a live cluster. Treat output as representative and check it on yours.

Kubernetes releases a new minor version roughly three times a year and supports each one for about a year. If you don’t plan upgrades, you’ll be forced into them, usually several minor versions at once and under pressure. This chapter is the plan.

  1. Version skew policy. The API server must be the newest component. Kubelets may be older than the API server by a limited number of minor versions (three in current releases; it was two before 1.28), but never newer. kubectl is supported within one minor version of the API server. Check the policy for your target version on kubernetes.io.

  2. Control plane first. With kubeadm: kubeadm upgrade plan, then kubeadm upgrade apply v1.N+1.x on the first control plane node, kubeadm upgrade node on the others. Managed platforms do this step for you when you trigger it.

  3. Then nodes, one at a time (or one batch at a time). Cordon and drain the node, upgrade kubelet and the runtime (or replace the node with a new one built on the new version), then uncordon.

  4. Draining respects PodDisruptionBudgets. kubectl drain uses the Eviction API, which refuses to evict a pod if that would violate its PDB. That’s what keeps services up during node upgrades, and also what blocks drains when PDBs are too strict.

Before any upgrade, find manifests that use APIs the next version removes:

Terminal window
# Which deprecated APIs are clients actually calling? (requires metrics access)
kubectl get --raw /metrics | grep apiserver_requested_deprecated_apis
# Drain a node the way an upgrade does
kubectl cordon <node>
kubectl drain <node> --ignore-daemonsets --delete-emptydir-data --timeout=10m
kubectl uncordon <node>

Static scanners for your repository (such as pluto or kubent) catch deprecated APIs in manifests and Helm charts that aren’t deployed yet. The metric above only shows what has been called since the API server started.

Can you upgrade a cluster from 1.N directly to 1.N+2?

No. Upgrade the control plane one minor version at a time. (OpenShift EUS-to-EUS paths still step through the intermediate version on the control plane.)

May a kubelet be newer than the API server?

No. The API server must be at least as new as every kubelet.

After an upgrade, existing Ingress objects work, but applying your old manifest fails. Why?

Stored objects were converted to a served API version. Your manifest still asks for a version the API server no longer serves.

Maps to: CKA: Cluster Architecture, Installation and Configuration. Check the current exam curriculum, since domain names change between revisions.