升级 Azure Kubernetes 服务 (AKS) 群集

项目
12/02/2024

AKS 群集生命周期的一部分涉及到定期升级到最新的 Kubernetes 版本。必须应用最新的安全版本并通过升级来获取最新功能。本文介绍如何查找升级，以及如何将升级应用到 AKS 群集。

Kubernetes 版本升级

升级受支持的 AKS 群集时，不能跳过 Kubernetes 次要版本。必须按主版本号按顺序执行所有升级。例如，允许在 1.14.x ->1.15.x 或 1.15.x ->1.16.x 之间升级。不允许使用 1.14.x ->1.16.x。仅当从不受支持的版本升级回受支持的版本时，才可以跳过多个版本。例如，可从不受支持的 1.10.x 升级到受支持的 1.12.x（如果可用）。

从跳过两个或更多次要版本的不支持版本执行升级时，执行升级时无任何功能保障，并且不在服务级别协议和有限保修范围内。如果版本明显过期，建议重新创建群集。

开始之前

如果你使用的是 Azure CLI，本文要求 Azure CLI 2.34.1 或更高版本。运行 az --version 即可查找版本。如果需要进行安装或升级，请参阅安装 Azure CLI。
如果使用的是 Azure PowerShell，本文要求使用 Azure PowerShell 5.9.0 或更高版本。运行 Get-InstalledModule -Name Az 即可查找版本。如果需要进行安装或升级，请参阅安装 Azure PowerShell。
执行升级操作需要 Microsoft.ContainerService/managedClusters/agentPools/write RBAC 角色。有关 Azure RBAC 角色的详细信息，请参阅 Azure 资源提供程序操作。

警告

AKS 群集升级会触发节点的隔离和排空。如果可用计算配额较低，则升级可能会失败。

检查是否有可用的 AKS 群集升级

注意

如需随时掌握 AKS 修补程序的最新动态、发布的版本和更新，请参阅 AKS 发布跟踪器。

使用 az aks get-upgrades 命令检查哪些 Kubernetes 版本可用于群集。

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

以下示例输出显示当前版本为 1.26.6，可用版本在 upgrades 下列出：

{
  "agentPoolProfiles": null,
  "controlPlaneProfile": {
    "kubernetesVersion": "1.26.6",
    ...
    "upgrades": [
      {
        "isPreview": null,
        "kubernetesVersion": "1.27.1"
      },
      {
        "isPreview": null,
        "kubernetesVersion": "1.27.3"
      }
    ]
  },
  ...
}

使用 Get-AzAksVersion cmdlet 检查有哪些可用于群集的 Kubernetes 版本及其所在的区域。

Get-AzAksVersion -Location chinanorth3 | Where-Object OrchestratorVersion

以下示例输出显示 OrchestratorVersion 下的可用版本：

Default     IsPreview     OrchestratorType     OrchestratorVersion
-------     ---------     ----------------     -------------------
                          Kubernetes           1.27.1
                          Kubernetes           1.27.3

对 AKS 群集升级错误消息进行故障排除

以下示例输出表示 appservice-kube 扩展与 Azure CLI 版本不兼容（至少需要版本 2.34.1）：

The 'appservice-kube' extension is not compatible with this version of the CLI.
You have CLI core version 2.0.81 and this extension requires a min of 2.34.1.
Table output unavailable. Use the --query option to specify an appropriate query. Use --debug for more info.

如果收到此输出，则需要更新 Azure CLI 版本。 az upgrade 命令为版本 2.11.0 中新增，不能在 2.11.0 之前的版本中使用。可以重新安装 Azure CLI 以更新旧版本，如安装 Azure CLI 中所述。如果 Azure CLI 版本为 2.11.0 或更高版本，请运行 az upgrade，将 Azure CLI 升级到最新版本。

如果 Azure CLI 已更新并收到以下示例输出，则表示没有可用升级：

ERROR: Table output unavailable. Use the --query option to specify an appropriate query. Use --debug for more info.

如果没有可用升级，请使用受支持的 Kubernetes 版本创建新群集，并将工作负载从现有群集迁移到新群集。如果 az aks get-upgrades 显示没有可用升级，则 AKS 不支持将群集升级到较新的 Kubernetes 版本。

升级 AKS 群集

在群集升级过程中，AKS 执行以下操作：

向运行指定 Kubernetes 版本的群集添加新的缓冲区节点（或最大电涌中配置的节点数）。
隔离和排空旧节点之一，最大程度地减少对正在运行的应用程序的中断。如果使用的是最大激增，它会隔离和排空数量与指定缓冲区节点数相同的节点。
对于长时间运行的 Pod，可以配置节点排空超时，从而允许在逐出 Pod 和正常终止每个节点时使用自定义等待时间。如果未指定，则默认值为 30 分钟。允许的最小超时值为 5 分钟。排空超时的最大限制为 24 小时。
旧节点在完全排空时，会重置映像以接收新版本，并且会成为下一个要升级的节点的缓冲区节点。
此过程会重复进行，直到群集中的所有节点都已升级。
在此过程结束时，会删除上一个缓冲区节点，从而维持现有的代理节点计数和区域均衡。

注意

如果未指定补丁，群集会自动升级到指定的次要版本的最新 GA 补丁。例如，将 --kubernetes-version 设置为 1.28 会导致群集升级到 1.28.9。

有关详细信息，请参阅 AKS 中支持的 Kubernetes 次要版本升级。

使用 az aks upgrade 命令升级群集。

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

使用 az aks show 命令确认升级成功。

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

以下示例输出表明群集现在运行 1.27.3：

Name          Location    ResourceGroup    KubernetesVersion    ProvisioningState    Fqdn
------------  ----------  ---------------  -------------------  -------------------  ----------------------------------------------
myAKSCluster  chinanorth3      myResourceGroup  1.27.3               Succeeded            myakscluster-dns-379cbbb9.hcp.chinanorth3.cx.prod.service.azk8s.cn

使用 Set-AzAksCluster 命令升级群集。

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

使用 Get-AzAksCluster 命令确认升级成功。

Get-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster |
 Format-Table -Property Name, Location, KubernetesVersion, ProvisioningState, Fqdn

以下示例输出表明群集现在运行 1.27.3：

Name         Location KubernetesVersion ProvisioningState Fqdn                                   
----         -------- ----------------- ----------------- ----                                   
myAKSCluster chinanorth3   1.27.3            Succeeded         myakscluster-dns-379cbbb9.hcp.chinanorth3.cx.prod.service.azk8s.cn

设置自动升级通道

可以在群集上设置自动升级通道。有关详细信息，请参阅自动升级 AKS 群集。

自定义节点激增升级

重要

节点激增需要的订阅配额对应于为每个升级操作请求的最大激增计数。例如，一个群集有五个节点池，每个节点池有四个节点，共有 20 个节点。如果每个节点池的最大激增值为 50%，则额外需要 10 个节点（2 个节点/池 * 5 个池）的计算和 IP 配额才能完成升级。
节点池中的最大激增设置是永久性的。后续的 Kubernetes 升级或节点版本升级都将使用此设置。可以随时更改节点池的最大激增值。对于生产节点池，建议将 max-surge 设置为 33%。
如果使用的是 Azure CNI，需要验证子网中是否有可用 IP 以满足 Azure CNI 的 IP 要求。

默认情况下，AKS 会将升级配置为使用一个额外节点进行激增。最大激增设置的默认值为 1，这样会使 AKS 能够在隔离/排出现有应用程序之前创建额外的节点以替换旧版本的节点，从而最大限度地减少工作负载中断。可以自定义每个节点池的最大激增值。如果增大最大激增值，则升级过程可以更快完成，但可能会在升级过程中遇到中断。

例如，最大激增值为 100% 时，可以让升级过程尽可能快，但也会导致节点池中的所有节点同时被耗尽。对于测试环境，可能希望使用类似的较高的值。对于生产节点池，建议将 max_surge 设置为 33%。

AKS 可以接受整数值和百分比值作为最大激增值。整数值（例如 5）指示要激增五个额外的节点。值为 50% 指示激增值为池中当前节点计数的一半。最大激增百分比值的最小值可以为 1%，最大值可以为 100%。百分比值将向上舍入到最近的节点计数。如果最大激增值高于要升级的所需节点数，则要升级的节点数将用于最大激增值。在升级期间，最大激增值最小可以为 1，最大为节点池中的节点数。可以设置较大的值，但用于最大激增的最大节点数不能高于升级时池中的节点数。

设置最大激增值

使用 az aks nodepool add 或 az aks nodepool update 命令为新的或现有的节点池设置最大激增值。

# Set max surge for a new node pool
az aks nodepool add --name mynodepool --resource-group MyResourceGroup --cluster-name MyManagedCluster --max-surge 33%

# Update max surge for an existing node pool 
az aks nodepool update --name mynodepool --resource-group MyResourceGroup --cluster-name MyManagedCluster --max-surge 5

设置节点排空超时值

有时，某个 Pod 上可能会有长期运行的工作负载，并且在运行时无法将其重新安排到另一个节点，例如，必须完成运行的内存密集型有状态工作负载。在这些情况下，可以配置 AKS 在升级工作流中将遵循的节点排出超时。如果未指定节点排空超时值，则默认值为 30 分钟。允许的最小排空超时值为 5 分钟，排空超时的最大限制为 24 小时。

如果清空超时值已过并且 Pod 仍在运行，则将停止升级操作。任何后续 PUT 操作应该会恢复停止的升级。此外，建议长期运行的 Pod 配置 [terminationGracePeriodSeconds][https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/]。

使用 az aks nodepool add 或 az aks nodepool update 命令为新的或现有节点池设置节点排出超时。

# Set drain timeout for a new node pool
az aks nodepool add --name mynodepool --resource-group MyResourceGroup --cluster-name MyManagedCluster  --drain-timeout 100

# Update drain timeout for an existing node pool
az aks nodepool update --name mynodepool --resource-group MyResourceGroup --cluster-name MyManagedCluster --drain-timeout 45

设置节点浸泡时间值

要允许排出节点和继续重置映像之间等待一定的持续时间并转到下一个节点，可以将浸泡时间设置为 0 到 30 分钟之间的一个值。如果未指定节点浸泡时间值，则默认值为 0 分钟。

使用 az aks nodepool add、az aks nodepool update 或 az aks nodepool upgrade 命令为新的或现有节点池设置节点浸泡时间。

# Set node soak time for a new node pool
az aks nodepool add --name MyNodePool --resource-group MyResourceGroup --cluster-name MyManagedCluster --node-soak-duration 10

# Update node soak time for an existing node pool
az aks nodepool update --name MyNodePool --resource-group MyResourceGroup --cluster-name MyManagedCluster --max-surge 33% --node-soak-duration 5

# Set node soak time when upgrading an existing node pool
az aks nodepool upgrade --name MyNodePool --resource-group MyResourceGroup --cluster-name MyManagedCluster --max-surge 33% --node-soak-duration 20

查看升级事件

使用 kubectl get events 命令查看升级事件。

kubectl get events

以下示例输出显示了升级期间列出的一些上述事件：

...
default 2m1s Normal Drain node/aks-nodepool1-96663640-vmss000001 Draining node: [aks-nodepool1-96663640-vmss000001]
...
default 1m45s Normal Upgrade node/aks-nodepool1-96663640-vmss000001   Soak duration 5m0s after 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 nodepool1
...

后续步骤

若要了解如何配置自动升级，请参阅为 AKS 群集配置自动升级。

通过