Edit

Upgrade Kubernetes version of AKS clusters in AKS enabled by Arc using PowerShell

  • Article

Applies to: AKS on Azure Stack HCI 22H2, AKS on Windows Server

Two types of updates are available for an Azure Kubernetes Service (AKS) workload cluster in AKS enabled by Azure Arc:

  • Update the Kubernetes version of an AKS cluster.
  • Update the operating system version of an AKS cluster without updating the Kubernetes version.

Note

You can also use Windows Admin Center to upgrade AKS workload clusters.

We recommend updating an AKS workload cluster at least once every 60 days. New Kubernetes version updates are available every 30 days. To avoid outages in workload availability, rolling updates are performed. When you bring a new node with a newer build into the cluster, resources move from the old node to the new node. When the resources are successfully moved, the old node is decommissioned and removed from the cluster.

Important

Updating the Azure Kubernetes Service on the AKS host is the first step in any update flow and must be initiated before running Update-AksHciCluster. For information about updating the AKS host, see Update the AKS host on Azure Stack HCI.

Get available Kubernetes versions

Use the Get-AksHciKubernetesVersion command to check for supported Kubernetes versions:

Get-AksHciKubernetesVersion

Sample output:

OrchestratorType OrchestratorVersion OS      IsPreview
---------------- ------------------- --      ---------
Kubernetes       v1.18.14            Linux       False
Kubernetes       v1.18.17            Linux       False
Kubernetes       v1.19.7             Linux       False
Kubernetes       v1.19.9             Linux       False
Kubernetes       v1.20.2             Linux       False
Kubernetes       v1.20.5             Linux       False
Kubernetes       v1.18.14            Windows     False
Kubernetes       v1.18.17            Windows     False
Kubernetes       v1.19.7             Windows     False
Kubernetes       v1.19.9             Windows     False
Kubernetes       v1.20.2             Windows     False
Kubernetes       v1.20.5             Windows     False

Get available workload cluster updates

The following example assumes that the workload cluster myCluster is currently on Kubernetes version 1.19.7:

Get-AksHciClusterUpdates -name myCluster

details                                                     kubernetesversion operatingsystemversion
-------                                                     ----------------- ----------------------
This is a patch kubernetes upgrade. (i.e v1.1.X  to v1.1.Y) v1.19.9           @{mariner=April 2021; windows=April 2021}
This is a minor kubernetes upgrade. (i.e v1.X.1 to v1.Y.1)  v1.20.5           @{mariner=April 2021; windows=April 2021}

As you can see from this output, you can either perform a patch update to v1.19.9 or a minor update to v1.20.5.

Upgrade Kubernetes version of a workload cluster using PowerShell

Use the Update-AksHciCluster PowerShell command to perform a Kubernetes minor update. This command also updates the operating system version of your container host OS:

Update-AksHciCluster -name myCluster -kubernetesVersion v1.20.5

Update container OS version without updating Kubernetes

If you upload a workload cluster to a newer version of the operating system without changing the Kubernetes version, it doesn't work unless the new OS version does not require a different Kubernetes version. Run the Update-AksHciCluster command and specify the operatingSystem parameter to update the container hosts of AKS workload clusters to a newer version of the operating system. The following example assumes that the workload cluster myCluster currently has an operating system version that's more than 30 days old:

Update-AksHciCluster -name myCluster -operatingSystem

Next steps

In this article, you learned how to update AKS workload clusters in AKS Arc. Next, you can: