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

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

事前準備

• 安裝 Google Cloud CLI，然後 使用聯合身分登入 gcloud CLI。登入後，執行下列指令來初始化 Google Cloud CLI：

  gcloud init

• 請確認您已擁有 Autopilot 或 Standard 叢集。如要建立新叢集，請參閱「建立 Autopilot 叢集」。
• 選用：如果沒有專屬 Cloud de Confiance by S3NS 專案來代管 RolloutSequence 設定，請使用Cloud de Confiance 控制台或其他方法建立專案。每項專案只能建立一個 RolloutSequence 物件。
• 確認已啟用車隊所需的 API。 您必須在機群主專案中啟用這些 API，才能建立任何類型的推出順序。為推出順序主專案啟用 gkehub.googleapis.com API。

• 如需 Terraform 指令，請務必使用下列版本或更新版本的 google Terraform 供應商，視您要執行的動作而定：

  • 如要執行下列動作，必須使用 7.39.0 以上版本：
    • 建立推出作業序列
    • 修改推出作業序列
    • 選擇 GKE 在推出作業序列中執行的升級類型
    • 忽略推出作業序列中的叢集
  • 如要執行下列動作，必須使用 7.42.0 以上版本：
    • 將特定版本發布至發布序列

必要的角色

如要建立專案，您需要「專案建立者」角色 (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.update

這些權限可讓您建立、存取及修改 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 標籤。

如要進一步瞭解如何為叢集新增標籤，請參閱「為現有叢集新增或更新標籤」。

建立包含自訂階段的推出作業序列

透過自訂階段的推出作業序列，您可以宣告式地定義階段，進而定義升級順序。使用 gcloud CLI 時，您會使用 YAML 檔案；使用 Terraform 時，則會在設定中新增資源區塊。執行本節所述步驟時，您會建立 RolloutSequence。

為確保序列能擷取所有叢集，每個機群都必須包含「全包」階段 (沒有標籤選取器的階段)。這個階段會擷取 GKE 在先前階段未選取的所有剩餘叢集。如果您在一個階段內將單一叢集指派給多個階段 RolloutSequence，為解決衝突，GKE 會隱含地將 叢集指派給最早的階段。

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

• 第一階段的目標是 dev 機群中的所有叢集。升級完成後，會有 7 天的浸泡時間 (7d)。
• 第二階段的目標是 prod 機群中具有 canary=true 標籤的叢集。升級完成後，會有 7 天的浸泡時間 (7d)。

• 第三階段的目標是prod機群中的其餘叢集。 升級完成後，會有 7 天的浸泡時間 (7d)。

推出特定版本

您可以將特定版本納入發布順序。詳情請參閱「推出特定版本」。

您可以將版本推出至推出順序中的叢集控制層或節點。您可以獨立選擇要向控制層或節點推出哪些版本。

GKE 一次只能在一個階段中，分別向控制層或節點推出一個版本。如果現有的推出作業正在推出序列的第一階段執行，GKE 會根據您使用 gcloud CLI 或 Terraform 管理推出序列，執行下列動作：

• gcloud CLI：執行指令時，系統會顯示互動式提示，詢問是否要取消現有推出作業，並為您指定的版本建立推出作業。如果回答「是」，GKE 會取消現有的推出作業，並建立新的推出作業。如果沒有，GKE 會保留現有的推出作業，不會按照您在指令中要求的建立新作業。
• Terraform：如要更新 Terraform 設定，請按照下一節的說明操作。如果推出作業正在第一階段執行，GKE 會取消現有的推出作業。

在推出作業序列中，將版本推出至控制層

gcloud container fleet rolloutsequences upgrade ROLLOUT_SEQUENCE_NAME \
    --control-plane-version="CONTROL_PLANE_VERSION"

min_control_plane_version = "CONTROL_PLANE_VERSION"

在推出作業序列中，將版本推出至節點

gcloud container fleet rolloutsequences upgrade ROLLOUT_SEQUENCE_NAME \
    --node-version="NODE_VERSION"

min_node_version = "NODE_VERSION"

查看推出作業的狀態

設定推出順序後，系統會自動建立Rollout 物件來管理升級作業。您可以使用 Google Cloud CLI 指令觀察及追蹤這些物件的進度。

列出推出作業

如要列出推出序列主專案中的所有現有和過往推出作業，請執行下列指令：

gcloud 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 container fleet rollouts describe ROLLOUT_ID \
  --project=HOST_PROJECT_ID

更改下列內容：

• ROLLOUT_ID：列出推出作業時取得的推出作業 ID。
• HOST_PROJECT_ID：代管推出序列的專案 ID。

例如：

gcloud 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 欄位會分別提供每個階段的進度狀態，以及該階段內每個叢集的進度狀態。

下表列出階段的可能狀態：

下表列出序列中叢集的可能狀態：

管理推出作業

如要管理個別推出作業，請按照下列章節的說明操作。如要進一步瞭解如何管理推出作業及可執行的相關動作，請參閱「管理推出作業」。

如要管理整個推出作業序列，而不只是特定推出作業，請參閱下一節「管理推出作業序列」。

暫停推出作業

您可以暫停進行中的推出作業。如要進一步瞭解這項操作，請參閱「暫停推出」。

如要暫停推出作業，請執行下列指令：

gcloud container fleet rollouts pause ROLLOUT_ID

將 ROLLOUT_ID 替換為要暫停的推出作業 ID。如要取得推出作業序列中推出作業的推出作業 ID，請參閱「列出推出作業」。

繼續推出作業

如果推出作業暫停時間未超過 90 天，您可以繼續進行。如要進一步瞭解這項動作，請參閱「繼續推出版本」一文。

如要繼續暫停的推出作業，請執行下列指令：

gcloud container fleet rollouts resume ROLLOUT_ID

將 ROLLOUT_ID 替換為要繼續的推出作業 ID。如要取得推出序列中推出的推出 ID，請參閱「列出推出項目」。

取消推出作業

您可以取消推出作業，包括有效或已暫停的推出作業。您無法取消強制自動升級的推出作業。如要進一步瞭解如何取消推出作業，請參閱「取消推出作業」。

如要取消推出作業，請執行下列指令：

gcloud container fleet rollouts cancel ROLLOUT_ID

將 ROLLOUT_ID 替換為要取消的推出作業 ID。如要取得推出序列中推出的推出 ID，請參閱「列出推出項目」。

完成推出階段

如果準備好將升級作業推進至下一個階段，即可完成推出階段。如要進一步瞭解這項操作，請參閱「完成推出階段」。

如要完成推出階段，請執行下列指令：

gcloud container fleet rollouts force-complete-stage ROLLOUT_ID \
    --stage=STAGE

更改下列內容：

• ROLLOUT_ID：要完成階段的推出作業 ID。如要取得推出序列中推出的推出 ID，請參閱「列出推出項目」。
• STAGE：您要立即完成的階段。舉例來說，如要完成第二階段，請輸入 2。如要使用這項指令，階段必須處於執行或浸泡狀態。

在特定推出作業的推出順序中忽略叢集

如果您不希望叢集在進行中的推出作業中升級，可以讓 GKE 忽略推出作業序列中的叢集。不過，這項動作會從有效和日後推出作業的推出順序中移除叢集，而不只是有效推出作業。

如要執行這項動作，避免在進行中的推出作業中升級叢集，請參閱「在推出序列中忽略叢集」。

管理推出作業序列

您可以透過推出作業排序功能，以多種方式控管叢集自動升級作業，詳情請參閱下列章節。

如要管理推出作業序列中的單一推出作業，而非整個推出作業序列和所有推出作業，請參閱「管理推出作業」。

列出推出作業序列

如要列出主機專案中的推出順序，請執行下列指令：

gcloud container fleet rolloutsequences list --project=HOST_PROJECT_ID

將 HOST_PROJECT_ID 替換為推出序列主機專案的 ID。

說明推出作業序列

如要查看特定推出作業序列的詳細資料，請執行下列指令：

gcloud 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'

選擇 GKE 在推出作業序列中執行的升級類型

根據預設，GKE 會依序推出所有類型的叢集升級。您可以限制推出順序中的叢集升級範圍，只執行特定類型的升級。詳情請參閱「選擇 GKE 在推出作業序列中執行的升級類型」。

如要指定 GKE 在推出作業序列中執行的升級類型，請按照下列操作說明進行，具體取決於您管理推出作業序列的方式：

gcloud container fleet rolloutsequences update ROLLOUT_SEQUENCE_NAME \
    --auto-rollout-scope=TYPES_OF_UPGRADES

auto_upgrade_config {
  rollout_creation_scope {
    upgrade_types = [
      UPGRADE_TYPES
    ]
  }
}

修改推出作業序列

建立現有的推出順序後，您可以視需要修改。請按照下列操作說明修改推出作業序列，具體做法取決於您管理推出作業序列的方式。

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

忽略推出作業序列中的叢集

您可以讓 GKE 在推出作業序列中忽略叢集。您可以忽略發布序列中的一或多個叢集。詳情請參閱「在推出順序中忽略叢集」。

如要讓 GKE 在推出作業序列中忽略叢集，請按照下列步驟操作：

1. 為叢集新增標籤，讓 GKE 忽略該叢集，或使用現有標籤。舉例來說，您可以讓 GKE 忽略 status 等標籤，也可以在標籤具有特定值 (例如 status=quarantine) 時忽略該標籤。

2. 設定推出順序，忽略具有這個標籤的叢集。如要這樣做，請按照下列步驟操作，具體步驟取決於您管理推出順序的方式：

   gcloud

   執行下列指令：

   gcloud container fleet rolloutsequences update ROLLOUT_SEQUENCE_NAME \
       --ignored-clusters-selector="resource.labels.LABEL_TO_IGNORE"
   

   更改下列內容：

   • ROLLOUT_SEQUENCE_NAME：推出順序的名稱。
   • LABEL_TO_IGNORE：GKE 應在推出順序中忽略的叢集標籤名稱。

   Terraform

   如果您使用 Terraform 管理推出順序，請將下列欄位新增至用於建立推出順序的區塊。您可以將欄位新增至 stages 區塊以外的任何位置，這些區塊必須連續：

   ignored_clusters_selector {
     label_selector = "resource.labels.LABEL_TO_IGNORE"
   }
   

   將 LABEL_TO_IGNORE 替換為叢集的標籤名稱，GKE 應在推出順序中忽略這些叢集。

這些操作說明會設定 GKE，在推出作業順序中忽略一種標籤。如要忽略多個標籤，或建立更複雜的運算式，說明如何忽略含有特定標籤的叢集，可以使用 CEL 運算式語法將值傳遞至這個欄位。所有標籤都必須使用 resource.labels. 前置字元。

將叢集加回推出序列

如果您按照上一節的 GKE 說明忽略推出作業序列中的叢集，可以還原這項動作。如要讓 GKE 不再忽略叢集，請按照下列指示移除忽略選取器，具體做法取決於您管理推出作業順序的方式：

gcloud container fleet rolloutsequences update ROLLOUT_SEQUENCE_NAME \
    --clear-ignored-clusters-selector

或者，如果希望 GKE 不要忽略特定叢集，請從叢集移除標籤。

刪除推出作業序列

如要刪除推出作業序列，請執行下列指令：

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

更改下列內容：

• ROLLOUT_SEQUENCE_NAME，並替換為推出順序的名稱。
• 將 HOST_PROJECT_ID 換成推出序列主機專案的 ID。

刪除推出序列後，系統會取消該序列中所有進行中的推出作業。序列中的叢集會還原為註冊發布管道的預設自動升級行為。

將現有的推出作業順序遷移至自訂階段

如果您使用以車隊為基礎的推出順序版本，可以建立新的 RolloutSequence 參照現有車隊，藉此遷移至使用自訂階段的序列。請注意，這個版本的推出順序不支援 Cloud de Confiance 控制台。

如要遷移推出順序，請完成下列步驟：

1. 如有需要，您可以在遷移序列前，複製目前的發布序列設定。如要複製設定，請執行下列其中一項操作：

   • gcloud CLI：執行指令來檢查以車隊為基礎的推出程序狀態。儲存指令輸出內容。
   • Terraform：儲存 Terraform 設定。

   建議不要刪除以車隊為準的推出順序，這樣如有需要，就能輕鬆還原至先前的推出順序版本。如果同時存在這兩種推出作業，GKE 只會遵循自訂階段的推出作業，因此您不必刪除以車隊為準的推出作業順序。

2. 建立專屬 Cloud de Confiance by S3NS 專案來代管推出作業序列。這個專案通常不屬於序列，也就是說，專案不包含屬於序列的車隊或叢集。

3. 如要讓推出順序包含機群內的特定叢集，請為這些叢集新增標籤。本步驟為選擇性步驟。

4. 按照「建立含有自訂階段的推出作業序列」中的操作說明操作。

   舉例來說，下列名為 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 container fleet rolloutsequences delete ROLLOUT_SEQUENCE_NAME

將 ROLLOUT_SEQUENCE_NAME 替換為推出順序的名稱。

還原先前的推出順序設定 (不含自訂階段)

刪除 RolloutSequence 後，您可以還原原先的機群設定。這個程序需要使用原始參數重新建立 clusterupgrade 功能，包括序列中每個機群的 upstreamFleet 連結和浸泡時間。詳情請參閱「建立推出作業序列」。

移除維護作業排除時段

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

後續步驟

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