部署機群套件

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

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

事前準備

建立或確保您有權存取 Git 存放區，其中包含要部署至機群的 Kubernetes 資源。
安裝並初始化 Google Cloud CLI，其中提供 gcloud 和 nomos 指令。如果您使用 Cloud Shell，Google Cloud CLI 會預先安裝。如果您先前已安裝 Google Cloud CLI，請執行 gcloud components update 取得最新版本。

注意： 如果是現有的 gcloud CLI 安裝項目，請務必設定 compute/region 和 compute/zone 屬性。設定預設位置後，即可避免 gcloud CLI 發生下列錯誤： One of [--zone, --region] must be supplied: Please specify location。

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

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

設定預設位置：
```
gcloud config set config_delivery/location us-central1
```
注意： ConfigDelivery API 僅適用於 us-central1。
設定預設專案：
```
gcloud config set project PROJECT_ID
```
將 PROJECT_ID 替換為車隊主專案的專案 ID。
確認叢集已註冊至機群。
使用 Cloud Build 存放區建立與支援供應商的連線，例如 GitHub 或 GitLab。使用車隊套件時，您只需要為要同步處理的每個存放區設定一次 Cloud Build。

重要事項： Cloud Build 連線必須位於 us-central1，因為 Git 連線和 FleetPackage 必須位於相同區域。ConfigDelivery API 僅適用於 us-central1。

查看叢集需求

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

準備環境

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

安裝 Config Sync

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

控制台

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

前往 Google Cloud 控制台的「Features」(功能) 區段，然後點選「Config」(設定) 頁面。

前往「設定」

按一下「安裝 Config Sync」。
在「Installation options」(安裝選項)下方，選取「Install Config Sync on entire fleet (recommended)」(在整個機群上安裝 Config Sync (建議))。
按一下「Install Config Sync」(安裝 Config Sync)。在「設定」分頁中，幾分鐘後，機群中叢集的「狀態」欄應會顯示「已啟用」。

gcloud

啟用 ConfigManagement 車隊功能：

gcloud beta container fleet config-management enable

如要啟用 Config Sync，請建立名為 apply-spec.yaml 的檔案，並在當中加入下列內容：
```
applySpecVersion: 1
spec:
  configSync:
    enabled: true
```
套用 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 需要具備執行這項工作的權限的服務帳戶。如要建立服務帳戶並授予必要權限，請完成下列步驟：

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

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

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

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

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

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

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

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

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

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

建立機群套件

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

建立名為 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.iam.gserviceaccount.com
    path: CONFIG_FILE_PATH
    # Match all files and directories to generate variants
    variantsPattern: "*"
target:
  fleet:
    project: projects/PROJECT_ID
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS
variantSelector:
  variantNameTemplate: "VARIANT_NAME"
# 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，或在 Google Cloud 控制台中開啟「Repositories」(存放區) 頁面：
  
  開啟「Repositories」(存放區) 頁面
- REPOSITORY_NAME：存放區名稱。這必須與您設定 Cloud Build 連線時輸入的值相同。
- TAG：存放區的 Git 標記。格式必須是完整的語意化版本，包含主版號、次版號和修正程式編號。舉例來說，v1.0.0 是有效標記，但 v1 或 v1.0 是無效標記。
- CONFIG_FILE_PATH：存放庫中 Kubernetes 資源的路徑。如果檔案位於存放區的根目錄，可以省略這個欄位。
- MAX_CLUSTERS：一次部署 Kubernetes 資源的叢集數量上限。舉例來說，如果將此值設為 1，資源套件一次只會部署到一個叢集。
- VARIANT_NAME：要部署至叢集的變體。名稱必須與存放區中的變體相符 (不含副檔名的檔案名稱或目錄名稱)。舉例來說，如果您有名為 prod.yaml 的檔案，請將這個欄位設為 prod。如要使用預設行為 (例如將相同設定部署至機群中的所有叢集)，請將這個欄位設為 default，並確保存放區包含名為 default.yaml 的檔案。
  
  如需可設定的所有欄位完整清單，請參閱 FleetPackage 參考說明文件。

建立機群套件：

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

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

確認機群套件是否已建立：
```
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 資源。

建構觸發程序成功完成後，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，否則系統不會建立或排定新的推出作業。
更新 tag 欄位，從其他 Git 標記提取資料，即可更新機群套件部署的 Kubernetes 資源。

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

使用變更更新 FleetPackage 規格。

更新機群套件：

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

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

檢查資源套件和發行內容

根據 Git 存放區建立或更新車隊套件時，FleetPackages API 會自動建立資源套件和發布資源。檢查這些資源有助於排解問題，特別是需要驗證從存放區產生的變體時。

如要檢查資源套件和版本，請使用一或多個下列指令：

查看特定資源套件的詳細資訊：

gcloud container fleet packages resource-bundles describe flpkg-rb-FLEET_PACKAGE_NAME

列出與資源組合相關聯的所有發行內容：

gcloud container fleet packages resource-bundles releases list \
    --resource-bundle flpkg-rb-FLEET_PACKAGE_NAME

查看特定版本的詳細資訊，包括使用的資源套件。這項指令特別適合用來偵錯與變體相關的問題，因為您可以檢查特定版本中包含哪些變體：
```
gcloud container fleet packages resource-bundles releases describe RELEASE_NAME\
    --resource-bundle flpkg-rb-FLEET_PACKAGE_NAME
```

更改下列內容：

FLEET_PACKAGE_NAME：車隊套件的名稱。資源套件名稱會自動加上 flpkg-rb- 前置字串。
RELEASE_NAME：list指令輸出內容中的版本名稱。

管理機群套件推出作業

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

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

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

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

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

您可以執行下列指令來管理進行中的推行作業：
- 暫停發布後，系統會將進行中的發布作業設為 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
```

部署策略

您可以透過不同方式部署資源，例如指定標籤，將資源部署至部分叢集，或是使用變體模式比對，部署不同資源。您可以結合這兩種策略，進一步控管要將哪些資源部署至不同叢集。

部署至叢集子集

您可以透過標籤將相同資源部署至部分叢集，並使用標籤 (鍵/值組合) 指定 target.fleet.selector.matchLabels 欄位。舉例來說，如果您將 matchLabels 設為 country: "us"，車隊套件服務只會將資源部署到標籤為 country 且與 "us" 相符的叢集。

機群套件僅支援機群會員標籤。不支援 GKE 叢集標籤。

(選用) 如果您沒有要使用的標籤，請按照下列步驟新增：
1. 取得車隊中的會籍清單：
```
gcloud container fleet memberships list
```
2. 為會員方案加上標籤：
```
gcloud container fleet memberships update MEMBERSHIP_NAME \
    --update-labels=KEY=VALUE
```
  更改下列內容：
  - MEMBERSHIP_NAME：註冊至機群的叢集名稱。
  - KEY 和 VALUE：要新增至會員方案的標籤。如果標籤存在，系統會修改其值。否則系統會建立新標籤。鍵的開頭須為小寫字元，且只能包含連字號 (-)、底線 (_)、小寫字元和數字。值只能包含連字號 (-)、底線 (_)、小寫字元和數字。
  針對要新增標籤的每個會員方案重複執行這項指令。

使用標籤選取器建立或更新 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.iam.gserviceaccount.com
    path: CONFIG_FILE_PATH
target:
  fleet:
    project: projects/PROJECT_ID
    selector:
      matchLabels:
        KEY: "VALUE"
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS

建立或更新機群套件：

建立機群套件

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

更新機群套件

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

將變體資源部署至叢集

您可以在機群套件中加入變數定義，為不同叢集部署專屬設定 (例如 dev 與 prod)。

如要瞭解如何從存放區結構產生變數，請參閱「如何產生變數」一文。

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

建立或更新 FleetPackage 規格，加入 variantsPattern 和 variantNameTemplate 欄位：
```
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.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：從存放區產生變體的 glob 模式，例如 * (比對所有檔案和目錄) 或 *.yaml (只比對檔案)。如要進一步瞭解支援的模式，請參閱variantsPattern 比對。
- VARIANT_NAME_TEMPLATE ：字串或範本，用於選取每個叢集的變體。您可以使用 ${membership.labels['env']} 或 ${membership.location} 等中繼資料變數。
注意： 請確認 variantsPattern 生成的子類名稱不重複。如果兩個檔案對應到相同名稱 (例如 app1/deploy.yaml 和 app2/deploy.yaml 都解析為 deploy)，則可能因名稱衝突而導致推出作業失敗。

建立或更新機群套件：

建立機群套件

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 相關錯誤，請參閱「排解建構錯誤」。

後續步驟

請參閱 FleetPackage 欄位參考頁面

部署機群套件 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

查看叢集需求

準備環境

安裝 Config Sync

控制台

gcloud

為 Cloud Build 建立服務帳戶

建立機群套件

更新機群套件

檢查資源套件和發行內容

管理機群套件推出作業

部署策略

部署至叢集子集

建立機群套件

更新機群套件

將變體資源部署至叢集

建立機群套件

更新機群套件

刪除機群套件

疑難排解

後續步驟

部署機群套件