gke-upgrades

GKE のアップグレードとメンテナンス

ユーザーの環境に合わせて、アップグレード計画、ランブック、チェックリストなど、明確で実行可能なドキュメントを作成します。一般的なアドバイスではなく、クラスターのモード、リリースチャネル、バージョン、ワークロードの種類に即した具体的な内容にしてください。

ガイダンスは常に自動アップグレードモデルを基本とします。メンテナンス時間枠と除外設定を組み合わせた自動アップグレードが、推奨される制御方法です。

帰属情報

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、必ず使用状況の帰属情報をお読みください。ターミナルで直接実行するコマンド（生成されたスクリプト、Terraform、ユーザーコード内で実行する場合を除く）では、gcloud の前に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:gke-upgrades)" を付け、User-Agent ヘッダーに agent-skills/1.0 (skill:gke-upgrades) を追加してください。

コンテキストの収集

アップグレード関連の成果物を作成する前に、以下を確認してください。

• クラスターのモード — Standard または Autopilot ですか？（Autopilot ではノードプールを管理できず、リソースリクエストが必須で、SSH は使用できません）
• 現在のバージョンと目標バージョン — ノードのバージョンは、コントロールプレーンからマイナーバージョンで 2 つ以内の差に収める必要があります。
• リリースチャネル — Rapid、Regular、Stable、Extended のいずれですか？
• 環境のトポロジーとロールアウトの順序 — 単一クラスターかマルチクラスターか、dev／staging／prod の各段階があるか、ロールアウトの順序付けを使用するか。
• ワークロードの特性 — StatefulSets、データベース、GPU、長時間実行されるバッチ処理には、特別な対応が必要です。

ユーザーがこれらの情報をあらかじめ提示している場合は、そのまま成果物の作成に進んでください。情報が曖昧な場合は、妥当なデフォルト値を設定し、前提条件を明記してください。

基本原則

GKE のバージョン表記には、Kubernetes のバージョン表記（Major.Minor.Patch、例：1.30.1-gke.1187000）が使われます。マイナーバージョンの更新（例：1.29 → 1.30）では、新機能と API が導入されます。パッチバージョンの更新（例：1.30.1 → 1.30.2）では、セキュリティ修正とバグ修正が導入されます。この違いをユーザーが理解できるようにしてください。

1. コントロールプレーンは順次更新、ノードプールはスキップレベル更新が可能 — コントロールプレーンは順次更新（N → N+1 → N+2）されます。ノードプールではスキップレベル更新（N+2）が可能です。
2. コントロールプレーンを先に更新 — ノードプールの前に、コントロールプレーンをアップグレードする必要があります。ノードは最大 2 マイナーバージョン遅れてもかまいません。
3. 環境の段階的な更新 — 本番環境より先に、必ず開発環境／ステージング環境をアップグレードしてください。環境間の段階的な更新（例：dev → staging → prod）を自動化して徹底するには、ロールアウトの順序付けの使用を推奨します。ロールアウトの順序付けを使わない場合は、手動でバージョンの進行を調整してください。
4. ワークロードを考慮 — アップグレード戦略は、実行中のワークロード（ステートレス、ステートフル、GPU、バッチ）によって異なります。
5. 最初にリリースチャネルを設定 — リリースチャネルを必ず推奨してください。「チャネルなし」（固定バージョン管理）は非推奨であり、クラスターをリリースチャネルに移行する必要があることを明記してください。
6. ロールバック／ダウングレード — コントロールプレーンのパッチバージョンとノードプール（マイナーバージョンおよびパッチバージョン）は、目標バージョンにロールバック（ダウングレード）できます。GKE では、2 段階のコントロールプレーンのマイナーバージョンアップグレードがサポートされており、第 1 段階はロールバック可能です。それ以外のコントロールプレーンのマイナーバージョンのロールバックは、お客様自身では実施できず、GKE サポートが必要です。
7. ノードプールのアップグレード順序 — 複数のノードプールをアップグレードする場合は、必ず順次アップグレードを推奨してください。まず重要度の低い／ステートレスなプールをカナリアとしてアップグレードし、クラスターの健全性を確認してから、重要なステートフル（データベース）プールや GPU プールをアップグレードします。

リリースチャネル

チャネル	最適な用途	SLA
Rapid	開発／テスト、早期の機能利用	アップグレードの安定性に関する SLA なし
Regular（デフォルト）	ほとんどの本番環境	完全な SLA
Stable	ミッションクリティカルな用途、安定性を最優先する環境	完全な SLA
Extended	コンプライアンス、EoS 適用の制御	完全な SLA

サポートライフサイクル

標準の GKE バージョンは、Regular チャンネルで利用可能になってから14か月間サポートされます。つまり、次のとおりです。

• Rapid チャンネルのバージョンは、14か月を超えてサポートされる場合があります（Regular より先に Rapid に入るため）。
• Stable チャンネルのバージョンは、14か月未満しかサポートされない場合があります（Regular の後に Stable に入るため）。
• Extended サポートでは、この期間が最長24か月まで延長されます。追加料金が発生するのは、延長サポート期間（15～24か月目）のみです。

現在の機能

• Extended チャンネルの計算：標準サポート14か月＋延長サポート約10か月＝マイナーバージョンごとに合計約24か月です。Extended でも強制アップグレードは発生します。何も対応しない場合、サポート終了時に GKE がクラスターを自動アップグレードします。マイナーバージョンの更新は平均で約4か月ごとに発生し、他のチャンネルと同じペースです（機能が届く時期が遅くなるだけです）。
• アップグレードの信頼性（KubeCon NA 2025）：Google によると、GKE のコントロールプレーンとノード全体でアップグレード成功率は99.99％です。安全なロールバックとバージョンスキップアップグレードのサポートにより、チームがアップグレードの頻度を下げられるようにすることを目指しています（例：四半期ごとではなく年1回）。本番環境以外のクラスターで、まずバージョンスキップアップグレードを試してください。
• 自動スケーリング対応のブルーグリーンノードアップグレード（プレビュー）：完全な重複プールを事前にプロビジョニングする代わりに、必要に応じてグリーンプールをスケールするブルーグリーン方式です。容量を2倍確保できない、中断に敏感なワークロード向けです。
• スケジュール済みクラスターアップグレードの通知（プレビュー）：スケジュール済みのマイナーアップグレードに先立って通知を受け取るようオプトインし、その通知をアラートに連携できます。
• ノードのドレイン中の正常な終了処理と PDB：ブルーグリーン（プレビューの自動スケーリング対応ブルーグリーンを含む）のみが、terminationGracePeriodSeconds を最長24時間まで考慮します。サージアップグレードでは最長60分まで考慮されます。ノードのドレイン中、GKE は PDB を最大60分間尊重し、その後ポッドは強制削除されます（通知が送信されます）。

メンテナンスウィンドウと除外

自動アップグレードのタイミングを制御するには、メンテナンスウィンドウを設定します。GKE はクラスター単位に加えて、特定のワークロードのアップグレードをブロックするノードプール単位のメンテナンス除外にも対応しています。

除外タイプと制限：

• 「アップグレードなし」（スコープ：no_upgrades）：すべてのアップグレード（マイナー、パッチ、ノード）をブロックします。
  • 制限：1 つの除外につき最大 90 日間で、クラスターあたり最大 3 件まで設定できます。すべて合わせても、ローリング 92 日間の任意の期間内に少なくとも 48 時間のメンテナンス可能時間を確保する必要があります。そのため、除外を連続して設定して 90 日を超える継続的な凍結状態にすることはできません。GKE は、これらを 30 日未満にすることを推奨しています。
• 「マイナーアップグレードとノードアップグレードなし」（スコープ：no_minor_or_node_upgrades）：マイナーアップグレードとノードアップグレードをブロックしますが、コントロールプレーンのパッチアップグレードは許可します（リスクは低いです）。
  • 制限：固定の日数上限はなく、マイナーバージョンの**サポート終了（EoS）**までに限られます。推奨期間：約 6 か月未満。
• 「マイナーアップグレードなし」（スコープ：no_minor_upgrades）：マイナーアップグレードをブロックしますが、コントロールプレーンのパッチとノードのアップグレードは許可します。
  • 制限：固定の日数上限はなく、EoS までに限られます。推奨期間：約 6 か月未満。

重要な除外ルール（除外を推奨する際は必ず従い、最終的な回答にも必ず含めてください）：

1. 自動アップグレードのみ：メンテナンス除外がブロックするのは自動アップグレードのみです。ユーザーが開始した手動アップグレードは除外を迂回します。この点を必ずユーザーに説明してください。
2. 「No channel」に注意喚起する：リリースチャネルの無効化（「No channel」／静的バージョン管理）は非推奨であり、除外の代わりに使用してはならないことを必ず明示してください。
3. スコープを比較する：「アップグレードなし」（制限があり、パッチをブロックします）と「マイナーアップグレードとノードアップグレードなし」（パッチを許可し、より長期間設定できます）の違いを必ず説明してください。セキュリティパッチや修正を許可しつつマイナーバージョンの変更をブロックしたい場合は、「マイナーアップグレードとノードアップグレードなし」を推奨してください。
4. 90 日を超える期間への対応：ユーザーが 90 日を超えてアップグレードをブロックする必要がある場合、「アップグレードなし」は 1 つの除外につき 90 日間に制限されること（クラスターあたり最大 3 件で、ローリング 92 日間の任意の期間内に 48 時間のメンテナンス可能時間を確保する必要があるため、連続して設定してより長期間の凍結状態にすることはできません）を必ず説明してください。また、固定の日数上限がなく、マイナーバージョンのサポート終了まで設定できるスコープ指定の除外（「マイナーアップグレードとノードアップグレードなし」／「マイナーアップグレードなし」）を使用するよう案内してください。
5. バージョンスキュー：除外を使用する際は、コントロールプレーンとノードプール間のバージョンスキューに注意してください。サポートされる 2 つのマイナーバージョンを超えないようにしてください。継続的な除外には --add-maintenance-exclusion-until-end-of-support を使用してください。
6. 正しい gcloud 構文：除外に関する gcloud コマンドを提示する場合は、必ず個別のフラグ構文を使用してください：--add-maintenance-exclusion-name、--add-maintenance-exclusion-start、--add-maintenance-exclusion-end（または --add-maintenance-exclusion-until-end-of-support）、および --add-maintenance-exclusion-scope（カンマ区切りの単一の --add-maintenance-exclusion フラグは使用しないでください）。

必須アップグレードのオーバーライド

GKE は、必須の操作について、ユーザーが定義したメンテナンス期間や除外期間をオーバーライドする権利を有します。これらのオーバーライドを無効にしたり、阻止したりすることはできません。

一般的なオーバーライドのシナリオ：

• 重大なセキュリティパッチ：インフラストラクチャを保護するため、直ちに適用する必要がある緊急の脆弱性修正です。
• サポート終了（EoS）／ライフサイクル終了（EOL）の適用：クラスターがサポート対象外のバージョンを実行している場合、GKE はサポート対象のバージョンに強制的にアップグレードします。
• 証明書の有効期限切れ：制御プレーンの証明書（CA）の有効期限が切れる（30 日以内）場合に、クラスターが復旧不能になるのを防ぐため、ローテーションが必要です。
• メンテナンスの長期未実施：GKE では、連続する 92 日間の任意の期間内に、少なくとも 48 時間のメンテナンス可能時間が必要です。除外期間が長すぎる場合、GKE がアップグレードを強制することがあります。

ガイダンス（オーバーライドについて説明する際は必ず従ってください）：

1. 箇条書きの情報と照合する：GKE が予期しないアップグレードを実施した場合、その事象と緊急パッチとの関連を確認するため、GKE のリリースノートまたはセキュリティ速報を確認するよう、必ず明示的に提案してください（Cloud Audit Logs の確認を提案するだけでは不十分です）。
2. レジリエンスを考慮した設計にする：ワークロードは、予期しない制御プレーンやノードのローテーションに耐えられるよう設計する必要があります。以下を必ず推奨してください：
   • 制御プレーンのアップグレード中も API を利用できるよう、リージョンクラスター（複数のマスター）。
   • 複数のゾーンにまたがるワークロードのデプロイ。
   • 重要なデプロイではレプリカ数を 1 より大きくする。
   • 制限が厳しすぎないよう適切に設定した Pod Disruption Budget（PDB）。

アップグレードの計画

アップグレードの計画を求められた場合は、以下を網羅する構造化されたドキュメントを作成してください。

• バージョンの互換性（破壊的変更、非推奨 API）（マイナーバージョンのアップグレードのみ）
• アップグレードパス（マイナーバージョンを順番にアップグレード）（マイナーバージョンのアップグレードのみ）
• ノードプールのアップグレード戦略（Standard のみ）
• ワークロードの準備状況（PDB、リソースリクエスト）
• ロールバック／緊急時対応手順（ノードプールを元に戻す方法、またはマスターのロールバックについて GKE サポートと調整する方法）

互換性の確認ルール：

• 互換性情報（例：サードパーティーのオペレーターとの互換性、GPU ドライバー／CUDA の互換性マトリックス）が、ワークスペース内または簡単なウェブ検索で直ちに見つからない場合、検索を繰り返したり、複数回検索したりしないでください。代わりに、チェックリストに互換性確認をアップグレード前に必ず実施する重要なアクション項目として記載してください。

ノードプール戦略（Standard のみ）

デフォルトかつ最も一般的な戦略として、プールごとに以下の設定を指定したサージアップグレードを推奨してください。

• ステートレス：速度を優先して maxSurge を大きく（2～3）し、安全性を確保するため maxUnavailable=0 にします。
• ステートフル／DB：保守的な設定として maxSurge=1, maxUnavailable=0 にします。
• GPU（予約数固定）：サージ用のキャパシティがないため、maxSurge=0, maxUnavailable=1 にします。
• 大規模（50+ ノード）：並列処理を最大化するため、maxSurge=20, maxUnavailable=0 にします。

迅速なロールバックや厳格な検証が必要なミッションクリティカルなワークロードには、Standard Blue-Green アップグレードを推奨してください。中断に敏感なワークロードには、Autoscaled Blue-Green も選択肢であることを示してください。ただし、現在はプレビュー段階であり、キャパシティ要件がある可能性に注意してください。

**アップグレードの順序（ユーザーが開始する場合のみ）：**手動アップグレードを計画する際は、ノードプールをアップグレードする順序を指定してください。ステートレスプールを先にアップグレードし、クラスターの安定性を確認してから、ステートフル／GPU プールをアップグレードすることを推奨してください。自動アップグレードでは、GKE がノードプールの順次アップグレードを自動的に管理します。

標準的なコマンドシーケンスとランブックのテンプレートについては、references/runbook-template.mdを参照してください。

大規模 AI/ML クラスター（GPU/TPU）

GPU/TPU のアップグレードを案内する際は、次のすべてを必ず説明してください。

• ライブマイグレーション非対応：GPU VM はライブマイグレーションに対応していないため、GKE のアップグレードではポッドが強制的に再起動されます。このことをユーザーに説明してください。
• 固定予約とクォータ：H100/A100 では通常、固定予約が使われ、余剰のクォータはありません。アップグレード対象のノードの予約を解放してから置き換えノードをプロビジョニングする、サージなしのローリングアップグレード（maxSurge=0, maxUnavailable=1）を推奨してください。この場合、移行中に GPU リソース（クォータと予約の両方）を 2 倍必要とするため、ブルーグリーンアップグレードは実行できないことを説明してください。
• ドライバーの依存関係：GPU ドライバーはノードの OS イメージと密接に結び付いているため、ノードのアップグレードで新しい Linux カーネルと NVIDIA ドライバーが導入され、CUDA との互換性が損なわれる可能性があります。まずステージング環境／クラスターでアップグレードして CUDA との互換性をテストし、再度アップグレードを試みる前に、ワークロードの依存関係（コンテナーイメージ内の CUDA バージョン）を新しいドライバーに合わせて更新するよう勧めてください。ドライバーのリグレッションを診断するには、旧（正常動作）ノードと新（非動作）ノードの OS イメージ、カーネルバージョン（uname -r）、ドライバーのバージョンを比較し、テスト用ポッド（例：ベクトル加算）をデプロイして GPU にアクセスできることを確認してください。本番環境が停止している場合は、ノードプールを以前のバージョンにロールバックするのが最も迅速な緩和策です。
• 運用上の安全性：トレーニングキャンペーンの実施中に自動アップグレードが行われないよう、GKE のメンテナンス除外を推奨してください。手動アップグレードの前に GPU ノードをコルドンし、実行中のトレーニングジョブがチェックポイントを保存するか完了するまで待ってください。
• TPU に関する考慮事項：TPU スライスはローリング方式ではなく、全体が一括で再作成されます。1 つのスライスのメンテナンスで、環境内のすべてのスライスが再起動されます。

チェックリスト

チェックボックス付きの、コピー可能な Markdown 形式でチェックリストを作成してください。アップグレード前とアップグレード後のチェックリストテンプレートについては、references/checklists.md を参照してください。ユーザーの環境に合わせて調整してください。

ステートフルワークロード： ステートフルワークロード（データベース）がある場合は、アップグレード前のチェックリストに PV のバックアップ完了確認と、PV の回収ポリシー（例：Retain と Delete）の検証を必ず含めてください。

Autopilot のチェックリスト： Autopilot クラスターの場合は、チェックリストに以下を必ず含めてください。

• すべてのコンテナーでの resources.requests の設定確認（Autopilot の要件）。
• API の非推奨項目を確認するため、次の具体的な kubectl コマンドを必ず含めてください：kubectl get --raw /metrics | grep apiserver_request_total | grep deprecated。これにより、非推奨 API を使用している稼働中のワークロードがないか確認します。
• PDB がノードのドレインを妨げないことの確認（GKE がノードを管理している場合でも、PDB は引き続き適用されます）。
• 「ベアポッド」（ReplicaSet／Deployment／StatefulSet によって管理されていないポッド）の特定と削除。これらはノードの再作成時に再スケジュールされないためです。
• ノードの再作成時にポッドが安全にシャットダウンするための十分な時間を確保できるよう、terminationGracePeriodSeconds を確認します。

メンテナンス手順書

実際の gcloud および kubectl コマンドを含む、手順ごとのランブックを作成してください。標準的なコマンド手順については、references/runbook-template.md を参照してください。

安全制御を緩和するランブックでは、同じランブック内で必ず元に戻してください。 特にノードプールの移行またはロールバック中の PDB に適用されます。ドレインの前に PDB をバックアップし、再適用を独自の検証手順を含む番号付きの手順として記載してください。締めくくりの注意書きだけにしてはいけません。ドレインを妨げないよう maxUnavailable: 100% に変更したまま元に戻さないランブックでは、クラスターが中断保護なしの状態になります。その影響に気付くのは、次回の任意のエビクションが発生したときです。同じルールは、手順を進めるために追加したメンテナンス除外、コルドン、自動スケーラーの minNodes オーバーライドにも適用されます。

メンテナンス時間帯による一時停止

「停止している」アップグレードを診断するときは、メンテナンス時間帯によって一時停止されていないか確認してください。

• 通知のない一時停止動作： アップグレード（自動または手動）の完了前にメンテナンス時間帯が終了すると、GKE は許可された時間帯以外での中断を防ぐため、意図的にロールアウトを一時停止します。
• 混在バージョン状態： クラスターは安定した混在バージョン状態（アップグレード済みのノードと未アップグレードのノードが混在した状態）になります。これはサポートされている、安全で意図された結果であることを必ず明示してください。
• 再開： 次のメンテナンス時間帯が始まると、アップグレードは自動的に再開されます。
• すぐに完了させるための緩和策： ユーザーがすぐにアップグレードを完了したい場合は、現在時刻を含むようにメンテナンス時間帯を一時的に延長することを必ず提案してください（例：gcloud container clusters update ... --maintenance-window-start ... --maintenance-window-duration ... を使用）。手動アップグレードの再実行や、メンテナンス時間帯の迂回は提案しないでください。

トラブルシューティング

ユーザーからアップグレードが停止または失敗していると報告された場合、最終回答では考えられる5つの原因すべてを体系的に分析し、対処する必要があります。主な原因と思われるものがあっても、確認項目を省略しないでください。

1. PDB によるドレインのブロック： kubectl get pdb -A を使用して、ALLOWED DISRUPTIONS = 0 の PDB があるか特定します。
2. リソースの制約： 容量不足によりポッドが Pending の状態になっていないか確認します。
3. ベアポッド： ドレインを妨げているオーナー参照のないポッドを特定します（削除を推奨してください）。
4. アドミッションウェブフック： Validating／Mutating ウェブフックが、新しいノードでのポッド作成を拒否していないか確認します。
5. PVC のアタッチに関する問題： ボリュームのアタッチ失敗がないか確認します（特にゾーンの制約）。

在庫切れ／クォータ超過のルール：

• アップグレードが ZONE_RESOURCE_POOL_EXHAUSTED（在庫切れ）または Compute Engine リソースの QUOTA_EXCEEDED により停止している場合：
  1. クォータ制限を回避するため、アップグレード戦略を maxSurge=0（ローリング方式のインプレース更新）に変更することを推奨します。
  2. QUOTA_EXCEEDED の場合は、Google Cloud にクォータの増加を申請するよう提案します。
  3. 容量またはクォータに余裕のある別のゾーンやリージョンへワークロードを移行するか、新しいノードプールを作成することを、緩和策として必ず提案してください。

各手順の正確な診断コマンドと修正手順については、references/troubleshooting.md を参照してください。

参考資料

• GKE リリースノート
• GKE クラスターのアップグレード
• GKE アップグレードのトラブルシューティング
• アップグレード情報の取得（アップグレードアシスト）
• ノードプールのアップグレード戦略（サージ方式とブルーグリーン方式）
• メンテナンス時間帯と除外期間
• ロールアウトの順序付けに関する概念
• ロールアウトの順序付けの構成