カスタム ステージを使用してクラスタのアップグレードのロールアウトを順序付ける

Autopilot Standard

Rollout sequencing with custom stages

• カスタム ステージを使用したロールアウト シーケンス（プレビュー）
• ロールアウト シーケンス（一般提供）

プレビュー版

この機能は サービス固有の規約の対象となります。 一般提供前の機能は「現状のまま」で提供されるものであり、サポートが制限されることがあります。 詳細については、リリース ステージの説明をご覧ください。

このドキュメントでは、カスタム ステージでロールアウト シーケンスを使用する Google Kubernetes Engine（GKE）クラスタのアップグレードを管理する方法について説明します。ロールアウト シーケンスは、フリートに編成されたクラスタのグループと、必要に応じて、それらのフリートのクラスタのサブセットを使用して作成します。1 つのグループ内でクラスタのアップグレードが完了した後のソークテスト時間（最大 30 日）を選択できます。これには Autopilot クラスタと Standard クラスタの両方を含めることができます。この機能の仕組みの詳細については、カスタム ステージを使用したロールアウト シーケンスについてをご覧ください。

複数のフリートにわたってロールアウトを管理する場合は、専用のプロジェクトを使用して RolloutSequence オブジェクトをホストすることをおすすめします。このプロジェクトは、シーケンス全体のロールアウトの親とコーディネーターとして機能します。通常、このプロジェクトはシーケンスの一部ではありません。つまり、このプロジェクトにはシーケンスの一部であるフリートやクラスタは含まれていません。

始める前に

• Google Cloud CLI をインストールします。 インストール後、次のコマンドを実行して Google Cloud CLI を初期化します。

  gcloud init

  外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

  注: すでに gcloud CLI をインストールしている場合は、gcloud components update を実行して、最新バージョンがインストールされていることを確認してください。
• 既存の Autopilot クラスタまたは Standard クラスタがあることを確認します。新しいクラスタを作成するには、Autopilot クラスタの作成をご覧ください。

• （省略可）RolloutSequence 構成をホストする専用の Google Cloud プロジェクトがまだない場合は、 Google Cloud コンソールまたは別の方法を使用して作成します。

• フリートに必要な API が有効になっていることを確認します。あらゆる種類のロールアウト シーケンスを作成するには、フリート ホスト プロジェクトでこれらの API を有効にする必要があります。ロールアウト シーケンスのホスト プロジェクトで、gkehub.googleapis.com API を有効にします。

必要なロール

プロジェクトを作成するには、resourcemanager.projects.create 権限を含むプロジェクト作成者のロール（roles/resourcemanager.projectCreator）が必要です。ロールを付与する方法を確認する。

ロールアウト シーケンスを作成または変更するには、ロールアウト シーケンス内の各フリート ホスト プロジェクトとロールアウト シーケンス ホスト プロジェクトに対するフリート編集者 IAM ロール（roles/gkehub.editor）が必要です。このロールには次の権限が付与されます。

• gkehub.rolloutsequences.create
• gkehub.rolloutsequences.get
• gkehub.rolloutsequences.list
• gkehub.rolloutsequences.update
• gkehub.rolloutsequences.delete
• gkehub.fleet.get

これらの権限により、RolloutSequence オブジェクトの作成、アクセス、変更と、ロールアウト シーケンスでのフリートの使用が可能になります。

クラスタをフリートに登録または登録解除するには、次のすべての権限が必要です。

• フリート ホスト プロジェクトのクラスタ登録権限。
• 登録する GKE クラスタに対するクラスタ管理者権限。
• 別のプロジェクトのフリートに GKE クラスタを登録するためのプロジェクト間のクラスタ登録権限。

さまざまなタスクに必要な最小権限の IAM ロールについては、Gemini アシスタンスを使用して事前定義ロールの候補を取得するをご覧ください。

ロールアウト シーケンスを構成する

ロールアウト シーケンスを作成するには、クラスタをフリートのグループに編成する必要があります。Kubernetes ラベルを使用して、フリート内のクラスタの特定のサブセットをターゲットにできるきめ細かいステージを作成することもできます。クラスタの編成方法については、コミュニティ バンクの例をご覧ください。クラスタをグループに整理し、必要に応じてラベルを付けた後、ステージの順序付きリストと各グループのソーク時間を定義して、ロールアウト シーケンスを作成します。

クラスタをフリートに編成する

ロールアウト シーケンスでは、すべてのクラスタを同じリリース チャンネルに登録することをおすすめします。クラスタが同じチャンネルに登録されていない場合、GKE はシーケンス内の最も保守的なチャンネルからバージョンを選択します。たとえば、クラスタが Stable チャンネルと Regular チャンネルの両方に登録されている場合、GKE は Stable チャンネルのバージョンを選択します。また、同じ自動アップグレード ターゲット バージョンの対象となるように、すべてのクラスタで同じマイナー バージョンを実行することをおすすめします。

すでにクラスタをフリートに編成している場合は、次の手順をスキップして、クラスタのサブセットを作成するセクションに進むことができます。

1. クラスタをフリートにグループ化します。テスト、ステージング、本番環境などのデプロイ環境ごとにクラスタを編成できます（推奨）。
2. 選択したグループ化に基づいて、各クラスタをフリートに登録します。

クラスタのサブセットを作成する（省略可）

ロールアウト シーケンスのステージで特定のクラスタをターゲットにするには、それらのクラスタにラベルを付ける必要があります。

たとえば、完全なロールアウトの前にクラスタの小さなサブセットで新しいバージョンをテストするには、これらのクラスタに canary ラベルを適用します。Google Cloud CLI を使用して値 true の canary ラベルをクラスタに追加するには、次のコマンドを実行します。

gcloud container clusters update CLUSTER_NAME \
    --location=CLUSTER_LOCATION\
    --update-labels=canary=true

次のように置き換えます。

• CLUSTER_NAME: 既存のクラスタの名前。
• CLUSTER_LOCATION: クラスタの Compute Engine のリージョンまたはゾーン。

--update-labels=canary=true フラグを指定すると、GKE はクラスタに canary ラベルを適用します。

警告: クラスタのラベルを更新すると、クラスタの既存のラベルが上書きされます。クラスタの既存のラベルを保持する場合は、クラスタの更新時に、追加する新しいラベルとともに既存のラベルを含める必要があります。

クラスタにラベルを追加する方法については、既存のクラスタのラベルを追加または更新するをご覧ください。

カスタム ステージを含むロールアウト シーケンスを作成する

ロールアウト シーケンスは、ステージを使用してアップグレードの順序を定義します。ロールアウト シーケンスを作成するには、まずステージを定義する YAML ファイルを作成し、次に RolloutSequence を作成する必要があります。

シーケンスがすべてのクラスタをキャプチャするようにするには、各フリートにキャッチオール ステージ（ラベル セレクタのないステージ）を含める必要があります。このキャッチオール ステージでは、前のステージで GKE が選択しなかった残りのすべてのクラスタがキャプチャされます。1 つの RolloutSequence 内の複数のステージに 1 つのクラスタを割り当てると、競合を解決するために、GKE はクラスタを最も早いステージにのみ暗黙的に割り当てます。

重要: YAML 構成ファイルでは、ソーク時間は秒単位で表す必要があります。

次の構成例では、3 つのステージを作成します。

• 最初のステージは、dev フリート内のすべてのクラスタを対象としています。アップグレードが完了すると、7 日間（604800 秒）の浸漬期間があります。
• 第 2 段階では、ラベル canary=true が付いている prod フリート内のクラスタをターゲットにします。アップグレードが完了すると、7 日間のソーク期間があります。
• 第 3 段階では、prod フリート内の残りのクラスタをターゲットにします。アップグレードが完了すると、7 日間のソーク期間があります。

1. 次のマニフェストを rollout-sequence.yaml として保存します。

   - stage:
     fleet-projects:
     - projects/dev
     soak-duration: 604800s
   - stage:
     fleet-projects:
     - projects/prod
     soak-duration: 604800s
     label-selector: resource.labels.canary=='true'
   - stage:
     fleet-projects:
     - projects/prod
     soak-duration: 604800s
   

   次の点にご注意ください。

   • stage: フリートまたはフリート内のクラスタのサブセットが含まれます。前のステージのクラスタは、シーケンスが次のステージに進む前に、完全にアップグレードしてソークする必要があります。ただし、アップグレード プロセスの開始から 30 日後にクラスタのアップグレードが完了していない場合、GKE はソーク期間を開始します。
   • fleet-projects: このステージのクラスタを選択するフリートのリスト。ステージごとに参照できるフリートは 1 つまでです。フリートは、フリートがホストされているプロジェクトによって識別されます。フリートにプロジェクト間のメンバーシップが含まれている場合、このプロジェクトはクラスタが存在するプロジェクトとは異なるプロジェクトにできます。フリート プロジェクトを指定する形式は projects/PROJECT_ID です。
   • label-selector（省略可）: 指定されたフリートからクラスタのサブセットを選択します。このフィールドでは Common Expression Language（CEL）構文を使用し、resource.labels で始める必要があります。
   • soak-duration: 前のステージのすべてのクラスタをアップグレードしてから次のステージに進むまでの待機時間。秒単位で表されます。

2. rollout-sequence.yaml マニフェストで定義したロールアウト シーケンスを作成するには、次のコマンドを実行します。

   gcloud beta container fleet rolloutsequences create ROLLOUT_SEQUENCE_NAME \
       --display-name=DISPLAY_NAME \
       --stage-config=rollout-sequence.yaml
   

   次のように置き換えます。

   • ROLLOUT_SEQUENCE_NAME: RFC-1034 仕様に準拠する不変の識別子（例: test-rollout-sequence）。
   • DISPLAY_NAME: ロールアウト シーケンスの人が読める形式の文字列。

ロールアウトのステータスを確認する

ロールアウト シーケンスを構成すると、アップグレードを管理するために Rollout オブジェクトが自動的に作成されます。これらのオブジェクトの進行状況は、Google Cloud CLI コマンドを使用してモニタリングおよび追跡できます。

ロールアウトを一覧表示する

ロールアウト シーケンス ホスト プロジェクトのアクティブなロールアウトと過去のロールアウトをすべて一覧表示するには、次のコマンドを実行します。

gcloud beta container fleet rollouts list --project=HOST_PROJECT_ID

HOST_PROJECT_ID は、ロールアウト シーケンス ホスト プロジェクトの ID に置き換えます。

ロールアウト シーケンスがホストされているプロジェクトにすでにいる場合は、--project=HOST_PROJECT_ID フラグを省略できます。

出力は次のようになります。

NAME                                              STATE      CREATE_TIME
05eb251e4f19269e23-node-1-33-5-gke-1201000-t7mqd  COMPLETED  2025-10-30T20:07:46
05eb251e4f19269e23-kcp-1-33-5-gke-1201000-djwst   COMPLETED  2025-10-30T18:07:06
05eb251e4f19269e23-node-1-33-5-gke-1125000-6bxvu  COMPLETED  2025-10-23T17:46:54
05eb251e4f19269e23-kcp-1-33-5-gke-1125000-2f6ct   RUNNING    2025-10-23T16:41:33

上記の出力で、kcp を含むロールアウト名はコントロール プレーンのアップグレードを指し、node を含む名前はノードのアップグレードを指します。kcp または node の後のロールアウト名のセグメントは、GKE バージョンから取得されます。

ロールアウトの説明を取得する

特定のロールアウトの詳細情報（ターゲット バージョン、状態、アップグレードされたクラスタなど）を取得するには、前のコマンドで取得したロールアウト ID を指定して describe コマンドを使用します。

gcloud beta container fleet rollouts describe ROLLOUT_ID \
  --project=HOST_PROJECT_ID

次のように置き換えます。

• ROLLOUT_ID: ロールアウトを一覧表示したときに取得したロールアウト ID。
• HOST_PROJECT_ID: ロールアウト シーケンスがホストされているプロジェクト ID。

次に例を示します。

gcloud beta container fleet rollouts describe 927e9a989930cf3b55-kcp-1-32-4-gke-1106006 \
  --project=my-hostfleet

出力は次のようになります。

createTime: '2025-05-26T11:47:29.909959672Z'
membershipStates:
  projects/dev-project-id/locations/us-central1/memberships/c-1:
    lastUpdateTime: '2025-05-26T12:20:55.601542481Z'
    targets:
    - cluster:   projects/dev-project-id/locations/us-central1/clusters/c-1
      operation: //container.googleapis.com/v1/projects/dev-project-id/locations/us-central1/operations/operation-1234567890-abcdefg-hijklm-nopqrst
      state: SUCCEEDED
    stageAssignment: 1
  projects/dev-project-id/locations/us-central1/memberships/c-2:
    lastUpdateTime: '2025-05-26T12:22:57.151203493Z'
    targets:
    - cluster:   projects/dev-project-id/locations/us-central1/clusters/c-2
      operation: //container.googleapis.com/v1/projects/dev-project-id/locations/us-central1/operations/operation-987654321-ghijkl-mno-pqr-stu-vwxyz
      state: SUCCEEDED
    stageAssignment: 1
  projects/prod-project-id/locations/us-central1/memberships/c-1:
    lastUpdateTime: '2025-05-26T13:03:34.134308942Z'
    targets:
    - cluster: projects/prod-project-id/locations/us-central1/clusters/c-1
      operation: //container.googleapis.com/v1/projects/prod-project-id/locations/us-central1/operations/operation-567891234-efghij-klm-nopq-rstu-vwxyz
      state: SUCCEEDED
    stageAssignment: 2
  projects/prod-project-id/locations/us-central1/memberships/c-2:
    lastUpdateTime: '2025-05-26T13:06:34.025261641Z'
    targets:
    - cluster: projects/prod-project-id/locations/us-central1/clusters/c-1
      operation: //container.googleapis.com/v1/projects/prod-project-id/locations/us-central1/operations/operation-765432198-01a7b896-67c2-523-6fjjh4-icmdydh
      state: SUCCEEDED
    stageAssignment: 2
name: projects/user-hostfleet/locations/global/rollouts/05eb251e4f19269e23-kcp-1-32-4-gke-1106006
rolloutSequence: projects/project-id/locations/global/rolloutSequences/my-sequence
state: COMPLETED
updateTime: '2025-07-22T07:36:51.052691989Z'
versionUpgrade:
  desiredVersion: 1.32.4-gke.1106006
  type: TYPE_CONTROL_PLANE
stages:
- state: COMPLETED
  endTime: '2025-05-26T12:22:28.828506491Z'
  stageNumber: 1
  startTime: '2025-05-26T11:48:28.772658427Z'
  soakDuration: 600s
- state: COMPLETED
  endTime: '2025-05-26T13:06:20.026390832Z'
  stageNumber: 2
  startTime: '2025-05-26T12:32:38.419372153Z'
  soakDuration: 600s

ロールアウトのステータス情報

ロールアウトを記述すると、出力の stages フィールドと membershipStates フィールドに、それぞれ各ステージの進行状況と、そのステージ内のクラスタの進行状況が示されます。

次の表に、ステージのステータスを示します。

ステータス	説明
PENDING	このステージのアップグレードはまだ開始されていません。
RUNNING	このステージのアップグレードが進行中です。ステージ内のクラスタにメンテナンスの時間枠を構成している場合、GKE は時間枠が開くまで待ってからクラスタをアップグレードします。
SOAKING	このステージのすべてのクラスタでアップグレードが完了し、ステージは構成されたソーキング期間に入っています。
FORCED_SOAKING	アップグレードに最長アップグレード時間（30 日間）を超える期間を要していたため、GKE はソークフェーズを強制的に開始しました。残りのクラスタではアップグレードが続行されます。
COMPLETED	ステージのソークが完了し、ロールアウトが次のステージに進みます。

次の表に、シーケンス内のクラスタのステータスを示します。

ステータス	説明
PENDING	このクラスタでアップグレードが保留中です。
INELIGIBLE	このクラスタは、バージョンの不一致などが原因で、アップグレードの対象外です。不適格の理由は出力に表示されます。
RUNNING	このクラスタでアップグレードが進行中です。
SUCCEEDED	このクラスタでアップグレードが正常に完了しました。
FAILED	このクラスタでアップグレードが失敗しました。失敗したターゲットは、ステージがアクティブな間（RUNNING または FORCED_SOAKING 状態）、無期限に再試行されます。

ロールアウト シーケンスを管理する

以下の各セクションで説明するように、ロールアウト シーケンスを使用してクラスタの自動アップグレードを制御する方法はいくつかあります。

ロールアウト シーケンスを一覧表示する

ホスト プロジェクトのすべてのロールアウト シーケンスを一覧表示するには、次のコマンドを実行します。

gcloud beta container fleet rolloutsequences list --project=HOST_PROJECT_ID

HOST_PROJECT_ID は、ロールアウト シーケンス ホスト プロジェクトの ID に置き換えます。

ロールアウト シーケンスについて説明する

特定のロールアウト シーケンスの詳細を表示するには、次のコマンドを実行します。

gcloud beta container fleet rolloutsequences describe ROLLOUT_SEQUENCE_NAME \
  --project=HOST_PROJECT_ID

次のように置き換えます。

• ROLLOUT_SEQUENCE_NAME: ロールアウト シーケンスの名前。
• HOST_PROJECT_ID: ロールアウト シーケンス ホスト プロジェクトの ID。

出力は次のようになります。

createTime: '2025-10-23T16:40:16.403871189Z'
displayName: my-display-name
name: projects/HOST_PROJECT_ID/locations/global/rolloutSequences/ROLLOUT_SEQUENCE_NAME
stages:
- clusterSelector:
    labelSelector: resource.labels.canary=='true'
  fleetProjects:
  - projects/FLEET_PROJECT_ID
  soakDuration: 600s
- fleetProjects:
  - projects/FLEET_PROJECT_ID
  soakDuration: 300s
uid: 5c5b2ac8-9d76-45f9-92ca-5e6bd3fbcaef
updateTime: '2025-10-23T17:11:57.285678399Z'

ロールアウト シーケンスを変更する

既存のロールアウト シーケンスを変更するには、シーケンスを定義した YAML 構成ファイルを編集します。たとえば、ステージの浸漬時間を更新したり、ステージを更新してアップグレードの順序を変更したりできます。ファイルを編集したら、変更を適用します。

たとえば、元のロールアウト シーケンスを rollout-sequence.yaml という名前のファイルで定義した場合は、必要に応じてファイルを編集します。次のコマンドを実行します。

gcloud beta container fleet rolloutsequences update test-rollout-sequence \
  --display-name="My Updated Rollout Sequence" \
  --stage-config=rollout-sequence.yaml

注意: 参加クラスタに影響する形で既存のロールアウト シーケンスを変更すると（ステージの順序を変更するなど）、GKE は既存のロールアウトをすべて直ちにキャンセルします。ステージのソーク時間のみを変更した場合、GKE はロールアウトをキャンセルしません。

ロールアウト シーケンスを削除する

ロールアウト シーケンスを削除するには、次のコマンドを実行します。

gcloud beta container fleet rolloutsequences delete ROLLOUT_SEQUENCE_NAME \
  --project=HOST_PROJECT_ID

次のように置き換えます。

• ROLLOUT_SEQUENCE_NAME は、ロールアウト シーケンスの名前に置き換えます。
• HOST_PROJECT_ID は、ロールアウト シーケンス ホスト プロジェクトの ID に置き換えます。

ロールアウト シーケンスを削除すると、そのシーケンスで進行中のロールアウトはすべてキャンセルされます。シーケンスの一部であったクラスタは、登録されているリリース チャンネルのデフォルトの自動アップグレード動作に戻ります。

カスタム ステージを使用するように既存のロールアウト シーケンスを移行する

ロールアウト シーケンスの一般提供版のフリートベースのバージョンを使用している場合は、既存のフリートを参照する新しい RolloutSequence を作成して、カスタム ステージを使用するシーケンスに移行できます。

シーケンスを移行する前に、現在のロールアウト シーケンス構成のコピーを作成することをおすすめします。

ロールアウト シーケンスを移行する手順は次のとおりです。

1. ロールアウト シーケンスをホストする専用の Google Cloud プロジェクトを作成します。通常、このプロジェクトはシーケンスの一部ではありません。つまり、このプロジェクトにはシーケンスの一部であるフリートやクラスタは含まれていません。
2. ロールアウト シーケンスにフリート内の特定のクラスタを含める場合は、それらのクラスタにラベルを追加します。この手順は省略可能です。

3. カスタム ステージでロールアウト シーケンスを作成するの手順に沿って操作します。

   たとえば、rollout-sequence-migrate.yaml という名前の次のマニフェストは、以前のロールアウト シーケンスの既存のフリートを参照しています。このマニフェストでは、prod フリートの canary ステージを含む 3 つのステージを記述しています。

   - stage:
     fleet-projects:
     - projects/dev
     soak-duration: 604800s
   - stage:
     fleet-projects:
     - projects/prod
     soak-duration: 604800s
     label-selector: canary=true
   - stage:
     fleet-projects:
     - projects/prod
     soak-duration: 604800s
   

フリートの新しい RolloutSequence を定義すると、GKE は新しいシーケンスに従ってフリートのアップグレードを開始し、以前の構成を削除します。

カスタム ステージを含むロールアウト シーケンスを以前のロールアウト シーケンスに移行する

このセクションでは、カスタム ステージを使用したロールアウト シーケンスから、一般提供のフリートベースのシーケンス モデルに戻す方法について説明します。このプロセスでは、新しい RolloutSequence を削除し、元のフリートベースの構成を復元します。

移行中の順序外アップグレードを防ぐ

シーケンスの再構成中に意図しないアップグレードや順序外のアップグレードが発生しないようにするには、本番環境クラスタにメンテナンスの除外を適用します。この手順では、これらのクラスタのすべての自動アップグレードが一時的に一時停止されます。たとえば、本番環境クラスタで no upgrades タイプのメンテナンス除外を構成できます。

ロールアウト シーケンスを削除する

クラスタを管理する RolloutSequence オブジェクトを削除します。この削除により、カスタム ステージ機能が無効になります。

RolloutSequence を削除するには、次のコマンドを実行します。

gcloud beta container fleet rolloutsequences delete ROLLOUT_SEQUENCE_NAME

ROLLOUT_SEQUENCE_NAME は、ロールアウト シーケンスの名前に置き換えます。

以前のロールアウト シーケンス構成（カスタム ステージなし）を復元する

RolloutSequence を削除すると、元のフリートベースの構成を復元できます。このプロセスでは、シーケンス内の各フリートの upstreamFleet リンクとソーク時間など、元のパラメータを使用して clusterupgrade 機能が再作成されます。詳細については、ロールアウト シーケンスを作成するをご覧ください。

メンテナンスの除外を削除する

元のフリートベースのロールアウト シーケンス構成を復元したら、このセクションの最初の手順で適用したメンテナンス除外を削除します。GKE は自動アップグレードを再開します。このアップグレードは、復元されたフリートベースのシーケンスによって管理されます。

次のステップ

• ロールアウト シーケンスを使用したクラスタのアップグレードの詳細を確認する。