Skip to content

Files

Latest commit

alexbuckgitalexbuckgit
[BULK UPDATE] DocuTune - Apply event-tier1-build-2022 ms.custom tag t…
May 23, 2022
55762f7 · May 23, 2022

History

History
300 lines (222 loc) · 11.8 KB

tutorial-kubernetes-upgrade-cluster.md

File metadata and controls

300 lines (222 loc) · 11.8 KB
title description services ms.topic ms.date ms.custom
Kubernetes on Azure tutorial - Upgrade a cluster
In this Azure Kubernetes Service (AKS) tutorial, you learn how to upgrade an existing AKS cluster to the latest available Kubernetes version.
container-service
tutorial
05/24/2021
mvc, devx-track-azurepowershell, event-tier1-build-2022

Tutorial: Upgrade Kubernetes in Azure Kubernetes Service (AKS)

As part of the application and cluster lifecycle, you may wish to upgrade to the latest available version of Kubernetes and use new features. An Azure Kubernetes Service (AKS) cluster can be upgraded using the Azure CLI.

In this tutorial, part seven of seven, a Kubernetes cluster is upgraded. You learn how to:

[!div class="checklist"]

  • Identify current and available Kubernetes versions
  • Upgrade the Kubernetes nodes
  • Validate a successful upgrade

Before you begin

In previous tutorials, an application was packaged into a container image. This image was uploaded to Azure Container Registry, and you created an AKS cluster. The application was then deployed to the AKS cluster. If you have not done these steps, and would like to follow along, start with Tutorial 1 – Create container images.

Azure CLI

This tutorial requires that you are running the Azure CLI version 2.0.53 or later. Run az --version to find the version. If you need to install or upgrade, see Install Azure CLI.

Azure PowerShell

This tutorial requires that you're running Azure PowerShell version 5.9.0 or later. Run Get-InstalledModule -Name Az to find the version. If you need to install or upgrade, see Install Azure PowerShell.

Get available cluster versions

Azure CLI

Before you upgrade a cluster, use the az aks get-upgrades command to check which Kubernetes releases are available for upgrade:

az aks get-upgrades --resource-group myResourceGroup --name myAKSCluster

In the following example, the current version is 1.18.10, and the available versions are shown under upgrades.

{
  "agentPoolProfiles": null,
  "controlPlaneProfile": {
    "kubernetesVersion": "1.18.10",
    ...
    "upgrades": [
      {
        "isPreview": null,
        "kubernetesVersion": "1.19.1"
      },
      {
        "isPreview": null,
        "kubernetesVersion": "1.19.3"
      }
    ]
  },
  ...
}

Azure PowerShell

Before you upgrade a cluster, use the Get-AzAksCluster cmdlet to determine which Kubernetes version you're running and what region it resides in:

Get-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster |
  Select-Object -Property Name, KubernetesVersion, Location

In the following example, the current version is 1.19.9:

Name         KubernetesVersion Location
----         ----------------- --------
myAKSCluster 1.19.9            eastus

Use the Get-AzAksVersion cmdlet to determine which Kubernetes upgrade releases are available in the region where your AKS cluster resides:

Get-AzAksVersion -Location eastus | Where-Object OrchestratorVersion -gt 1.19.9

The available versions are shown under OrchestratorVersion.

OrchestratorType    : Kubernetes
OrchestratorVersion : 1.20.2
DefaultProperty     :
IsPreview           :
Upgrades            : {Microsoft.Azure.Commands.Aks.Models.PSOrchestratorProfile}

OrchestratorType    : Kubernetes
OrchestratorVersion : 1.20.5
DefaultProperty     :
IsPreview           :
Upgrades            : {}

Upgrade a cluster

To minimize disruption to running applications, AKS nodes are carefully cordoned and drained. In this process, the following steps are performed:

  1. The Kubernetes scheduler prevents additional pods being scheduled on a node that is to be upgraded.
  2. Running pods on the node are scheduled on other nodes in the cluster.
  3. A node is created that runs the latest Kubernetes components.
  4. When the new node is ready and joined to the cluster, the Kubernetes scheduler begins to run pods on it.
  5. The old node is deleted, and the next node in the cluster begins the cordon and drain process.

[!INCLUDE alias minor version callout]

Azure CLI

Use the az aks upgrade command to upgrade the AKS cluster.

az aks upgrade \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --kubernetes-version KUBERNETES_VERSION

Note

You can only upgrade one minor version at a time. For example, you can upgrade from 1.14.x to 1.15.x, but cannot upgrade from 1.14.x to 1.16.x directly. To upgrade from 1.14.x to 1.16.x, first upgrade from 1.14.x to 1.15.x, then perform another upgrade from 1.15.x to 1.16.x.

The following condensed example output shows the result of upgrading to 1.19.1. Notice the kubernetesVersion now reports 1.19.1:

{
  "agentPoolProfiles": [
    {
      "count": 3,
      "maxPods": 110,
      "name": "nodepool1",
      "osType": "Linux",
      "storageProfile": "ManagedDisks",
      "vmSize": "Standard_DS1_v2",
    }
  ],
  "dnsPrefix": "myAKSClust-myResourceGroup-19da35",
  "enableRbac": false,
  "fqdn": "myaksclust-myresourcegroup-19da35-bd54a4be.hcp.eastus.azmk8s.io",
  "id": "/subscriptions/<Subscription ID>/resourcegroups/myResourceGroup/providers/Microsoft.ContainerService/managedClusters/myAKSCluster",
  "kubernetesVersion": "1.19.1",
  "location": "eastus",
  "name": "myAKSCluster",
  "type": "Microsoft.ContainerService/ManagedClusters"
}

Azure PowerShell

Use the Set-AzAksCluster cmdlet to upgrade the AKS cluster.

Set-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster -KubernetesVersion <KUBERNETES_VERSION>

Note

You can only upgrade one minor version at a time. For example, you can upgrade from 1.14.x to 1.15.x, but cannot upgrade from 1.14.x to 1.16.x directly. To upgrade from 1.14.x to 1.16.x, first upgrade from 1.14.x to 1.15.x, then perform another upgrade from 1.15.x to 1.16.x.

The following condensed example output shows the result of upgrading to 1.19.9. Notice the kubernetesVersion now reports 1.20.2:

ProvisioningState       : Succeeded
MaxAgentPools           : 100
KubernetesVersion       : 1.20.2
PrivateFQDN             :
AgentPoolProfiles       : {default}
Name                    : myAKSCluster
Type                    : Microsoft.ContainerService/ManagedClusters
Location                : eastus
Tags                    : {}

View the upgrade events

When you upgrade your cluster, the following Kubenetes events may occur on each node:

  • Surge – Create surge node.
  • Drain – Pods are being evicted from the node. Each pod has a 5 minute timeout to complete the eviction.
  • Update – Update of a node has succeeded or failed.
  • Delete – Deleted a surge node.

Use kubectl get events to show events in the default namespaces while running an upgrade. For example:

kubectl get events

The following example output shows some of the above events listed during an upgrade.

...
default 2m1s Normal Drain node/aks-nodepool1-96663640-vmss000001 Draining node: [aks-nodepool1-96663640-vmss000001]
...
default 9m22s Normal Surge node/aks-nodepool1-96663640-vmss000002 Created a surge node [aks-nodepool1-96663640-vmss000002 nodepool1] for agentpool %!s(MISSING)
...

Validate an upgrade

Azure CLI

Confirm that the upgrade was successful using the az aks show command as follows:

az aks show --resource-group myResourceGroup --name myAKSCluster --output table

The following example output shows the AKS cluster runs KubernetesVersion 1.19.1:

Name          Location    ResourceGroup    KubernetesVersion    ProvisioningState    Fqdn
------------  ----------  ---------------  -------------------  -------------------  ----------------------------------------------------------------
myAKSCluster  eastus      myResourceGroup  1.19.1               Succeeded            myaksclust-myresourcegroup-19da35-bd54a4be.hcp.eastus.azmk8s.io

Azure PowerShell

Confirm that the upgrade was successful using the Get-AzAksCluster cmdlet as follows:

Get-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster |
  Select-Object -Property Name, Location, KubernetesVersion, ProvisioningState

The following example output shows the AKS cluster runs KubernetesVersion 1.20.2:

Name         Location KubernetesVersion ProvisioningState
----         -------- ----------------- -----------------
myAKSCluster eastus   1.20.2            Succeeded

Delete the cluster

Azure CLI

As this tutorial is the last part of the series, you may want to delete the AKS cluster. As the Kubernetes nodes run on Azure virtual machines (VMs), they continue to incur charges even if you don't use the cluster. Use the az group delete command to remove the resource group, container service, and all related resources.

az group delete --name myResourceGroup --yes --no-wait

Azure PowerShell

As this tutorial is the last part of the series, you may want to delete the AKS cluster. As the Kubernetes nodes run on Azure virtual machines (VMs), they continue to incur charges even if you don't use the cluster. Use the Remove-AzResourceGroup cmdlet to remove the resource group, container service, and all related resources.

Remove-AzResourceGroup -Name myResourceGroup

Note

When you delete the cluster, the Azure Active Directory service principal used by the AKS cluster is not removed. For steps on how to remove the service principal, see AKS service principal considerations and deletion. If you used a managed identity, the identity is managed by the platform and does not require you to provision or rotate any secrets.

Next steps

In this tutorial, you upgraded Kubernetes in an AKS cluster. You learned how to:

[!div class="checklist"]

  • Identify current and available Kubernetes versions
  • Upgrade the Kubernetes nodes
  • Validate a successful upgrade

For more information on AKS, see AKS overview. For guidance on a creating full solutions with AKS, see AKS solution guidance.