本頁說明如何在 Google Distributed Cloud 連結網路方案環境中使用 Config Sync 機群套件。機群套件是一種工具，可使用 Git 存放區做為叢集設定的單一可靠資料來源。
Distributed Cloud Connected 中的 Fleet 套件與標準 Google Kubernetes Engine 叢集使用相同的基礎技術和指令。GKE 說明文件頁面「部署機群套件」說明如何建立及管理機群套件。本頁說明如何根據 Distributed Cloud 連線環境調整該指南。
下列各節說明 Distributed Cloud 連線的必要做法，以及 GKE 文件中哪些步驟可照常執行。
需求條件
在 Distributed Cloud Connected 中使用 Config Sync 機群套件時，須符合下列條件：
- 由於推出控制器位於雲端，您的 Git 存放區必須可透過公用網際網路連線。系統不支援未公開的內部或地端部署 Git 伺服器。
- Distributed Cloud Connected 僅支援使用 Fleet Workload Identity Federation 向 Google Cloud 服務進行驗證。叢集與版本化套件組合存放區之間的連線不支援其他 Config Sync 驗證方法，例如 SSH 金鑰或 Cookie。詳情請參閱「Workload Identity 叢集驗證」。
- 機群中的所有叢集都必須位於同一項專案中。 Distributed Cloud Connected 不支援將多個專案的叢集註冊至單一中央專案，以進行機群管理。
- Kubernetes 資訊清單必須符合 Distributed Cloud 連線工作負載限制。如果資訊清單違反這些限制，叢集許可控制器就會封鎖。
- 機群套件必須使用 Config Sync 1.16.0 以上版本。
系統行為
Distributed Cloud connected 中的 Fleet 套件具有下列行為：
- 機群套件會將 Kubernetes 資訊清單轉換為已納入版本的 OCI 映像檔。這些映像檔會儲存在名為
fleet-packages的受管理 Artifact Registry 存放區中，該存放區會在專案中自動建立。叢集會直接從存放區提取這些映像檔，確保傳送作業一致且可靠。 - 機群套件會沿用 Config Sync 的偏移校正行為。叢集資源的手動變更會自動覆寫，以符合版本化 OCI 組合。
- 如果 Distributed Cloud 連線叢集進入存續模式，Config Sync 代理程式會繼續在本地強制執行上次成功同步的設定。不過，在雲端連線能力恢復前，任何新的推出或車隊套件更新都會暫停。
- 機群套件會沿用 Config Sync 的資源自動修剪行為。在 Git 存放區中建立新標記，並使用新標記更新機群套件設定來啟動同步作業時，如果從 Git 存放區中移除資訊清單，Config Sync 代理程式就會從叢集中刪除對應的資源。
- 如果多個機群套件管理相同資源，就會發生擁有權衝突。如果嘗試刪除處於擁有權衝突狀態的機群套件，刪除作業可能會停滯。如要解決這個問題，請修改其中一個衝突的車隊套件，移除衝突的資源，再嘗試刪除套件。
Distributed Cloud connected 先決條件
請先確認 Distributed Cloud 連線環境和使用者權限設定正確無誤，再按照「部署機群套件」一文中的步驟操作。
網路與安全
網路環境必須符合下列條件：
- VPC Service Controls。如果專案受到 VPC 服務範圍保護，請確保 Cloud Build 和 Config Delivery 服務代理程式 (例如
service-PROJECT_NUMBER@gcp-sa-configdelivery.iam.gserviceaccount.com) 已獲授權可跨越範圍，並從 Artifact Registry 提取映像檔。詳情請參閱「設定 VPC Service Controls 整合」。 - 輸出存取權。Distributed Cloud connected 叢集必須具備
us-central1-docker.pkg.dev的輸出存取權。機群套件會將資訊清單組合以 OCI 映像檔的形式儲存在 Artifact Registry 中。叢集必須能夠直接從 Artifact Registry 提取這些映像檔。
存放區設定
包含資訊清單套件的 Artifact Registry 存放區必須與機群套件位於相同專案，且必須位於 us-central1。
所需權限
如要在 Distributed Cloud 連線環境中完成步驟，您必須擁有專案的下列 IAM 角色：
- Config Delivery Admin (
roles/configdelivery.admin)：建立及管理機群套件和推出作業時必須具備此角色 - Developer Connect 管理員 (
roles/developerconnect.admin)：必須具備此角色才能建立及管理存放區連線 - 專案 IAM 管理員 (
roles/resourcemanager.projectIamAdmin)：必要角色，可將必要角色授予服務帳戶
如要進一步瞭解如何授予角色，請參閱「授予、變更及撤銷資源的存取權」。
必要 API
您需要啟用 API，才能建立存放區連線，並與 Distributed Cloud 連線叢集進行安全通訊。如要啟用必要的 API，請執行下列指令：
gcloud services enable
gcloud services enable anthosconfigmanagement.googleapis.com \
configdelivery.googleapis.com \
cloudbuild.googleapis.com \
connectgateway.googleapis.com \
developerconnect.googleapis.com \
artifactregistry.googleapis.com
下列元件需要這些 API：
anthosconfigmanagement.googleapis.com：管理叢集上的 Config Sync 代理程式configdelivery.googleapis.com：協調機群中 Kubernetes 資源的推出作業cloudbuild.googleapis.com：從 Git 擷取 Kubernetes 資訊清單，並將其封裝成版本化套件connectgateway.googleapis.com：在設定傳送服務與 Distributed Cloud 連線叢集之間提供安全連線developerconnect.googleapis.com：可安全連線至外部 Git 存放區主機artifactregistry.googleapis.com：在專案中以 OCI 映像檔的形式儲存版本化套件組合
預設環境設定
機群套件的 Config Delivery API 僅支援 us-central1。如要確保指令路徑正確，請使用 gcloud config set 指令設定預設專案和位置：
設定您的預設專案：
gcloud config set project PROJECT_ID
將
PROJECT_ID替換為 Google Cloud 專案 ID。設定車隊套件的預設位置。搭配機群套件使用的所有 Cloud Build 存放區連線，都必須位於
us-central1區域。gcloud config set config_delivery/location us-central1
程序差異
請參閱下表，瞭解如何將「部署機群套件」中的步驟套用至 Distributed Cloud 連線環境。
| 標準步驟 | Distributed Cloud connected 調整 |
|---|---|
| 向機群註冊叢集 | 略過這個步驟。建立 Distributed Cloud 連線叢集時，系統會自動將其註冊至專案中的機群。 |
| 安裝 Config Sync | 請按照標準步驟操作，但建議使用「在整個機群上安裝 (機群預設)」方法。在 Google Cloud 控制台的「Hub」或「Fleet」設定中，設定這個方法。這項實作作業可確保區域中現有或日後的 Distributed Cloud 連線節點，都會自動收到 Config Sync 代理程式。 驗證成員類型必須選取「Workload Identity」。 您用於 Workload Identity 的服務帳戶必須具備專案的 roles/artifactregistry.reader 角色，Config Sync 代理程式才能從受管理 fleet-packages 存放區提取資訊清單套件。 |
| 建立服務帳戶 | 按照操作說明為 Cloud Build 建立服務帳戶，並授予必要權限。服務帳戶必須與車隊套件位於相同專案。建議您使用下列指令：
|
| 找出會員方案名稱 | 當指令要求 MEMBERSHIP_NAME 時，請使用 Distributed Cloud 連線叢集的名稱。您可以執行 gcloud container fleet memberships list 指令，找出叢集名稱。 |
| 找出叢集 | 以機群套件為叢集設定目標前，如果工作負載需要主機層級的網路設定 (例如 HugePages 或 SR-IOV)，請在叢集中的每個節點套用並驗證 NodeSystemConfigUpdate 資源。 |
| 找出 Git 標記 | 推出控制器需要 Git 標記，且標記必須採用完整的語意版本格式 (major.minor.patch)。舉例來說，v1.0.0 是有效格式，但 v1 無效。 |
| 指定特定叢集 | 雖然叢集會自動註冊，但如要使用標籤選取器指定叢集子集，您必須手動將標籤新增至叢集成員資格。 |
| 部署策略 | 使用標籤和變體指定特定叢集。如果是 Distributed Cloud 連線，變體範本中使用的成員資格中繼資料變數 (例如專案和位置)，是指與 Distributed Cloud 連線叢集相關聯的雲端資源。 下列 Distributed Cloud 專屬成員資格中繼資料可用於變體範本：
|
共用程序
對於下列作業工作，Distributed Cloud Connected 和標準 GKE 的指令語法和服務行為相同。按照這些操作說明進行設定時，請使用本文件「程序差異」一節中表格定義的設定和值。
- 建立機群套件：
定義
FleetPackage資源，以擷取及部署設定。 - 更新機群套件： 修改套件以推出變更或更新設定。
- 管理機群套件推出作業： 暫停、繼續或中止進行中的推出作業。
- 檢查資源套件和版本：
偵錯變體產生和版本管理。資源套件是設定的容器，而發布版本則是這些套件的例項版本。如要確認是否已順利將內容傳送至 Distributed Cloud connected 硬體，請使用
gcloud container fleet memberships get-credentials指令取得叢集存取權，然後使用kubectl檢查叢集上的RootSync狀態。 - 刪除機群套件：
移除機群套件及其管理資源。為確保順利移除，請確認與機群套件相關聯的受管理
RootSync物件已從叢集中移除。
監控與疑難排解
如要更有效率地監控部署作業，請搭配使用 --format 旗標和 gcloud 指令，在推出期間取得詳細的狀態訊息。
舉例來說，執行下列 gcloud container fleet packages rollouts describe 指令，即可查看機群中每個叢集的詳細狀態訊息：
gcloud container fleet packages rollouts describe ROLLOUT_NAME \
--fleet-package=FLEET_PACKAGE_NAME \
--format=json
替換下列值：
ROLLOUT_NAME：推出作業的名稱。FLEET_PACKAGE_NAME：機群套件的名稱。
如果建構作業失敗或停滯，您可以在 gcloud container fleet packages list 指令的輸出內容中，找到 Cloud Build 工作串流記錄的連結。如果推出作業仍處於 PENDING 或 STALLED 狀態，請按照「疑難排解 Distributed Cloud 連結網路方案」一文所述，檢查 Distributed Cloud 連結網路方案硬體連線。
如要進一步瞭解如何診斷與 Cloud Build 相關的錯誤，請參閱「排解建構錯誤」。
驗證叢集內同步狀態
如要確認叢集是否已成功與機群套件同步，請檢查叢集中的 RootSync 資源。叢集上的 RootSync 物件名稱與您為套件選擇的 FLEET_PACKAGE_NAME 相同。
如要檢查狀態，請執行下列指令：
kubectl get rootsync FLEET_PACKAGE_NAME -n config-management-system
同步處理成功時，會顯示 SYNCED 狀態。如果看到 Error 狀態，請執行下列指令，取得更多詳細資料：
kubectl describe rootsync FLEET_PACKAGE_NAME -n config-management-system
詳情請參閱 GKE 說明文件中的「監控 RootSync 和 RepoSync 物件」。
如需解讀輸出內容中特定錯誤代碼的說明，請參閱 Config Sync 錯誤參考資料。