Upgrading AKS Clusters Safely

Kubernetes version lifecycle on AKS

AKS supports the three most recent minor versions of Kubernetes. When a new minor version is released, the oldest supported version enters a deprecation window and is removed from support approximately 12 months after its release date. AKS adds a new patch version automatically when one is available, but minor version upgrades are always manual.

Check which versions are currently available in your region:

# List all available Kubernetes versions in your region
az aks get-versions \
  --location eastus \
  --output table

# Check available upgrades for your specific cluster
az aks get-upgrades \
  --resource-group myResourceGroup \
  --name myAKSCluster \
  --output table

The output of az aks get-upgrades shows your current version, available upgrade targets, and whether each target is a patch or minor upgrade. It will not list versions you cannot upgrade to from your current version — skipping minor versions is not offered.

To check the current version of your cluster and node pools:

az aks show \
  --resource-group myResourceGroup \
  --name myAKSCluster \
  --query "{controlPlane:kubernetesVersion, nodePools:agentPoolProfiles[].{name:name, version:orchestratorVersion}}" \
  --output table

The upgrade process: control plane first, then node pools

AKS upgrades happen in two phases. The control plane (API server, scheduler, etcd) is upgraded first. During this phase, the Kubernetes API remains available with at most a brief disruption. Node pools are upgraded second — the control plane must always be at a version equal to or one minor version ahead of the node pools.

# Upgrade both control plane and all node pools in one command
az aks upgrade \
  --resource-group myResourceGroup \
  --name myAKSCluster \
  --kubernetes-version 1.29.5

# Upgrade only the control plane (node pools stay on current version)
az aks upgrade \
  --resource-group myResourceGroup \
  --name myAKSCluster \
  --kubernetes-version 1.29.5 \
  --control-plane-only

# After upgrading the control plane, upgrade a specific node pool
az aks nodepool upgrade \
  --resource-group myResourceGroup \
  --cluster-name myAKSCluster \
  --name nodepool1 \
  --kubernetes-version 1.29.5

Upgrading the control plane separately first is useful if you want to test workload compatibility with the new version before upgrading nodes. A node pool on version N-1 is fully compatible with a control plane on version N.

What happens to nodes during an upgrade

For each node in a node pool, AKS performs four steps in sequence:

1. Provision a new node — a new VM is created at the target Kubernetes version and added to the node pool. This is the surge node.
2. Cordon the old node — the old node is marked as unschedulable. No new pods are placed on it, but existing pods continue running.
3. Drain the old node — Kubernetes evicts all pods from the old node. They are rescheduled onto other available nodes including the new surge node. This is where PodDisruptionBudgets come into play.
4. Delete the old node — once drained, the old VM is removed from the node pool.

This process repeats for each node. With the default surge of 1, only one node is being upgraded at a time. With a higher surge, multiple nodes can be upgraded in parallel.

Set the max surge for a node pool to speed up large upgrades:

# Set max surge to 2 nodes (absolute number)
az aks nodepool update \
  --resource-group myResourceGroup \
  --cluster-name myAKSCluster \
  --name nodepool1 \
  --max-surge 2

# Set max surge to 33% of node pool size
az aks nodepool update \
  --resource-group myResourceGroup \
  --cluster-name myAKSCluster \
  --name nodepool1 \
  --max-surge 33%

The drain step evicts pods by sending them a SIGTERM signal. Applications that handle SIGTERM gracefully — flushing connections, finishing in-flight requests, then exiting — will have zero dropped requests during the drain. Applications that do not handle SIGTERM will be force-killed after the terminationGracePeriodSeconds (default 30 seconds).

Using PodDisruptionBudgets to prevent downtime

A PodDisruptionBudget (PDB) limits how many pods from a Deployment can be simultaneously unavailable during voluntary disruptions — which includes node drains during upgrades. Without a PDB, Kubernetes might evict all replicas of your application simultaneously if they happen to be on the same nodes being drained.

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: api-server-pdb
  namespace: production
spec:
  minAvailable: 2
  selector:
    matchLabels:
      app: api-server

This PDB says: when evicting pods with the label app: api-server, always keep at least 2 pods available. If the Deployment has 3 replicas and the upgrade wants to drain a node that has 2 of those replicas, the drain will pause until those pods are rescheduled elsewhere and become ready before continuing.

Alternatively, specify the maximum number that can be unavailable:

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: api-server-pdb
  namespace: production
spec:
  maxUnavailable: 1
  selector:
    matchLabels:
      app: api-server

Apply the PDB before starting an upgrade:

kubectl apply -f pdb.yaml

# Verify the PDB
kubectl get pdb -n production
kubectl describe pdb api-server-pdb -n production

Testing in staging first

The most effective risk mitigation for upgrades is running a staging cluster that matches production and upgrading it first. A staging upgrade catches API deprecations, admission webhook incompatibilities, and add-on failures before they hit production.

Key things to check after upgrading staging:

• All pods start and pass readiness probes on the new version.
• Add-ons (Container Insights, Key Vault CSI driver, ingress controller) still function.
• Any custom admission webhooks (ValidatingWebhookConfiguration, MutatingWebhookConfiguration) are compatible with the new API version.
• Deprecated API versions in your YAML manifests. For example, certain Ingress and PodSecurityPolicy API versions were removed in Kubernetes 1.25. Run kubectl api-versions to see what is available.

# Check for use of deprecated APIs in your cluster (requires Pluto or kubectl deprecations)
kubectl get ingress --all-namespaces -o yaml | grep "apiVersion"

# Show all API resources available in the new version
kubectl api-resources --api-group=networking.k8s.io

Auto-upgrade channels

AKS supports auto-upgrade channels that automatically upgrade your cluster when new versions are available. These reduce manual work but require confidence that your workloads handle upgrades without intervention.

# Set the auto-upgrade channel
az aks update \
  --resource-group myResourceGroup \
  --name myAKSCluster \
  --auto-upgrade-channel patch

Combine auto-upgrade with planned maintenance windows so upgrades only occur during off-peak hours. Configure maintenance windows in the portal or with az aks maintenanceconfiguration add.