1# Upgrade Operations
2 
3Use this guide when node image rotation, Kubernetes version changes, or node-pool upgrade settings appear to be the failure domain.
4 
5## Node Image / OS Upgrade Issues
6 
7> ⚠️ **Warning:** `az aks nodepool upgrade` and `az aks nodepool update --max-surge ...` change cluster state. During diagnostics, do not recommend or run upgrade actions by default. Only surface these commands after the user explicitly approves remediation or confirms the change window / change-control context.
8 
9```bash
10# Check current node image versions
11az aks nodepool show -g <rg> --cluster-name <cluster> -n <nodepool> \
12  --query "{nodeImageVersion:nodeImageVersion, osType:osType}"
13 
14# Check available upgrades
15az aks nodepool get-upgrades -g <rg> --cluster-name <cluster> --nodepool-name <nodepool>
16 
17# Upgrade node image (non-disruptive with surge)
18az aks nodepool upgrade -g <rg> --cluster-name <cluster> -n <nodepool> --node-image-only
19```
20 
21---
22 
23## Kubernetes Version Upgrade Failures
24 
25**Pre-upgrade check:**
26 
27```bash
28# Check for deprecated API usage before upgrading
29kubectl get --raw /metrics | grep apiserver_requested_deprecated_apis
30 
31# Verify available upgrade paths (can only skip one minor version)
32az aks get-upgrades -g <rg> -n <cluster> -o table
33```
34 
35**Upgrade stuck or failed:**
36 
37```bash
38# Check control plane provisioning state
39az aks show -g <rg> -n <cluster> --query "provisioningState"
40 
41# If stuck: check AKS diagnostics blade in portal
42# Azure Portal -> AKS cluster -> Diagnose and solve problems -> Upgrade
43```
44 
45Common causes: PDB blocking drain (`kubectl get pdb -A`), deprecated APIs in use, custom admission webhooks failing (`kubectl get validatingwebhookconfiguration`).
46 
47---
48 
49## Zero-Downtime Node Pool Upgrades
50 
51`maxSurge` controls how many extra nodes are provisioned during upgrade.
52 
53```bash
54# Check current maxSurge
55az aks nodepool show -g <rg> --cluster-name <cluster> -n <nodepool> \
56  --query "upgradeSettings.maxSurge"
57 
58az aks nodepool update -g <rg> --cluster-name <cluster> -n <nodepool> \
59  --max-surge 33%
60```
61 
62**Upgrade stuck / nodes not draining:**
63 
64```bash
65kubectl get pdb -A
66kubectl describe pdb <pdb-name> -n <ns>
67```
68 
69If `DisruptionsAllowed: 0`, scale up the workload or temporarily relax `minAvailable`.
70