部署機群套件

本頁說明如何使用 Config Sync 艦隊套件，在註冊至艦隊的叢集中部署 Kubernetes 資源。建立並部署機群套件後，當您將新叢集新增至機群時，機群套件會自動將 Git 存放區中的 Kubernetes 設定檔部署至新叢集。

FleetPackage 是一種宣告式 API，可將 Kubernetes 原始資訊清單部署至叢集群組。如要使用機群套件部署任何 Kubernetes 資源，必須已完成水合 (WET)。

事前準備

  1. 建立或確保您有權存取 Git 存放區，其中包含要部署至機群的 Kubernetes 資源。

  2. 安裝並初始化 Google Cloud CLI，其中提供 gcloud 和 nomos 指令。如果您使用 Cloud Shell，Google Cloud CLI 會預先安裝。如果您先前已安裝 Google Cloud CLI，請執行 gcloud components update，取得最新版本。

  3. 啟用 Config Sync (anthosconfigmanagement) API 和 ConfigDelivery API：

    gcloud services enable anthosconfigmanagement.googleapis.com configdelivery.googleapis.com

  4. 設定預設位置：

    gcloud config set config_delivery/location us-central1

  5. 設定預設專案：

    gcloud config set project PROJECT_ID

    將 PROJECT_ID 替換為車隊主專案的專案 ID。

  6. 確認叢集已註冊至機群。

  7. 使用 Cloud Build 存放區建立與支援供應商的連線，例如 GitHub 或 GitLab。使用機群套件時，您只需要為要同步處理的每個存放區設定一次 Cloud Build。

查看叢集需求

在叢集上安裝 Config Sync 前，請先參閱叢集設定建議和需求。

準備環境

如要準備 Config Sync 機群套件的環境，請將必要的 IAM 角色授予註冊叢集的使用者。

安裝 Config Sync

您可以透過 Cloud de Confiance 控制台或 Google Cloud CLI 安裝 Config Sync。

控制台

如要安裝 Config Sync，所有叢集都必須註冊至機群。在 Cloud de Confiance 控制台中安裝 Config Sync 時，選取個別叢集會自動將這些叢集註冊至機群。

  1. 前往 Cloud de Confiance 控制台的「Features」(功能) 區段下「Config」(設定) 頁面。

    前往「設定」

  2. 按一下「安裝 Config Sync」。

  3. 在「Installation options」(安裝選項)下方，選取「Install Config Sync on entire fleet (recommended)」(在整個機群上安裝 Config Sync (建議))。

  4. 按一下「Install Config Sync」(安裝 Config Sync)。在「設定」分頁中，幾分鐘後，機群中叢集的「狀態」欄應會顯示「已啟用」。

gcloud

  1. 啟用 ConfigManagement 車隊功能：

    gcloud beta container fleet config-management enable

  2. 如要啟用 Config Sync，請建立名為 apply-spec.yaml 的檔案，並在當中加入下列內容：

    applySpecVersion: 1
spec:
  configSync:
    enabled: true

  3. 套用 apply-spec.yaml 檔案：

    gcloud beta container fleet config-management apply \
    --membership=MEMBERSHIP_NAME \
    --config=apply-spec.yaml

    將 MEMBERSHIP_NAME 替換為您註冊叢集時選擇的機群成員名稱。如要找出會員名稱，請執行 gcloud container fleet memberships list 指令。

為 Cloud Build 建立服務帳戶

機群套件會使用 Cloud Build 從 Git 存放區擷取 Kubernetes 資源，並部署至叢集。Cloud Build 需要具備執行這項工作的權限的服務帳戶。如要建立服務帳戶並授予必要權限，請完成下列步驟：

  1. 建立服務帳戶：

    gcloud iam service-accounts create "SERVICE_ACCOUNT_NAME"

    將 SERVICE_ACCOUNT_NAME 替換為服務帳戶的名稱。名稱必須是介於 6 至 30 個字元的英數字元 ID，例如 my-service-account。建立服務帳戶後，即無法變更名稱。

  2. 新增 Resource Bundle Publisher 角色的 IAM 政策繫結：

    gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com" \
   --role='roles/configdelivery.resourceBundlePublisher'

    如果系統出現提示，請選取「None」做為政策條件。

  3. 為「記錄檔寫入者」角色新增 IAM 政策繫結：

    gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com" \
   --role='roles/logging.logWriter'

    如果系統出現提示，請選取「None」做為政策條件。

  4. 新增 ArtifactRegistry Writer 角色的 IAM 政策繫結：

    gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com" \
   --role='roles/artifactregistry.writer'

    如果系統出現提示，請選取「None」做為政策條件。

建立機群套件

如要建立車隊套件，請定義指向存放 Kubernetes 資源的存放區的 FleetPackage 規格，並將該存放區連結至 Cloud Build。然後套用 FleetPackage，從 Git 擷取資源並部署至整個機群。

  1. 建立名為 fleetpackage-spec.yaml 的檔案，並在其中加入下列內容：

    resourceBundleSelector:
  cloudBuildRepository:
    name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
    tag: TAG
    serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com
    path: CONFIG_FILE_PATH
target:
  fleet:
    project: projects/PROJECT_ID
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS
# set the state to SUSPENDED to pause new rollouts
# set the state back to ACTIVE to resume rollouts
# state: SUSPENDED

    更改下列內容：

    • CONNECTION_NAME：您將 Git 主機連結至 Cloud Build 時選擇的名稱。如要查看專案中的所有 Cloud Build 連線，請執行 gcloud builds connections list，或在 Cloud de Confiance 控制台中開啟「Repositories」(存放區) 頁面：

      開啟「Repositories」(存放區) 頁面

    • REPOSITORY_NAME：存放區名稱。這必須與您設定 Cloud Build 連線時輸入的值相同。

    • TAG：存放區的 Git 標記。格式必須是完整的語意化版本，包含主版號、次版號和修正程式編號。舉例來說，v1.0.0 是有效標記，而 v1 或 v1.0 則是無效標記。

    • CONFIG_FILE_PATH：存放庫中 Kubernetes 資源的路徑。如果檔案位於存放區的根目錄，可以省略這個欄位。

    • MAX_CLUSTERS：一次部署 Kubernetes 資源的叢集數量上限。舉例來說，如果將此值設為 1，資源套件一次只會部署至一個叢集。

      如需可設定的所有欄位完整清單，請參閱 FleetPackage 參考說明文件。

  2. 建立機群套件：

    gcloud container fleet packages create FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

    將 FLEET_PACKAGE_NAME 替換為車隊套件推出作業的名稱。

  3. 確認機群套件是否已建立：

    gcloud container fleet packages list

    輸出內容會列出建構觸發條件的狀態。幾秒後，MESSAGE 欄位會更新，輸出內容類似如下：

    MESSAGES: Build status: WORKING. The release is still being built; see the build status on the following page:

    您可以按一下提供的連結，查看 Cloud Build 工作的串流記錄。 Cloud Build 處理建構觸發程序可能需要幾分鐘的時間。

    如果建構觸發程序成功，機群套件就會開始在機群中推出 Kubernetes 資源。

  4. 建構觸發程序成功完成後，gcloud container fleet packages list 的輸出內容會類似於下列內容：

    NAME               STATE   CREATE_TIME           ACTIVE_ROLLOUT            LAST_COMPLETED_ROLLOUT  MESSAGES
my-fleet-package   ACTIVE  2024-07-09T15:15:56   rollout-20240709-153621

    機群套件會開始在機群中推出 Kubernetes 資源。

部署機群套件後，只要將新叢集新增至機群，系統就會自動將機群套件中定義的 Kubernetes 資源部署至新叢集。

更新機群套件

您可以更新機群套件，變更設定或機群套件部署的資源，例如：

  • 變更 maxConcurrent 欄位的值，即可變更推出策略。
  • 設定 state: SUSPENDED 即可暫時暫停車隊套件。車隊套件暫停後，任何進行中的發布作業都會繼續。除非將狀態改回 ACTIVE，否則系統不會建立或排定新的推出作業。
  • 如要更新機群套件部署的 Kubernetes 資源，請更新 tag 欄位，從其他 Git 標記提取資源。

如要更新車隊套件，請完成下列步驟：

  1. 使用變更更新 FleetPackage 規格。

  2. 更新機群套件：

    gcloud container fleet packages update FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

    系統可能需要幾分鐘才會接收到變更，並開始推出至叢集。

管理機群套件推出作業

您可以監控機群套件部署作業的進度，以及管理進行中的推出作業。如果車隊套件有變更，系統會自動建立新的推出作業。下列指令可協助您取得推出作業的詳細資訊。舉例來說，如要偵錯部署作業問題，可以檢查推出詳細資料，並視需要暫停或取消推出作業。

  1. 列出推出作業後，您就能查看與套件相關的所有推出作業狀態，包括可能導致推出作業失敗的錯誤。如要列出發布作業並查看狀態，請執行下列指令：

    gcloud container fleet packages rollouts list --fleet-package FLEET_PACKAGE_NAME

    輸出結果會與下列內容相似：

    ROLLOUT                   RELEASE  START_TIME              END_TIME                STATE     MESSAGE
rollout-20250515-132857   v2-0-0   2025-05-15T13:28:58Z                            STALLED
rollout-20250418-165528   v1-0-0   2025-04-18T16:55:29Z    2025-04-18T16:57:47Z    COMPLETED

  2. 描述推出作業可提供特定推出作業的詳細資訊，包括每個目標叢集的狀態和任何叢集專屬錯誤。如要說明發布作業，請執行下列指令：

    gcloud container fleet packages rollouts describe ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME

    將 ROLLOUT_NAME 替換為推出作業的名稱。您可以從上一個步驟的 list 指令取得完整推出名稱。

    輸出結果會與下列內容相似：

    CLUSTER    CURRENT_VERSION  SYNC_STATE  DESIRED_VERSION  START_TIME              END_TIME                STATE      MESSAGES
cluster1   v2.0.0           SYNCED      v2.0.0           2025-05-15T13:28:58Z    2025-05-15T13:30:27Z    COMPLETED
cluster2   v1.0.0           SYNCED      v2.0.0           2025-05-15T13:30:27Z                            ERROR      Membership no longer exists

  3. 您可以執行下列指令來管理進行中的推行作業：

    • 暫停發布後，系統會將進行中的發布作業設為 SUSPENDED 狀態。 系統會繼續執行任何進行中的套件更新，但不會排定後續的套件更新。如要暫停推出作業，請執行下列指令：

      gcloud container fleet packages rollouts suspend ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME

    • 恢復發布後，SUSPENDED發布作業會變回 IN_PROGRESS狀態。系統會按照計畫將套件更新部署至目標叢集。如要繼續推出，請執行下列指令：

      gcloud container fleet packages rollouts resume ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME

    • 取消進行中的推出作業後，系統會立即終止作業，並將其設為 ABORTED 狀態。系統會取消所有預計在推出作業中進行的待處理套件更新。如要取消推出作業，請執行下列指令：

      gcloud container fleet packages rollouts abort ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME

使用標籤部署至不同叢集

標籤是附加至物件的鍵/值組合，機群套件僅支援機群成員標籤。系統不支援 GKE 叢集標籤。

您可以使用標籤，將機群套件部署至機群中的部分叢集。

新增會員標籤

如要新增會員標籤，請完成下列步驟：

  1. 取得車隊中的會籍清單：

    gcloud container fleet memberships list

  2. 為會員方案加上標籤：

    gcloud container fleet memberships update MEMBERSHIP_NAME \
    --update-labels=KEY=VALUE

    更改下列內容：

    • MEMBERSHIP_NAME：註冊至機群的叢集名稱。
    • KEY 和 VALUE：要新增至會員方案的標籤。如果標籤存在，系統會修改其值。否則系統會建立新標籤。鍵的開頭須為小寫字元，且只能包含連字號 (-)、底線 (_)、小寫字元和數字。值只能包含連字號 (-)、底線 (_)、小寫字元和數字。

    針對要新增標籤的每個會員方案重複執行這項指令。

部署至叢集子集

您可以指定含有鍵/值組合的 target.fleet.selector.matchLabels 欄位，將部署作業發布至部分叢集。舉例來說，如果您將 matchLabels 設為 country: "us"，機群套件服務只會將資源部署到標籤為 country 且符合 "us" 的叢集。

如要將車隊套件部署至部分叢集，請完成下列步驟：

  1. 使用標籤選取器建立或更新 FleetPackage 規格：

    resourceBundleSelector:
  cloudBuildRepository:
    name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
    tag: TAG
    serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com
    path: CONFIG_FILE_PATH
target:
  fleet:
    project: projects/PROJECT_ID
    selector:
      matchLabels:
        KEY: "VALUE"
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS

  2. 建立或更新機群套件：

    建立機群套件

    gcloud container fleet packages create FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

    更新機群套件

    gcloud container fleet packages update FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

將變體資源部署至叢集

變化版本是資源的不同版本。這些資源的值可能因叢集的位置、專案或名稱而異。您可以指定 variantsPattern 和 variantNameTemplate 欄位，將變體資源部署至不同叢集。

你可以使用成員標籤或其他成員中繼資料 (例如位置、專案或名稱) 來比對變體。

如要部署含有變體的車隊套件，請完成下列步驟：

  1. 使用子類詳細資料建立或更新 FleetPackage 規格：

    resourceBundleSelector:
  cloudBuildRepository:
    name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
    tag: TAG
    serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com
    path: CONFIG_FILE_PATH
    variantsPattern: VARIANT_PATTERN
target:
  fleet:
    project: projects/PROJECT_ID
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS
target:
  fleet:
    project: projects/PROJECT_ID
 variantSelector:
  variantNameTemplate: VARIANT_NAME_TEMPLATE

    更改下列內容：

    • VARIANT_PATTERN：變體的模式，例如 "variants/*.yaml" 或 "us-*"。
    • VARIANT_NAME_TEMPLATE ：範本字串，可指含叢集成員資格中繼資料的變數，例如位置、專案、名稱或標籤，用於判定目標叢集的變化版本名稱。如需更多範例，請參閱FleetPackage參考說明文件。

  2. 建立或更新機群套件：

    建立機群套件

    gcloud container fleet packages create FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

    更新機群套件

    gcloud container fleet packages update FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

刪除機群套件

刪除機群套件時，系統也會一併刪除下列資源：

  • 部署在叢集上的 Kubernetes 資源
  • 機群套件推出記錄

如要刪除車隊套件，請執行下列指令：

gcloud container fleet packages delete FLEET_PACKAGE_NAME --force

疑難排解

如要瞭解如何診斷及解決 Cloud Build 相關錯誤，請參閱「排解建構錯誤」。

後續步驟