This article explains how to upgrade an Azure Kubernetes Service (AKS) cluster. Upgrading your cluster ensures you have access to the latest features, security patches, and bug fixes from Kubernetes and AKS.
Overview of AKS Cluster Upgrades
AKS supports in-place upgrades of the control plane and node pools. You can choose to upgrade the Kubernetes minor version, patch version, or both. The upgrade process involves upgrading the AKS control plane and then upgrading the node pools to match the new control plane version.
Prerequisites
- An existing Azure Kubernetes Service (AKS) cluster.
- Azure CLI installed and configured, or Azure Cloud Shell.
- Permissions to manage the AKS cluster.
Before You Begin
It's recommended to review the AKS release notes and Kubernetes release notes for any breaking changes or important information related to the version you are upgrading to.
Consider performing a test upgrade on a non-production cluster first.
Steps to Upgrade an AKS Cluster
1. Check Available Versions
Before upgrading, you can check the available Kubernetes versions for your cluster region:
az aks get-versions --location <your-cluster-region> --output tableYou can also list available upgrade versions for your specific cluster:
az aks get-upgrades --resource-group <your-resource-group> --name <your-aks-cluster-name> --output table2. Upgrade the Control Plane
To upgrade the cluster's control plane to a new Kubernetes version, use the following command:
az aks upgrade --resource-group <your-resource-group> --name <your-aks-cluster-name> --kubernetes-version <target-kubernetes-version>Replace <target-kubernetes-version> with the desired version (e.g., 1.27.7).
Note: The control plane upgrade typically takes several minutes. During this time, the API server will be unavailable, but existing workloads will continue to run.
3. Upgrade Node Pools
After the control plane has been upgraded, you need to upgrade your node pools to match the new control plane version. You can upgrade a specific node pool:
az aks nodepool upgrade --resource-group <your-resource-group> --cluster-name <your-aks-cluster-name> --name <your-nodepool-name> --kubernetes-version <target-kubernetes-version>If you have multiple node pools, you will need to upgrade each one individually.
Warning: Upgrading a node pool will drain existing nodes, replace them with new nodes running the target Kubernetes version, and then uncordon them. Ensure your applications are configured for graceful shutdown.
4. Verify the Upgrade
After the node pool upgrade is complete, verify the cluster version:
az aks show --resource-group <your-resource-group> --name <your-aks-cluster-name> --query "kubernetesVersion"You can also check the status of your node pools:
az aks nodepool list --resource-group <your-resource-group> --cluster-name <your-aks-cluster-name> --output tableAutomated Upgrades
AKS also supports automated upgrades for both the control plane and node pools. This can help ensure your cluster stays up-to-date with the latest stable versions.
Refer to the AKS documentation on automated upgrades for more details.
Common Issues and Troubleshooting
- Upgrade Stuck: Check AKS diagnostics and cluster events for errors.
- Application Failures: Review application logs and Kubernetes events for compatibility issues with the new version.
- Node Pool Not Upgrading: Ensure there are no pending operations on the node pool and that the cluster has sufficient quota.
Tip: Regularly monitor your cluster's health and version status using the Azure portal or Azure CLI.
Next Steps
Once your cluster is upgraded, you can explore new Kubernetes features or update your deployed applications to take advantage of them.