API の破壊的変更時に Azure Kubernetes Service (AKS) クラスターのアップグレードを自動的に停止する

適用対象: ✔️ AKS 自動 ✔️ AKS Standard

この記事では、Azure Kubernetes Service (AKS)が非推奨の Kubernetes API の使用を検出したときにクラスターのアップグレードを自動的にブロックする方法について説明します。

ほとんどの運用ワークロードでは、AKS の推奨される運用環境対応の既定のエクスペリエンスが AKS 自動です。 Kubernetes API の破壊的変更検出は、AKS 自動クラスターと AKS Standard クラスターの両方で事前構成されています。

AKS 自動および AKS Standard での動作

どちらのクラスター モードにも、次のセーフガードが含まれます。

  • AKS Automatic: AKS Automatic の本番対応プラットフォーム保護機能の一部として、既定で含まれます。
  • AKS Standard: AKS Standard クラスターには既定で含まれます。

どちらのモードでも、AKS は、ターゲットの Kubernetes バージョンで非推奨または削除された API の最近の使用を検出したときに、マイナー バージョンのアップグレード操作をブロックできます。

概要

サポートされている Kubernetes バージョン内を維持するには、クラスターを少なくとも 1 年に 1 回アップグレードし、中断の可能性に備える必要があります。 これらの中断には、API の破壊的変更、非推奨、Helm や Container Storage Interface (CSI) などの依存関係が含まれる場合があります。 これらの中断を予測し、ダウンタイムなしで重要なワークロードを移行することは困難な場合があります。

AKS は、ターゲット バージョンの非推奨の API の使用を検出すると、マイナー バージョンのアップグレード操作を自動的にブロックし、問題にアラートを送信できます。 この動作は、予期しない中断を回避するのに役立ち、アップグレードを続行する前に非推奨の API の使用を修正する時間を与えます。

Prerequisites

次の前提条件を満たしていることを確認します。

  • アップグレード操作は、クラスター コントロール プレーンの Kubernetes マイナー バージョンの変更である。
  • Kubernetes ターゲット バージョンは 1.26 以降です。
  • ターゲット バージョンで非推奨の API が最後に使用されたのは、アップグレード操作の 12 時間以内に発生しました。 AKS では 1 時間ごとに使用状況が記録されるため、直近の 1 時間以内の使用状況が検出に表示されるとは限りません。

注

この検出機能を手動で有効にする必要はありません。 AKS 自動クラスターと 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 portal で、クラスター リソースに移動し、[問題の診断と解決] を選びます

  2. [作成、アップグレード、削除、スケーリング]>[Kubernetes API の非推奨化] を選びます。

    選択された [Kubernetes API 非推奨] セクションが表示されている Azure portal のスクリーンショット。

  3. 最後に非推奨の API の使用状況が表示された時点から 12 時間待ちます。 読み取り専用動詞は、非推奨の API の使用 ( Get/List/Watch) から除外されます。 Container Insights を有効にし、kube 監査ログを調べて、過去の API の使用状況を確認することもできます。

  4. クラスターのアップグレードを再試行します。

検証を回避して API の変更を無視する

注

この方法では、バージョン 2.57 以降Azure CLI必要です。 プレビュー CLI 拡張機能がインストールされている場合は、バージョン 3.0.0b10 以降に更新してください。 ターゲットの Kubernetes バージョンで非推奨の API が長期的に失敗する可能性があるため、この方法は通常の運用操作には推奨されません。 非推奨の API の使用は、アップグレード後にできるだけ早く削除してください。

az aks upgradeで--enable-force-upgrade コマンドを使用して検証バイパスを使用してアップグレードを実行し、バイパス ウィンドウが終了するタイミングを定義する--upgrade-override-untilを設定します。 値を設定しない場合、ウィンドウの既定値は現在の時刻から 3 日になります。 指定された日付と時刻は将来である必要があります。

# 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 の詳細については、次の記事を参照してください。

  • Last updated on