在出现 API 重大变更时，自动停止 Azure Kubernetes 服务（AKS）群集的升级

本文介绍如何在 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 的使用（建议）

在 Azure 门户中，导航到群集资源并选择“诊断并解决问题”
选择“ 创建”、“升级”、“删除”和“缩放>Kubernetes API 弃用”。
从最后一次看到弃用的 API 使用情况起，等待 12 小时。只读动词被排除在弃用的 API 用法之外，即 Get/List/Watch。（还可以通过启用容器见解并浏览 kube 审核日志来检查过去的 API 使用情况。）
重试群集升级。

绕过验证以忽略 API 更改

注释

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

绕过验证以忽略 API 重大变更并执行升级。指定 enable-force-upgrade 标志并设置 upgrade-override-until 属性以定义跳过验证的窗口末尾。如果未设置任何值，则会将窗口默认为从当前时间开始的三天。指定的日期和时间必须位于将来。
```
az aks upgrade --name $CLUSTER_NAME --resource-group $RESOURCE_GROUP_NAME --kubernetes-version $KUBERNETES_VERSION --enable-force-upgrade --upgrade-override-until 2023-10-01T13:00:00Z
```
注释

Z 是零 UTC/GMT 偏移量的区时标识符，也称为“Zulu”时间。本示例将窗口的末尾设置为 13:00:00 GMT。有关详细信息，请参阅合并日期和时间表示形式。

后续步骤

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

Last updated on 2026-01-16