Automatically upgrade an Azure Kubernetes Service (AKS) cluster
Part of the AKS cluster lifecycle involves performing periodic upgrades to the latest Kubernetes version. It’s important you apply the latest security releases, or upgrade to get the latest features. Before learning about auto-upgrade, make sure you understand upgrade fundamentals by reading Upgrade an AKS cluster.
Note
Any upgrade operation, whether performed manually or automatically, will upgrade the node image version if not already on the latest. The latest version is contingent on a full AKS release, and can be determined by visiting the AKS release tracker.
Auto-upgrade will first upgrade the control plane, and then proceed to upgrade agent pools one by one.
Why use auto-upgrade
Auto-upgrade provides a set once and forget mechanism that yields tangible time and operational cost benefits. By enabling auto-upgrade, you can ensure your clusters are up to date and don't miss the latest AKS features or patches from AKS and upstream Kubernetes.
AKS follows a strict versioning window with regard to supportability. With properly selected auto-upgrade channels, you can avoid clusters falling into an unsupported version. For more on the AKS support window, see Supported Kubernetes versions.
Even if using node image auto upgrade (which won't change the Kubernetes version), it still requires MC to be in a supported version
Using auto-upgrade
Automatically completed upgrades are functionally the same as manual upgrades. The timing of upgrades is determined by the selected channel. When making changes to auto-upgrade, allow 24 hours for the changes to take effect.
The following upgrade channels are available:
Channel | Action | Example |
---|---|---|
none |
disables auto-upgrades and keeps the cluster at its current version of Kubernetes | Default setting if left unchanged |
patch |
automatically upgrade the cluster to the latest supported patch version when it becomes available while keeping the minor version the same. | For example, if a cluster is running version 1.17.7 and versions 1.17.9, 1.18.4, 1.18.6, and 1.19.1 are available, your cluster is upgraded to 1.17.9 |
stable |
automatically upgrade the cluster to the latest supported patch release on minor version N-1, where N is the latest supported minor version. | For example, if a cluster is running version 1.17.7 and versions 1.17.9, 1.18.4, 1.18.6, and 1.19.1 are available, your cluster is upgraded to 1.18.6. |
rapid |
automatically upgrade the cluster to the latest supported patch release on the latest supported minor version. | In cases where the cluster is at a version of Kubernetes that is at an N-2 minor version where N is the latest supported minor version, the cluster first upgrades to the latest supported patch version on N-1 minor version. For example, if a cluster is running version 1.17.7 and versions 1.17.9, 1.18.4, 1.18.6, and 1.19.1 are available, your cluster first is upgraded to 1.18.6, then is upgraded to 1.19.1. |
node-image |
automatically upgrade the node image to the latest version available. | Microsoft provides patches and new images for image nodes frequently (usually weekly), but your running nodes won't get the new images unless you do a node image upgrade. Turning on the node-image channel will automatically update your node images whenever a new version is available. |
Note
Cluster auto-upgrade only updates to GA versions of Kubernetes and will not update to preview versions.
Note
Auto-upgrade requires the cluster's Kubernetes version to be within the AKS support window, even if using the node-image
channel.
Automatically upgrading a cluster follows the same process as manually upgrading a cluster. For more information, see Upgrade an AKS cluster.
To set the auto-upgrade channel when creating a cluster, use the auto-upgrade-channel parameter, similar to the following example.
az aks create --resource-group myResourceGroup --name myAKSCluster --auto-upgrade-channel stable --generate-ssh-keys
To set the auto-upgrade channel on existing cluster, update the auto-upgrade-channel parameter, similar to the following example.
az aks update --resource-group myResourceGroup --name myAKSCluster --auto-upgrade-channel stable
Using auto-upgrade with Planned Maintenance
If you’re using Planned Maintenance and Auto-Upgrade, your upgrade will start during your specified maintenance window.
Note
To ensure proper functionality, use a maintenance window of four hours or more.
For more information on Planned Maintenance, see Use Planned Maintenance to schedule maintenance windows for your Azure Kubernetes Service (AKS) cluster.
Auto upgrade limitations
If you’re using Auto-Upgrade you cannot anymore upgrade the control plane first, and then upgrade the individual node pools. Auto-Upgrade will always upgrade the control plane and the node pools together. In Auto-Upgrade there is no concept of upgrading the control plane only, and trying to run the command az aks upgrade --control-plane-only
will raise the error: NotAllAgentPoolOrchestratorVersionSpecifiedAndUnchanged: Using managed cluster api, all Agent pools' OrchestratorVersion must be all specified or all unspecified. If all specified, they must be stay unchanged or the same with control plane.
Best practices for auto-upgrade
The following best practices will help maximize your success when using auto-upgrade:
- In order to keep your cluster always in a supported version (i.e within the N-2 rule), choose either
stable
orrapid
channels. - If you're interested in getting the latest patches as soon as possible, use the
patch
channel. Thenode-image
channel is a good fit if you want your agent pools to always be running the most recent node images. - Follow Operator best practices.
- Follow PDB best practices.
Feedback
Submit and view feedback for