Upgrade Readiness Check

What the Readiness Check Validates
A series of critical checks are performed as part of the validation process. These include:

Input Parameter Validation
Ensures that all input parameters are valid. For example, specifying an invalid Kubernetes version will result in a validation failure.

Pod Disruption Budget (PDB) Configuration
Verifies that your pods are not protected by overly strict disruption rules. Incorrect PDB configurations can prevent nodes from draining properly, blocking the upgrade. This check confirms whether your PDB settings allow the upgrade to proceed.

Example Error:

Code: UnsatisfiablePDB
Message: Upgrade is blocked due to invalid Pod Disruption Budgets (PDBs). Please review the PDB spec to allow disruptions during upgrades. To bypass this error, set forceUpgrade in upgradeSettings.overrideSettings. Bypassing this error without updating the PDB may result in drain failures during upgrade process. Invalid PDBs details: 1 error occurred:\n\t* PDB ingress-nginx/ingress-nginx-pdb has maxunavailable == 0 can't proceed with put operation\n\n. Please see https://learn.microsoft.com/en-us/troubleshoot/azure/azure-kubernetes/create-upgrade-delete/error-code-unsatisfiablepdb
Quota Validation
During an upgrade, additional surge nodes may be required. If your subscription or resource group lacks sufficient quotas (e.g., CPU, memory, or VM limits), surge node creation may fail, blocking the upgrade.

Example Error:

Code: ErrCode_InsufficientVCPUQuota
Message: Insufficient regional vcpu quota left for location x. left regional vcpu quota x, requested quota x. If you want to
increase the quota, please follow this instruction: https://learn.microsoft.com/en-us/azure/quotas/view-quotas. Surge nodes
would also consume vcpu quota, please consider use smaller maxSurge or use maxUnavailable to proceed upgrade without surge
nodes, details: aka.ms/aks/maxUnavailable."
API Deprecation and Breaking Changes
When upgrading Kubernetes versions, some APIs may be deprecated or removed. This check identifies in-use deprecated APIs, helping you migrate to supported versions and test workloads prior to upgrading in production environments.

Example Error:

Code: ValidationError
SubCode: UpgradeBlockedOnDeprecatedAPIUsage
Message: Control Plane upgrade is blocked due to recent usage of a Kubernetes API deprecated in the specified version. Please refer to https://kubernetes.io/docs/reference/using-api/deprecation-guide to migrate the usage. AKS records the usage over the last 12 hours, so you may need to wait that long after migrating before this error stops. To bypass this error, set forceUpgrade in upgradeSettings.overrideSettings. Bypassing this error without migrating usage will result in the deprecated Kubernetes API calls failing. See details in https://aka.ms/aks/UpgradeAndDeprecatedAPIs. Usage details: 2 errors occurred: usage has been detected on API X, and was recently seen at: X, which will be removed in X
Subnet Capacity
Surge nodes need available IP addresses within the assigned subnet. The check evaluates whether your subnet has enough allocatable IP addresses and recommends resizing the subnet if necessary.

Example Error:

Code: InsufficientSubnetSize
Message: Pre-allocated IPs 103424 exceeds IPs available 65536 in Subnet Cidr 10.244.0.0/16, Subnet Name networkProfile.podCIDR. If Autoscaler is enabled, the max-count from each nodepool is counted towards this total (which means that pre-allocated IPs count represents a theoretical max value, not the actual number of IPs requested). http://aka.ms/aks/insufficientsubnetsize. Surge nodes would also consume the subnet IP space, please consider use smaller maxSurge or use maxUnavailable, details: aka.ms/aks/maxUnavailable.)
After Running the Check
Once initiated, the readiness check typically returns results quickly. Any identified issues will be surfaced in the output.

We strongly recommend addressing these issues and re-running the check to confirm that your cluster is in an upgrade-ready state before proceeding with your scheduled upgrade activities.