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 the AKS cluster upgrade fundamentals.
Note
Any upgrade operation, whether performed manually or automatically, upgrades the node image version if it's not already on the latest version. The latest version is contingent on a full AKS release and can be determined by visiting the AKS release tracker.
Auto-upgrade first upgrades the control plane, and then upgrades agent pools one by one.
Why use cluster auto-upgrade
Cluster 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 features or patches from AKS and upstream Kubernetes.
AKS follows a strict supportability versioning window. With properly selected auto-upgrade channels, you can avoid clusters falling into an unsupported version. For more on the AKS support window, see Alias minor versions.
Customer versus AKS-initiated auto-upgrades
You can specify cluster auto-upgrade specifics using the following guidance. The upgrades occur based on your specified cadence and are recommended to remain on supported Kubernetes versions.
AKS also initiates auto-upgrades for unsupported clusters. When a cluster in an n-3 version (where n is the latest supported AKS GA minor version) is about to drop to n-4, AKS automatically upgrades the cluster to n-2 to remain in an AKS support policy. Automatically upgrading a platform supported cluster to a supported version is enabled by default. Stopped node pools will be upgraded during an auto-upgrade operation. The upgrade will apply to nodes when the node pool is started. To minimize disruptions, set up maintenance windows.
Cluster auto-upgrade limitations
If you’re using cluster auto-upgrade, you can no longer upgrade the control plane first, and then upgrade the individual node pools. Cluster auto-upgrade always upgrades the control plane and the node pools together. You can't upgrade the control plane only. Running the az aks upgrade --control-plane-only
command raises the following 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.
If using the node-image
(legacy and not to be used) cluster auto-upgrade channel or the NodeImage
node image auto-upgrade channel, Linux unattended upgrades are disabled by default.
Cluster auto-upgrade channels
Automatically completed upgrades are functionally the same as manual upgrades. The selected auto-upgrade channel determines the timing of upgrades. When making changes to auto-upgrade, allow 24 hours for the changes to take effect. Automatically upgrading a cluster follows the same process as manually upgrading a cluster. For more information, see Upgrade an AKS cluster.
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 upgrades the cluster to the latest supported patch version when it becomes available while keeping the minor version the same. | For example, if a cluster runs version 1.17.7, and versions 1.17.9, 1.18.4, 1.18.6, and 1.19.1 are available, the cluster upgrades to 1.17.9. |
stable |
automatically upgrades 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 runs version 1.17.7 and versions 1.17.9, 1.18.4, 1.18.6, and 1.19.1 are available, the cluster upgrades to 1.18.6. |
rapid |
automatically upgrades the cluster to the latest supported patch release on the latest supported minor version. | In cases where the cluster's Kubernetes version is 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 runs version 1.17.7 and versions 1.17.9, 1.18.4, 1.18.6, and 1.19.1 are available, the cluster first upgrades to 1.18.6, then upgrades to 1.19.1. |
node-image (legacy) |
automatically upgrades the node image to the latest version available. | Microsoft provides patches and new images for image nodes frequently (usually weekly), but your running nodes don't get the new images unless you do a node image upgrade. Turning on the node-image channel automatically updates your node images whenever a new version is available. If you use this channel, Linux [unattended upgrades] are disabled by default. Node image upgrades work on patch versions that are deprecated, so long as the minor Kubernetes version is still supported. This channel is no longer recommended and is set to be deprecated in future. For an option that can automatically upgrade node images, see the NodeImage channel in node image auto-upgrade. |
Note
Keep the following information in mind when using cluster auto-upgrade:
Cluster auto-upgrade only updates to GA versions of Kubernetes and doesn't update to preview versions.
With AKS, you can create a cluster without specifying the exact patch version. When you create a cluster without designating a patch, the cluster runs the minor version's latest GA patch. To learn more, see AKS support window.
Auto-upgrade requires the cluster's Kubernetes version to be within the AKS support window, even if using the
node-image
channel.If you're using the preview API
11-02-preview
or later, and you select thenode-image
cluster auto-upgrade channel, the node image auto-upgrade channel automatically sets toNodeImage
.Each cluster can only be associated with a single auto-upgrade channel. This is because your specified channel determines the Kubernetes version that runs on the cluster.
Use cluster auto-upgrade with a new AKS cluster
Set the auto-upgrade channel when creating a new cluster using the
az aks create
command and theauto-upgrade-channel
parameter.az aks create --resource-group myResourceGroup --name myAKSCluster --auto-upgrade-channel stable --generate-ssh-keys
Use cluster auto-upgrade with an existing AKS cluster
Set the auto-upgrade channel on an existing cluster using the
az aks update
command with theauto-upgrade-channel
parameter.az aks update --resource-group myResourceGroup --name myAKSCluster --auto-upgrade-channel stable
Use auto-upgrade with Planned Maintenance
If using Planned Maintenance and cluster auto-upgrade, your upgrade starts during your specified maintenance window.
Note
To ensure proper functionality, use a maintenance window of four hours or more.
For more information on how to set a maintenance window with Planned Maintenance, see Use Planned Maintenance to schedule maintenance windows for your Azure Kubernetes Service (AKS) cluster.
Best practices for cluster auto-upgrade
Use the following best practices to help maximize your success when using auto-upgrade:
- To ensure your cluster is 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 run the most recent node images. - To automatically upgrade node images while using a different cluster upgrade channel, consider using the node image auto-upgrade
NodeImage
channel. - Follow Operator best practices.
- Follow PDB best practices.
- For upgrade troubleshooting information, see the AKS troubleshooting documentation.
For a detailed discussion of upgrade best practices and other considerations, see AKS patch and upgrade guidance.
Azure Kubernetes Service
Pripomienky
https://aka.ms/ContentUserFeedback.
Pripravujeme: V priebehu roka 2024 postupne zrušíme službu Problémy v službe GitHub ako mechanizmus pripomienok týkajúcich sa obsahu a nahradíme ju novým systémom pripomienok. Ďalšie informácie nájdete na stránke:Odoslať a zobraziť pripomienky pre