自訂 Config Sync 安裝作業

透過 Config Sync，您可以從集中式可靠來源 (例如 Git 存放區、OCI 映像檔或 Helm 資訊套件) 同步處理設定，藉此管理 Kubernetes 資源。如果預設安裝操作說明不符合需求，您可能需要自訂 Config Sync 安裝作業。

本頁說明如何進階安裝及設定 Config Sync。安裝程序包括：

• 使用Google Cloud 控制台、Google Cloud CLI 或 Terraform，在個別叢集上安裝 Config Sync。
• 設定根存放區，包括來源類型、格式和驗證。
• 確認 Config Sync 安裝及設定成功。

限制

Config Sync 不支援使用 Google Cloud 控制台或 Google Cloud CLI，將 helm 設定為來源類型。您可以透過 Kubernetes API 設定 RootSync 或 RepoSync 物件，從 Helm 存放區同步處理，或在其他可靠資料來源中宣告。詳情請參閱「Helm 存放區的設定」一節。

事前準備

安裝 Config Sync 前，請準備單一事實來源和合適的叢集。

授予 Config Sync 對可靠資料來源的存取權

如要將可靠來源的設定同步至叢集，Config Sync 需要存放區的唯讀權限。如要授權 Config Sync 讀取設定，請完成下列步驟：

• 建立或存取可靠來源，其中包含您要讓 Config Sync 同步至叢集的設定檔。詳情請參閱下列資源：

  • 將設定新增至單一事實來源：設定的概念資訊。
  • GitOps 最佳做法：提供整理及管理存放區的訣竅和一般最佳做法。
  • 使用非結構化存放區：使用及整理非結構化存放區的建議。

• 如果您的單一事實來源是公開的，則無須採取任何行動。 Config Sync 不需要額外權限。

• 如果你的單一事實來源是私人來源，請按照下列其中一個頁面的操作說明完成設定：

  • 授予 Config Sync 存取 Git 的權限。
  • 授予 Config Sync 對 OCI 或 Helm 的存取權。

查看叢集需求

建立叢集前，請先查看叢集需求。

安裝 Config Sync

使用 Google Cloud 控制台或 Google Cloud CLI 安裝 Config Sync 時，Config Sync 會自動建立名為 root-sync 的 RootSync 物件。您可以使用 kubectl 指令修改 root-sync，並新增其他 Config Sync 設定。詳情請參閱「使用 kubectl 指令設定 Config Sync」。

控制台

安裝 Config Sync

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

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

   前往「設定」

2. 按一下「安裝 Config Sync」。
3. 選取要使用的 Config Sync 版本。
4. 在「安裝選項」下方，選取下列其中一個選項：
   • 在整個機群中安裝 Config Sync (建議)：在機群中的所有叢集上安裝 Config Sync。
   • 在個別叢集上安裝 Config Sync：Config Sync 會安裝在您選取的叢集上。所選叢集會自動註冊至機群。
5. 如要在個別叢集上安裝 Config Sync，請在「Available clusters」(可用叢集) 表格中，選取要安裝 Config Sync 的叢集。
6. 按一下「Install Config Sync」(安裝 Config Sync)。在「設定」分頁中，幾分鐘後，機群中叢集的「狀態」欄應該會顯示「已啟用」。

部署套件

將叢集註冊至機群並安裝 Config Sync 後，您就能設定 Config Sync，從可靠來源將套件部署至叢集。您可以將相同套件部署至多個叢集，也可以將不同套件部署至不同叢集。部署套件後，您可以編輯套件，但部分設定 (例如套件名稱和同步類型) 除外。詳情請參閱「管理套件」。

注意： 如要讓 Config Sync 算繪及套用 Helm 圖表，請使用 Google Cloud CLI 設定 Config Sync。

如要部署套件，請完成下列步驟：

1. 前往 Google Cloud 控制台的 Config Sync 資訊主頁。

   前往 Config Sync 資訊主頁

2. 按一下「Deploy Package」(部署套件)。

3. 在「Select clusters for package deployment」(選取叢集來部署套件) 表格中，選取要部署套件的叢集，然後按一下「Continue」(繼續)。

4. 選取「Package hosted on Git」(Git 上託管的套件) 或「Package hosted on OCI」(OCI 上託管的套件) 做為來源類型，然後按一下「繼續」。

5. 在「套件詳細資料」部分，輸入「套件名稱」，用於識別 RootSync 或 RepoSync 物件。

6. 在「Sync type」(同步類型) 欄位中，選擇「Cluster scoped sync」(叢集範圍同步) 或「Namespace scoped sync」(命名空間範圍同步) 做為同步類型。

   叢集範圍同步會建立 RootSync 物件，命名空間範圍同步則會建立 RepoSync 物件。 如要進一步瞭解這些物件，請參閱「Config Sync 架構」。

7. 在「來源」部分，完成下列步驟：

   • 如要使用 Git 存放區中託管的來源，請填寫下列欄位：

     1. 在「存放區網址」中，輸入做為資料來源的 Git 存放區網址。
     2. 選用：更新「修訂版本」欄位，確認您是否未使用預設的 HEAD。
     3. 選用：如不想從根存放區同步處理，請更新「路徑」欄位。
     4. 選用：如未使用預設的 main 分支版本，請更新「分支版本」欄位。

   • 如要使用 OCI 映像檔代管的來源，請輸入下列欄位：

     1. 輸入做為可靠資料來源的 OCI 圖片網址，做為「圖片」。
     2. 輸入要同步的目錄路徑 (相對於根目錄)，做為「目錄」。

8. (選用)：展開「進階設定」部分，完成下列步驟：

   1. 選取「驗證類型」。Config Sync 需要您可靠來源的唯讀權限，才能讀取來源中的設定檔，並將這些檔案套用至叢集。除非來源不需要驗證 (例如公開存放區)，否則請務必授予 Config Sync 對 Git 存放區、OCI 映像檔或 Helm 資訊套件 (僅限 gcloud CLI) 的唯讀存取權。選擇您在安裝 Config Sync 時設定的驗證類型：

      注意： 如果是 OCI，您只能選取「Workload Identity」進行驗證。
      • 無：不使用任何驗證機制。
      • SSH：使用 SSH 金鑰組進行驗證。
      • Cookiefile：使用 cookiefile 進行驗證。
      • 權杖：使用存取權杖或密碼進行驗證。
      • Google Cloud Repository：使用 Google 服務帳戶存取 Cloud Source Repositories 存放區。只有在叢集未啟用 GKE 的工作負載身分聯盟時，才選取這個選項。
      • Workload Identity：使用 Google 服務帳戶存取 Cloud Source Repositories 存放區。

   2. 輸入秒數來設定「同步等待時間」，決定 Config Sync 嘗試從可靠來源提取資料時的等待時間。

   3. 輸入 Git Proxy 網址，供 HTTPS Proxy 在與資料來源通訊時使用。

   4. 選擇「階層」即可變更「來源格式」。

      在大多數情況下，建議使用預設值「非結構化」，因為這樣您就能隨意整理單一事實來源。

9. 按一下「Deploy Package」(部署套件)。

   系統會將您重新導向至 Config Sync「Packages」(套件) 頁面。幾分鐘後，您應該會在所設定叢集的「Sync status」(同步處理狀態)欄中看到「Synced」(已同步)。

gcloud

繼續操作前，請先將叢集註冊至機群。

1. 啟用 ConfigManagement 車隊功能：

   gcloud beta container fleet config-management enable
   

2. 建立名為 apply-spec.yaml 的檔案，並將下列 YAML 檔案複製到該檔案中，即可準備設定。

   建立資訊清單時，您可以設定所有需要的選用 spec.configSync 欄位，之後再使用 kubectl 指令進行設定。您也可以只將 spec.configSync.enabled 欄位設為 true，並省略選用欄位。之後您可以使用 kubectl 指令建立其他 RootSync 物件或 RepoSync，並透過 kubectl 指令全面管理。

   # apply-spec.yaml
   
        applySpecVersion: 1
        spec:
          configSync:
            enabled: true
            # If you don't have a source of truth yet, omit the
            # following fields. You can configure them later.
            sourceType: SOURCE_TYPE
            sourceFormat: FORMAT
            syncRepo: REPO
            syncRev: REVISION
            secretType: SECRET_TYPE
            gcpServiceAccountEmail: EMAIL
            metricsGcpServiceAccountEmail: METRICS_EMAIL
            policyDir: DIRECTORY
            preventDrift: false
   

   更改下列內容：

   • SOURCE_TYPE：新增 git 從 Git 存放區同步、oci 從 OCI 映像檔同步，或 helm 從 Helm 資訊套件同步。如未指定值，預設值為 git。
   • FORMAT：新增 unstructured 即可使用非結構化存放區，或新增 hierarchy 即可使用階層式存放區。這些值會區分大小寫。 這是選填欄位，預設值為 hierarchy。建議您新增 unstructured，因為這個格式可讓您以最方便的方式整理設定。

   • REPO：新增資訊來源的網址。 Git 和 Helm 存放區網址使用 HTTPS 或 SSH 通訊協定。例如：https://github.com/GoogleCloudPlatform/anthos-config-management-samples。如果您打算使用 SSH 做為 secretType，請輸入含有 SSH 通訊協定的網址。這個欄位為必填，如未輸入通訊協定，系統會將網址視為 HTTPS 網址。

     OCI 網址採用下列格式： LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME。 根據預設，系統會從 latest 標記提取圖片，但您也可以改用 TAG 或 DIGEST 提取圖片。在 PACKAGE_NAME 中指定 TAG 或 DIGEST：

     • 如要依 TAG 提取：LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME:TAG
     • 如要依 DIGEST 提取：LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME@sha256:DIGEST
     注意： Config Sync 要求 OCI 層必須以 tar 或 tar+gzip 格式壓縮。 Config Sync 無法辨識其他格式 (例如 tar+bz2)。如果從有效的 REPO 切換為格式不受支援的 OCI 映像檔，系統會修剪受管理資源，但不會顯示錯誤。

   • REVISION：要從中同步處理的 Git 修訂版本 (標記或雜湊) 或分支名稱。使用雜湊時，必須是完整雜湊，不得使用縮寫形式。

   • SECRET_TYPE：下列其中一個 secretTypes：

     Git

     • none：不使用驗證。
     • ssh：使用安全殼層金鑰組。
     • cookiefile：使用 cookiefile。
     • token：使用權杖。
     • gcpserviceaccount：使用 Google 服務帳戶存取 Cloud Source Repositories 或 Secure Source Manager 存放區。如果選取這個驗證類型，您需要在完成 Config Sync 設定後，建立 IAM 政策繫結。詳情請參閱「使用 Google 服務帳戶授予 Config Sync Git 存取權」一節中的 Google 服務帳戶分頁。
     • gcenode：使用 Google 服務帳戶存取 Cloud Source Repositories。只有在叢集未啟用 Workload Identity Federation for GKE 時，才選取這個選項。
     • githubapp：使用 GitHub 應用程式向 GitHub 存放區進行驗證。

     如要進一步瞭解這些驗證類型，請參閱「授予 Config Sync Git 存取權」。

     oci

     • none：不使用驗證
     • gcenode：使用 Compute Engine 預設服務帳戶存取 Artifact Registry 中的映像檔。只有在叢集未啟用 Workload Identity Federation for GKE 時，才選取這個選項。
     • gcpserviceaccount：使用 Google 服務帳戶存取圖片。

     helm

     • token：使用權杖。
     • gcenode：使用 Compute Engine 預設服務帳戶存取 Artifact Registry 中的映像檔。只有在叢集未啟用 Workload Identity Federation for GKE 時，才選取這個選項。
     • gcpserviceaccount：使用 Google 服務帳戶存取圖片。

     • EMAIL：如果您已將 gcpserviceaccount 新增為 secretType，請新增 Google 服務帳戶電子郵件地址。gcpserviceaccountsecretType例如：acm@PROJECT_ID.。

     • METRICS_EMAIL：用於將 Config Sync 指標匯出至 Cloud Monitoring 的 Google Cloud服務帳戶 (GSA) 電子郵件地址。GSA 應具備監控指標寫入者 (roles/monitoring.metricWriter) IAM 角色。命名空間 config-management-monitoring 中的 Kubernetes ServiceAccount default 應繫結至 GSA。

     • DIRECTORY：要從中同步處理的目錄路徑，相對於 Git 存放區的根目錄。系統會納入您指定目錄的所有子目錄，並同步至叢集。預設值為存放區的根目錄。

   如需可新增至 spec 欄位的完整欄位清單，請參閱 gcloud 欄位。

   注意： 如果尚未準備好單一事實來源，您可以將 spec.configSync.enabled 設為 true，並省略所有其他 spec.configSync 欄位，啟用設定同步功能而不設定任何設定。準備好存放區後，請編輯 apply-spec.yaml 以新增設定。

3. 套用 apply-spec.yaml 檔案。如果您使用現有資訊清單，應將檔案套用至要設定的叢集，並使用先前指令擷取的設定：

   gcloud beta container fleet config-management apply \
       --membership=MEMBERSHIP_NAME \
       --config=CONFIG_YAML_PATH \
       --project=PROJECT_ID
   

   更改下列內容：

   • MEMBERSHIP_NAME：您在註冊叢集時選擇的機群成員名稱。您可以使用 gcloud container fleet memberships list 找出名稱。
   • CONFIG_YAML_PATH：apply-spec.yaml 檔案的路徑。
   • PROJECT_ID：您的專案 ID。

Terraform

針對要設定 Config Sync 的每個叢集，套用包含 configmanagement 和 config_sync 區塊的 google_gkehub_feature_membership 資源區塊，例如：

Git

data "google_project" "default" {}

resource "google_container_cluster" "default" {
  name     = "gke-autopilot-basic"
  location = "us-central1"

  fleet {
    project = data.google_project.default.project_id
  }

  enable_autopilot = true
}

resource "google_gke_hub_feature" "configmanagement_feature" {
  name     = "configmanagement"
  location = "global"
}

resource "google_gke_hub_feature_membership" "configmanagement_feature_member" {
  location = "global"

  feature             = google_gke_hub_feature.configmanagement_feature.name
  membership          = google_container_cluster.default.fleet[0].membership_id
  membership_location = google_container_cluster.default.fleet[0].membership_location

  configmanagement {
    config_sync {
      # The field `enabled` was introduced in Terraform version 5.41.0, and
      # needs to be set to `true` explicitly to install Config Sync.
      enabled = true
      git {
        sync_repo   = "REPO"
        sync_branch = "BRANCH"
        policy_dir  = "DIRECTORY"
        secret_type = "SECRET"
      }
    }
  }
}

更改下列內容：

• REPO：包含設定檔的 Git 存放區網址。
• BRANCH：存放區分支，例如 main。
• DIRECTORY：Git 存放區中的路徑，代表要同步處理的存放區頂層。
• SECRET：密鑰驗證類型。

oci

data "google_project" "default" {}

resource "google_container_cluster" "default" {
  name     = "gke-autopilot-basic"
  location = "us-central1"

  fleet {
    project = data.google_project.default.project_id
  }

  enable_autopilot = true
}

resource "google_gke_hub_feature" "configmanagement_feature" {
  name     = "configmanagement"
  location = "global"
}

resource "google_gke_hub_feature_membership" "configmanagement_feature_member" {
  location = "global"

  feature             = google_gke_hub_feature.configmanagement_feature.name
  membership          = google_container_cluster.default.fleet[0].membership_id
  membership_location = google_container_cluster.default.fleet[0].membership_location

  configmanagement {
    config_sync {
      # The field `enabled` was introduced in Terraform version 5.41.0, and
      # needs to be set to `true` explicitly to install Config Sync.
      enabled = true
      oci {
        sync_repo   = "REPO"
        policy_dir  = "DIRECTORY"
        secret_type = "SECRET"
      }
    }
  }
}

更改下列內容：

• REPO：OCI 映像檔存放區的網址，內含設定檔。
• DIRECTORY：含有要同步處理資源的目錄絕對路徑。如要使用根目錄，請將這個欄位留空。
• SECRET：密鑰驗證類型。

針對要同步處理的每個叢集，重複執行這個程序。

如要進一步瞭解如何使用 Terraform，請參閱「Config Sync 的 Terraform 支援」。

設定根存放區後，您可以選擇設定從多個存放區同步處理，包括其他根存放區和命名空間存放區。如果您希望存放區包含命名空間範圍的設定，並同步至叢集中的特定命名空間，命名空間存放區就非常實用。

驗證安裝

安裝及設定 Config Sync 後，您可以確認安裝是否成功。

gcloud

執行下列指令：

nomos status

安裝成功後，狀態會顯示為 SYNCED 或 PENDING。

如要進一步瞭解 nomos status 提供的資訊 (包括回報的錯誤)，請參閱 nomos 指令列工具說明文件中的「檢查 Config Sync 狀態」一節。

主控台

操作步驟如下：

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

   前往「設定」

2. 在「Packages」(套件) 分頁中，查看叢集表格的「Sync status」(同步狀態) 欄。 成功安裝 Config Sync 後，狀態會顯示為「已安裝」。 如果已成功設定可靠資料來源，狀態會顯示為「已同步」。

後續步驟

• 瞭解如何升級 Config Sync。
• 進一步瞭解如何使用 gcloud 指令設定 Config Sync。
• 瞭解如何設定同步處理多個存放區。
• 使用 nomos 指令。
• 請參閱「簡介：排解 Config Sync 問題」。
• 瞭解如何解除安裝 Config Sync。
• 查看預設 Config Sync 權限。