在發生 API 破壞性變更時自動停止 Azure Kubernetes Service (AKS) 叢集升級

適用於: ✔️ AKS 自動化 ✔️ AKS 標準

本文說明 Azure Kubernetes Service （AKS） 如何在偵測到已棄用的 Kubernetes API 使用時自動阻擋叢集升級。

對於大多數生產工作負載，AKS Automatic 是 AKS 建議的生產就緒預設體驗。 Kubernetes API 重大變更偵測功能已在 AKS Automatic 和 AKS Standard 叢集中預先設定。

AKS Automatic 和 AKS Standard 中的行為

兩種叢集模式都包含以下保障措施：

  • AKS Automatic：預設隨附於 AKS Automatic 的可投入生產環境平台防護措施中。
  • AKS 標準：AKS 標準叢集預設包含。

在這兩種模式下，當 AKS 偵測到目標 Kubernetes 版本中已棄用或移除的 API 近期使用時，都能阻擋次要版本升級操作。

概觀

為了維持在支援的 Kubernetes 版本內，您必須每年至少升級一次叢集，並準備應對可能的中斷。 這些中斷可能包括破壞性 API 變更、棄用，以及例如 Helm 和容器儲存體介面 (CSI) 等相依性。 要預測這些中斷並遷移關鍵工作負載而不需停機，可能相當困難。

當 AKS 偵測到針對目標版本使用已淘汰的 API 時，可能會自動封鎖次要版本升級作業，並提醒你注意此問題。 這種行為有助於避免意外中斷，並給你時間修復已棄用的 API 使用狀況，然後再繼續升級。

Prerequisites

請確定您符合下列先決條件：

  • 升級作業是叢集控制平面的 Kubernetes 次要版本變更。
  • Kubernetes 的目標版本是 1.26 或更新版本。
  • 目標版本最後一次使用已棄用的 API 是在升級操作前 12 小時內。 AKS 會記錄每小時的使用情況，因此最近一小時內的使用情況不一定會被偵測到。

注意

你不需要手動啟用這個偵測功能。 AKS Automatic 和 AKS Standard 叢集會預先設定它。

減輕已停止的升級作業的問題

若符合 先決條件，嘗試升級，卻收到類似以下錯誤訊息的錯誤訊息：

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"
})

使用下列其中一個選項：

  1. 在 Azure 入口網站中，瀏覽至叢集資源，然後選取 [診斷並解決問題]

  2. 選取建立、升級、刪除和調整>Kubernetes API 棄用。

    Azure 入口網站的螢幕擷取畫面，其中顯示 [已選取的 Kubernetes API 淘汰] 區段。

  3. 自上次偵測到已棄用 API 的使用後，請等待 12 小時。 唯讀動詞不包含在已棄用 API 的使用情況中，也就是 Get/List/Watch。 你也可以透過啟用 容器洞察 和探索 kube 稽核日誌來查看過去的 API 使用情況。

  4. 重試叢集升級。

略過驗證以忽略 API 變更

注意

此方法需使用 Azure CLI 2.57 或更新版本。 如果你安裝了預覽版 CLI 擴充功能，請更新到 3.0.0b10 或更新版本。 這種方法不建議用於一般生產作業，因為目標 Kubernetes 版本中已棄用的 API 可能會長期失敗。 升級後盡快移除已棄用的 API 使用。

使用 az aks upgrade 命令搭配 --enable-force-upgrade 來執行略過驗證的升級，並設定 --upgrade-override-until 以定義略過視窗何時結束。 如果你沒有設定值，視窗會預設為從當前時間起算三天。 所提供的日期和時間必須是未來。

# Set environment variables
RESOURCE_GROUP_NAME=<your-resource-group-name>
CLUSTER_NAME=<your-cluster-name>
KUBERNETES_VERSION=<target-kubernetes-version>

# Run the upgrade command with validation bypass
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 遷移而非強制繞過。
  • 利用預定維護時段，並在升級前進行檢查。
  • 持續監控已棄用的 API 使用情況，以避免最後一刻的升級阻擋。

相關內容

本文說明如何在 API 重大變更上自動停止 AKS 叢集升級。 若要深入了解 AKS 叢集的更多升級選項，請參閱 Azure Kubernetes Service (AKS) 叢集的升級選項。

欲了解更多 AKS Automatic 資訊，請參閱以下文章：

  • 上次更新時間：