透過自訂階段，依序推出叢集升級

自動駕駛 標準

Rollout sequencing with custom stages

• 使用自訂階段的推出作業排序功能 (預先發布版)
• 推出順序 (正式發布版)

預先發布版

這項功能 適用《服務專屬條款》。 正式發布前的功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

本文說明如何管理 Google Kubernetes Engine (GKE) 叢集升級作業，這類作業會使用自訂階段的推出作業序列。您可以透過叢集群組建立推出作業序列，這些叢集群組會整理成機群，也可以選擇性地從這些機群中選取叢集子集。您可以選擇叢集在群組中完成升級後，要進行多少時間的浸泡測試 (最多 30 天)。您可以同時加入 Autopilot 和 Standard 叢集。如要進一步瞭解這項功能的運作方式，請參閱「使用自訂階段推出序列」。

如果您管理多個車隊的推出作業，建議使用專案代管 RolloutSequence 物件。這個專案會做為父項，並協調整個序列的推出作業。這項專案通常不屬於序列，也就是說，專案不包含屬於序列的車隊或叢集。

事前準備

• 安裝 Google Cloud CLI。 完成後，執行下列指令來初始化 Google Cloud CLI：

  gcloud init

  若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

  注意：如果您先前已安裝 gcloud CLI，請執行 gcloud components update，確認目前使用的是最新版本。
• 請確認您已建立 Autopilot 或 Standard 叢集。如要建立新叢集，請參閱「建立 Autopilot 叢集」。

• (選用) 如果您還沒有專屬專案來代管設定，請使用主控台或其他方法建立專案。 Google Cloud RolloutSequence Google Cloud

• 確認已啟用車隊所需的 API。 您必須在機群主專案中啟用這些 API，才能建立任何類型的推出程序。為推出順序主專案啟用 gkehub.googleapis.com API。

必要的角色

如要建立專案，您需要具備專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

如要建立或修改推出作業序列，您必須在推出作業序列中的每個機群主機專案，以及推出作業序列主機專案中，具備機群編輯者 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 會從序列中最保守的發布版本中選取版本。舉例來說，如果叢集同時註冊了穩定版和一般版，GKE 會選擇穩定版的版本。此外，我們也建議所有叢集都執行相同的子版本，這樣才能符合相同的自動升級目標版本資格。

如果您已將叢集整理到機群中，可以略過下列步驟，直接前往「建立叢集子集」一節。

1. 將叢集分組到機群中。您可以依部署環境 (例如測試、預備和正式環境) 整理叢集 (建議)。
2. 根據所選分組，將每個叢集註冊至機群。

建立叢集子集 (選用)

如要讓推出程序中的階段指定特定叢集，請為這些叢集加上標籤。

舉例來說，如要在全面推出新版本前，先在部分叢集上測試，可以對這些叢集套用 canary 標籤。如要使用 Google Cloud CLI 將 canary 標籤新增至叢集，並將值設為 true，請執行下列指令：

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 在先前階段未選取的所有剩餘叢集。如果您在一個RolloutSequence內將單一叢集指派給多個階段，為解決衝突，GKE 只會將叢集隱含指派給最早的階段。

重要事項： 在 YAML 設定檔中，浸泡時間必須以秒為單位。

下列範例設定會建立三個階段：

• 第一階段的目標是 dev 機群中的所有叢集。升級完成後，會有 7 天的浸泡時間 (604800 秒)。
• 第二階段的目標是 prod 機群中具有 canary=true 標籤的叢集。升級完成後，會有 7 天的浸泡期。
• 第三階段的目標是 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：從中選取此階段叢集的車隊清單。每個階段最多可參照一個車隊。機群的識別依據是機群所在的專案。如果機群包含跨專案成員，這個專案可以與叢集所在的專案不同。指定機群專案的格式為 projects/PROJECT_ID。
   • label-selector (選用)：從指定的車隊中選取叢集子集。這個欄位使用一般運算語言 (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 規格的不變 ID，例如 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 版本。

說明推出作業

如要取得特定推出作業的詳細資訊，包括目標版本、狀態和已升級的叢集，請使用 describe 指令，並搭配您從前一個指令取得的推出作業 ID：

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 階段：

   - 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 後，您可以還原原始的機群設定。這個程序包括使用原始參數重新建立 clusterupgrade 功能，包括序列中每個車隊的 upstreamFleet 連結和浸泡時間。詳情請參閱「建立推出順序」。

移除排除的維護時間

還原原始的車隊式推出順序設定後，請移除您在本節第一個步驟中套用的維護排除條件。GKE 會繼續自動升級，但現在會依據還原的機群序列進行。

後續步驟

• 進一步瞭解運用推出作業排序功能升級叢集。