Edit

Upgrading Azure Kubernetes Service (AKS) clusters and node pools

Applies to: ✔️ AKS Automatic ✔️ AKS Standard

An Azure Kubernetes Service (AKS) cluster needs to be periodically updated to ensure security and compatibility with the latest features. There are two components of an AKS cluster that are necessary to maintain:

  • Cluster Kubernetes version: As part of the AKS cluster lifecycle, perform upgrades to the latest Kubernetes version. Upgrade to apply the latest security releases and to get access to the latest Kubernetes features. Stay within the AKS support window.
  • Node image version: AKS regularly provides new node images with the latest operating system (OS) and runtime updates. Regularly upgrade your node images to ensure support for the latest AKS features and to apply essential security patches and hotfixes.

For Linux nodes, you can apply node image security patches and hotfixes without your initiation as unattended updates. These updates are automatically applied, but AKS doesn't automatically reboot your Linux nodes to complete the update process. You need to use a tool like kured or node image upgrade to reboot the nodes and complete the cycle.

AKS Automatic: Production-ready upgrades by default

AKS Automatic clusters simplify cluster management by including automatic cluster and node upgrades by default. If you're using AKS Automatic, your cluster is already configured with:

  • Automatic Kubernetes version upgrades by using the stable channel (N-1 minor version).
  • Automatic node OS image upgrades with security patches and bug fixes.
  • Built-in API breaking change detection that stops upgrades if deprecated Kubernetes APIs are detected.
  • Automatic node repair and cluster component patching.
  • Guaranteed SLAs: 99.9% pod readiness within five minutes during upgrades, and 99.95% uptime for the Kubernetes API server.

No action is required on your part. AKS Automatic handles upgrades automatically during planned maintenance windows. This article covers advanced upgrade strategies for scenarios beyond the Automatic defaults.

Tip

Using AKS Automatic? Your cluster is preconfigured for production-ready upgrades with SLA guarantees. Continue reading only if you need advanced customization, multi-cluster orchestration, or manual upgrade control for non-Automatic clusters.

Component upgrade overview

The following table summarizes the upgrade frequency, methods, and support for each component. The AKS Automatic? column shows how AKS Automatic handles each component:

Component name Frequency AKS Automatic? Planned maintenance Supported methods (Standard) Multi-cluster support Learn more
Cluster Kubernetes version (minor) Roughly every three months Yes - Automatic (stable channel N-1) Yes Automatic, Manual Automatic, Manual Upgrade an AKS cluster, Multi-cluster upgrade
Cluster Kubernetes version (patch) Approximately weekly Yes - Automatic Yes Automatic, Manual Manual Upgrade an AKS cluster, AKS release tracker
Node OS image (Linux) Weekly Yes - Automatic Yes Automatic, Manual Automatic, Manual AKS node image upgrade
Node OS image (Windows) Monthly N/A Yes Automatic, Manual Automatic, Manual AKS node image upgrade
Security patches and hotfixes As needed Yes - Automatic N/A N/A Unsupported AKS node security patches

Advanced upgrade strategies

For advanced upgrade scenarios beyond AKS Automatic defaults, explore specialized upgrade patterns:

See AKS production upgrade strategies for detailed implementation guidance on these patterns.

Multi-cluster upgrade orchestration

When managing multiple AKS clusters, following consistent deployment and testing patterns is critical for minimizing disruptions:

  • Test first, deploy second: Always test upgrades in a development or test environment before production to identify compatibility issues, bugs, or performance impacts.
  • Consistent versioning across regions: Maintain consistent Kubernetes and node OS image versions across clusters in different regions to simplify operations and troubleshooting.

Azure Kubernetes Fleet Manager provides built-in orchestration for multi-cluster upgrades with:

  • Customizable upgrade ordering across clusters
  • Validation gates between upgrade stages
  • Automatic or scheduled update coordination
  • Consistent node OS image versions across regions

For AKS Automatic clusters, Fleet Manager's automatic upgrade orchestration implements these best practices by default, safely progressing upgrades through your fleet with integrated testing and validation.

For AKS Standard clusters, see Multi-cluster upgrade orchestration for step-by-step guidance.

Automatic upgrades

You can configure automatic upgrades through multiple methods:

  • Auto upgrade channels: AKS Automatic uses the stable channel by default. AKS Standard clusters can choose from release channels (patch, stable, rapid) or rapid N-1 for earlier access to new versions.
  • GitHub Actions: Automate node upgrades through CI/CD pipelines.
  • Azure Kubernetes Fleet Manager: Automatic multi-cluster upgrades with coordinated deployment across your fleet and testing and validation gates.

Planned maintenance

For both AKS Automatic and AKS Standard clusters, planned maintenance allows you to schedule weekly maintenance windows that update your control plane and your kube-system pods, helping to minimize workload impact.

Planned maintenance for AKS Automatic

For AKS Automatic clusters, planned maintenance is optional:

  • Default behavior: Automatic upgrades are scheduled during planned maintenance windows automatically, minimizing disruption.
  • Customization: You can configure a custom planned maintenance schedule to control when upgrades occur and ensure minimal impact on your applications.
  • No action required: If you don't configure a custom schedule, AKS Automatic upgrades proceed during default maintenance windows with built-in safeguards.

Planned maintenance for AKS Standard

For AKS Standard clusters, planned maintenance windows help align upgrades with your operational schedule and reduce unexpected disruptions.

Service level agreement (SLA) guarantees for upgrades

AKS Automatic SLAs

AKS Automatic includes financially-backed SLA guarantees that apply during and outside of upgrade operations:

  • Pod readiness SLA: 99.9% of qualifying pod readiness operations complete within 5 minutes, covering pod scheduling and node provisioning during upgrades and scaling events.
  • Cluster uptime SLA: 99.95% availability of the Kubernetes API server, ensuring your cluster remains responsive during upgrades.

These SLAs are included with every AKS Automatic cluster at no extra cost and require no configuration.

AKS Standard SLAs

AKS Standard clusters can optionally enable:

  • Uptime SLA: 99.95% availability of the Kubernetes API server (optional, available at Standard or Premium tiers).

Troubleshooting upgrade issues

Most AKS upgrades finish without problems, especially when you use AKS Automatic's built-in safeguards and API breaking change detection. If you encounter errors during manual upgrades or on AKS Standard clusters, review the following troubleshooting guides:

Related content

  • Last updated on