關於機群套件

Config Sync 中的 FleetPackage 宣告式 API 可讓您在註冊至機群的叢集間部署及管理機群套件。套件是一組定義叢集設定的 Kubernetes YAML 資訊清單。使用機群套件，即可一次或逐步將設定更新部署至機群，降低大規模服務中斷的風險。

您只需定義每個 FleetPackage 物件一次，然後在設定變更時，以新修訂版本更新該套件。套用新修訂版本時，機群套件服務會自動偵測這些變更，並部署至目標叢集。

優點

機群套件是以 Config Sync 功能 (例如自動偏移校正) 為基礎建構而成，具有下列優點：

• 自動推出資源：設定機群套件後，機群套件服務會自動將其指向的 Kubernetes 資源部署至所有叢集。

• 自動設定新叢集：如果您設定機群套件，之後再將新叢集新增至機群，機群套件定義的所有資源都會自動部署至新叢集。

• 大規模管理 Kubernetes 設定：使用機群套件將資源部署至整個叢集機群，不必逐一管理叢集。

• 盡量減少錯誤變更的影響：選擇一次要將資源部署至多少個叢集。您可以密切監控每個叢集的變更，確保不正確的變更不會影響整個機群。

• 簡化 Config Sync 設定：機群套件會使用 Cloud Build 向 Git 驗證，也就是說，您只需為每個專案驗證一次，不必為每個 RootSync 或 RepoSync 物件驗證。

如果符合下列一或多種情況，您可能偏好搭配使用 Config Sync 與 RootSync 或 RepoSync 物件，而非機群套件：

• 您管理的叢集數量不多。

• 您需要進一步控管資源部署至叢集的方式，而不只是透過 Fleet Package API 提供標籤和變體。

需求條件和限制

• 設定機群套件時，僅支援 Git 存放區做為可靠資料來源。

• 儲存在 Git 中的 Kubernetes 資源必須代表資源的最終狀態。不支援額外的疊加層來轉換儲存在 Git 中的資源。如要進一步瞭解這些資源的差異，請參閱「最佳做法：建立 WET 存放區」。

• FleetPackage API 僅適用於 us-central1 區域。您仍可部署至不同區域的叢集，但必須在 us-central1 設定 Cloud Build 和 gcloud CLI。

• 每個專案在各區域最多可有 300 個機群套件。

架構

您可以使用 FleetPackage API，將 Kubernetes 資訊清單部署至一組叢集。FleetPackage API 會使用 Cloud Build，從 Git 存放區同步及擷取 Kubernetes 資源。接著，機群套件服務會將這些資源部署至叢集。

變化版本的生成方式

機群套件會使用變體系統，將不同的 Kubernetes 資源設定部署至機群內的不同叢集或叢集群組，但這些設定都來自同一個 Git 存放區。

FleetPackage 規格中有兩個欄位可控制變化版本的行為：

1. resourceBundleSelector.cloudBuildRepository.variantsPattern：用於在 Git 存放區中尋找檔案和目錄的 glob 模式 (位於指定的 path 下，如果省略 path，則位於存放區根目錄下)。這個模式會決定哪些檔案或目錄會成為變體，以及其中包含哪些內容。
2. variantSelector.variantNameTemplate：將機群中的每個叢集對應至 variantsPattern 產生的其中一個變化版本名稱。這項選擇是根據叢集的機群成員資格中繼資料。

variantsPattern 比對

variantsPattern 欄位為必填，用於指定如何根據存放區中的設定產生變化版本。比對邏輯如下：

• 檔案比對：如果模式與 YAML 檔案相符，系統就會建立變化版本。

  • 變化版本名稱：不含副檔名的檔案名稱 (例如 prod-config.yaml 變成變化版本 prod-config)。
  • 變化版本內容：這個單一檔案的內容。

• 目錄比對：如果模式與目錄相符，系統會建立變體。

  • 變化版本名稱：目錄名稱 (例如目錄 dev 會變成變化版本 dev)。
  • 變化版本內容：這個目錄及其所有子目錄中，所有 YAML 檔案的組合。

檔案比對模式有下列限制：

• 不支援遞迴 (雙重) 萬用字元。不支援 ** 模式。
• 如果模式包含點 (.) 字元，後面必須加上英數字元。
• 模式不得包含單引號 (')。
• 變化版本名稱不得重複。如果模式比對到多個同名檔案 (例如 app1/deploy.yaml 和 app2/deploy.yaml)，兩者都會嘗試建立名為 deploy 的變化版本，導致名稱衝突。

舉例來說，假設存放區結構如下：

repo-root/
└── FleetPackages/
    └── clusters/
        ├── common-ingress.yaml
        ├── us-central1-a/
        │   ├── gke-1/
        │   │   ├── deployment.yaml
        │   │   └── service.yaml
        │   └── gke-2/
        │       ├── deployment.yaml
        │       └── service.yaml
        └── us-central1-b/
            ├── gke-1.yaml
            └── blue-green.yaml

您可以根據機群套件規格中定義的檔案或目錄比對類型，比對不同的檔案，並同步至叢集，例如：

• variantsPattern: "*"：比對 common-ingress.yaml、us-central1-a 和 us-central1-b。生成變化版本：

  • common-ingress (來自檔案)
  • us-central1-a (合併該資料夾中的所有 YAML 檔案)
  • us-central1-b (合併該資料夾中的所有 YAML)

• variantsPattern: "*.yaml"：與 common-ingress.yaml 相符。生成變體：

  • common-ingress

• variantsPattern: "us-*"：比對 us-central1-a 和 us-central1-b。生成變化版本：

  • us-central1-a
  • us-central1-b

• variantsPattern: "us-central1-b/*.yaml"：比對 us-central1-b/gke-1.yaml 和 us-central1-b/blue-green.yaml。生成變體：

  • gke-1
  • blue-green

variantNameTemplate 比對

定義變化版本後，variantSelector 區段中的 variantNameTemplate 欄位會決定要將哪個變化版本套用至各個叢集。範本可以使用變數存取下列機群成員資格中繼資料：

• ${membership.name}：叢集的機群成員資格名稱。
• ${membership.location}：機群成員資格位置。
• ${membership.project}：機群成員資格專案。
• ${membership.labels['KEY']}：機群成員資格的標籤 KEY 值。

舉例來說，請考慮下列使用標籤比對變化版本的情境：

• variantNameTemplate: "${membership.labels['env']}"：標籤為 env: prod 的叢集會同步至名為 prod 的變體。
• variantNameTemplate: "${membership.location}"：叢集會同步至與其位置相符的變體 (例如 us-central1-a)。
• variantNameTemplate: "default"：叢集會同步至名為 default 的變體。如果省略 variantSelector，則會採用預設行為。如果存放區不含名為 default.yaml 的檔案或名為 default 的目錄，則不會同步任何內容。

合併 variantsPattern 和 variantNameTemplate

為確保部署作業成功，您必須確保 variantsPattern 產生的變化版本名稱與 variantNameTemplate 相符，叢集才能同步至這些名稱。

舉例來說，如要根據環境標籤部署至叢集，您可以使用 dev、staging 和 prod 等目錄建構 Git 存放區。接著，您可以使用下列機群套件規格：

resourceBundleSelector:
  cloudBuildRepository:
    # ... other fields
    path: "manifests"
    variantsPattern: "*" # Matches dev, staging, prod directories
variantSelector:
  variantNameTemplate: "${membership.labels['env']}"

透過這項設定，標示為 env: staging 的叢集會接收 manifests/staging/ 目錄的內容。

部署策略

您可以使用機群套件，將 Git 存放區中的資源部署至整個叢集機群。您也可以設定機群套件，控管資源的部署方式、位置和類型。

以下各節提供不同 FleetPackage 設定的範例。如要進一步瞭解如何套用機群套件，請參閱「部署機群套件」。

部署至機群中的所有叢集

下列 FleetPackage 使用滾動策略，一次將 Kubernetes 資源部署至三個叢集，並指定機群中的所有叢集：

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/my-project/locations/us-central1/connections/my-connection/repositories/my-repo
    tag: v1.0.0
    variantsPattern: "*.yaml"
    serviceAccount: projects/my-project/serviceAccounts/[e-mail]
target:
  fleet:
    project: projects/my-project
rolloutStrategy:
  rolling:
    maxConcurrent: 3
variantSelector:
  variantNameTemplate: deployment # matches a file named deployment.yaml

部署至部分叢集

下列 FleetPackage 使用標籤選取器，僅將 Kubernetes 資源部署至機群中成員資格標籤 country 與 "us" 相符的叢集：

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/my-project/locations/us-central1/connections/my-connection/repositories/my-repo
    tag: v1.0.0
    variantsPattern: "*.yaml"
    serviceAccount: projects/my-project/serviceAccounts/[e-mail]
target:
  fleet:
    project: projects/my-project
    selector:
      matchLabels:
        country: "us"
rolloutStrategy:
  rolling:
    maxConcurrent: 3

後續步驟

部署機群套件