你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

发生 API 中断性变更时自动停止 Azure Kubernetes 服务 (AKS) 群集升级

项目
08/02/2024

本文介绍了如何在 API 中断性变更时自动停止 Azure Kubernetes 服务 (AKS) 群集升级。

概述

若要一直使用受支持的 Kubernetes 版本，需要每年至少升级一次群集，并为所有可能的中断做好准备。这些中断包括 API 中断性变更、弃用以及 Helm 和容器存储接口 (CSI) 等依赖项导致的中断。预测这些中断并在不停机的情况下迁移关键工作负载可能比较困难。

可以将 AKS 群集配置为自动停止包含次要版本更改和已弃用 API 的升级操作，并提醒你注意此问题。此功能有助于避免意外中断，并使你有时间在继续升级之前及时解决已弃用的 API。

开始之前

在开始之前，请确保满足以下先决条件：

升级操作是群集控制平面的 Kubernetes 次要版本更改。
要升级到的 Kubernetes 版本为 1.26 或更高版本。
对于要升级到的目标版本，最后一次使用弃用的 API 必须在升级操作前的 12 小时内发生。 AKS 按小时记录使用情况，因此一小时内不一定会出现任何已弃用 API 的情况。

缓解停止的升级操作

如果满足先决条件，并尝试升级，则会收到如下示例错误消息：

Bad Request({
  "code": "ValidationError",
  "message": "Control Plane upgrade is blocked due to recent usage of a Kubernetes API deprecated in the specified version. Please refer to https://kubernetes.io/docs/reference/using-api/deprecation-guide to migrate the usage. To bypass this error, set enable-force-upgrade in upgradeSettings.overrideSettings. Bypassing this error without migrating usage will result in the deprecated Kubernetes API calls failing. Usage details: 1 error occurred:\n\t* usage has been detected on API flowcontrol.apiserver.k8s.io.prioritylevelconfigurations.v1beta1, and was recently seen at: 2023-03-23 20:57:18 +0000 UTC, which will be removed in 1.26\n\n",
  "subcode": "UpgradeBlockedOnDeprecatedAPIUsage"
})

有两种选择来缓解此问题：可以删除已弃用 API 的使用（推荐）或绕过验证以忽略 API 更改。

删除已弃用 API 的使用情况（建议）

在 Microsoft Azure 门户中，导航到群集资源，然后选择“诊断并解决问题”
选择“创建、升级、删除和缩放”>“Kubernetes API 弃用”。
从上次弃用的 API 使用情况被观察到的时间开始等待 12 小时。检查已弃用的 API 用法中的谓词，以了解它是否为 watch。如果是手表，则可以等待使用量下降到零。（还可以通过启用容器见解并浏览 kube 审核日志来检查过去的 API 使用情况。）
重试群集升级。

绕过验证以忽略 API 更改

注意

此方法要求使用 Azure CLI 2.53 或更高版本。如果已安装 aks-preview CLI 扩展，则需要更新到版本 0.5.154 或更高版本。不建议使用此方法，因为目标 Kubernetes 版本中弃用的 API 可能无法长期使用。建议在升级完成后尽快将其删除。

使用 az aks update 命令绕过验证，以忽略 API 中断性变更。指定 enable-force-upgrade 标志，并设置 upgrade-override-until 属性以定义跳过验证的窗口的末尾。如果未设置任何值，窗口期默认为从当前时间开始的三天。指定的日期和时间必须是将来的。
```
az aks update --name $CLUSTER_NAME --resource-group $RESOURCE_GROUP_NAME --enable-force-upgrade --upgrade-override-until 2023-10-01T13:00:00Z
```
注意

Z 是零 UTC/GMT 偏移量的区域指示符，也称为“Zulu”时间。此示例将窗口期的结尾设置为 13:00:00 GMT。有关详细信息，请参阅日期和时间组合表达方式。

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

az aks upgrade --name $CLUSTER_NAME --resource-group $RESOURCE_GROUP_NAME --kubernetes-version $KUBERNETES_VERSION

后续步骤

本文介绍如何在 API 中断性变更时自动停止 AKS 群集升级。若要详细了解 AKS 群集的更多升级选项，请参阅 Azure Kubernetes 服务 (AKS) 群集的升级选项。

通过