Edit

Upgrade the AKS host in AKS enabled by Arc using PowerShell

  • Article

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

This article describes how to update the Azure Kubernetes Service host in AKS enabled by Azure Arc.

Overview of AKS host updates

Updates to the AKS host always include the latest available version. Although you can update the host independently of workload cluster updates, you must always update the host before updating a workload cluster.

To avoid outages and loss of AKS 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 you successfully remove the resources, the old node is decommissioned and removed from the cluster.

Note

Microsoft recommends upgrading your AKS clusters within 30 days of a new release. If you don't update within this window, you have up to 90 days from your last upgrade before internal certificates and tokens expire. Once the certificates and tokens expire, the cluster is still functional; however, you must call Microsoft Support to upgrade. When you reboot the cluster after the 90-day period, it remains in a non-functional state. For more information about internal certificates and tokens, see the overview of certificate management.

Update the AKS host

The first step in any update flow is to run the Update-AksHci command to update the AKS host. Update-AksHci takes no arguments and always updates the management cluster to the latest version. You must initiate this step before running Update-AksHciCluster to update the Kubernetes cluster to a new version.

Important

The update command only works if you have installed the GA release or later. It does not work for earlier releases. This update command updates the AKS host and the on-premises Microsoft-operated cloud platform. This command does not update any existing AKS workload clusters. New AKS workload clusters created after updating the AKS host might differ from existing AKS workload clusters in their OS version and Kubernetes version.

We recommend updating AKS workload clusters immediately after updating the AKS host to get the newest OS versions and recent fixes. If a workload cluster is on an unsupported Kubernetes version in the next version of AKS Arc, the upgrade fails.

Example flow for updating an AKS host

Update the PowerShell modules

Make sure you always have the latest PowerShell modules installed on the AKS nodes by running the following command on all the physical nodes in your AKS deployment.

Important

You should close all open PowerShell windows and then open a fresh session to run the update command. If you don't close all PowerShell windows, there might be modules that are in use and can't be updated.

Update-Module -Name AksHci -Force -AcceptLicense

Get the current AKS Arc version

Get-AksHciVersion                    

1.0.0.10517

Get the available AKS Arc updates

Get-AksHciUpdates

The output shows the available versions to which this AKS host can be updated:

1.0.2.10723

Versioning

Using version 1.0.2.10723 as an example, the following table shows how version numbers are constructed for AKS Arc releases.

Value Meaning
1 Major version: +1 for each release with a large breaking change.
0 Minor version: +1 for each release after the latest major version with a major functionality change.
2 Feature & patch updates: +1 for each regular (typically monthly) release after the latest major version.
1 Build type: Always 1 for public-facing builds.
0723 Build creation date: Build creation date in mmdd format.

Initiate the AKS Arc update

Update-AksHci

Verify the AKS host was updated

Get-AksHciVersion

The output shows the updated version of AKS on the AKS host:

1.0.2.10723

Next steps