Kubernetes is the de facto standard for container orchestration. If you don’t want to manage the operations yourself, you can opt for a managed solution like Microsoft’s Azure Kubernetes Service (AKS). With AKS, many operational aspects are handled for you. Even the updates to newer Kubernetes version can be entirely managed by Azure. You can learn how to configure auto-upgrades in AKS from this article.

However, if you want to determine the version and timing of a cluster upgrade yourself, you can achieve this using the Azure CLI or even better, through Terraform. Of course, this assumes that you have provisioned your Kubernetes infrastructure using Terraform.

Azure Kubernetes Versions

Microsoft provides a list of supported Kubernetes versions along with their support periods in the documentation.

It’s important to note that updates are only possible within a minor version or to the next minor version. For example, if you want to update from version 1.24 to 1.26, you need to do it through version 1.25 in two steps.

The available versions depend on the region where the cluster is located. You can use the Azure CLI to query the available versions for a specific region.

az aks get-versions \
  --location westeurope \
  --output table

The output provides a list of available versions and the possible upgrades.

KubernetesVersion    Upgrades
-------------------  -----------------------
1.26.3               None available
1.26.0               1.26.3
1.25.6               1.26.0, 1.26.3
1.25.5               1.25.6, 1.26.0, 1.26.3
1.24.10              1.25.5, 1.25.6
1.24.9               1.24.10, 1.25.5, 1.25.6

You can also query the available upgrades for a specific cluster.

az aks get-upgrades \
  --resource-group rg-aks-test \
  --name aks-test \
  --output table

The result will show the available upgrades precisely.

Name     ResourceGroup    MasterVersion    Upgrades
-------  ---------------  ---------------  --------------
default  rg-aks-test      1.24.10          1.25.5, 1.25.6

Terraform

Configuring an AKS (Azure Kubernetes Service) cluster using Terraform is a straightforward process. Through the Azure Provider, you create the corresponding resource, azurerm_kubernetes_cluster.

In this configuration, you set the version of the control plane using kubernetes_version and the version of the nodes using default_node_pool.orchestrator_version.

terraform {
  required_version = ">= 0.13"

  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 3.48.0"
    }
  }
}

# Configure the Azure Provider via environment variables
provider "azurerm" {
  features {}
}

# Resource Group
resource "azurerm_resource_group" "rg" {
  name     = "rg-aks-test"
  location = "westeurope"
}

# AKS Cluster
resource "azurerm_kubernetes_cluster" "aks" {
  name                              = "aks-test"
  location                          = azurerm_resource_group.rg.location
  resource_group_name               = azurerm_resource_group.rg.name
  dns_prefix                        = "k8s"
  kubernetes_version                = "1.24.10"
  role_based_access_control_enabled = true

  default_node_pool {
    name                 = "default"
    node_count           = 2
    vm_size              = "Standard_B2s"
    orchestrator_version = "1.24.10"
  }

  identity {
    type = "SystemAssigned"
  }
}

A simple terraform apply, and after a few minutes, you’ll have an AKS cluster available in the desired version.

Upgrade with Terraform

To upgrade your AKS cluster to a higher version, simply modify the version numbers in your Terraform configuration file, both for the control plane and the node pools. Then, execute a terraform apply command to initiate the upgrade process. The upgrade process will remove each node from the cluster one by one and replace them with updated versions. Running pods will be redistributed among the remaining nodes and will remain accessible throughout the process. The duration of the upgrade process depends on the number of nodes and may take several minutes to hours.

If you are using a CI/CD pipeline for infrastructure changes, make sure that the process doesn’t time out.

You can monitor the upgrade progress through the Azure CLI or the Azure Portal.

az aks list -o table

az aks nodepool list \
  --resource-group rg-aks-test \
  --cluster-name  aks-test \
  --output table

The ProvisioningState will change to Upgrading.

Name     OsType    KubernetesVersion    ProvisioningState
-------  --------  -------------------  -------------------
default  Linux     1.25.6               Upgrading

Upon completion of the upgrade, the ProvisioningState will change back to Succeeded, and all nodes will be running on the new Kubernetes version.