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 or rapid channels.
• If you're interested in getting the latest patches as soon as possible, use the patch channel. The node-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.