從 Artifact Registry 同步處理 Helm 資訊套件

本頁說明如何建立 Helm 資訊套件並推送至 Artifact Registry 的存放區，藉此從 Artifact Registry 同步處理 Helm 資訊套件。這個檔案也包含範例設定，可從 Helm 存放區同步處理圖表。

重要術語： Helm 是 Kubernetes 的套件管理工具，可協助您定義、安裝及升級應用程式。Config Sync 可以使用 Helm API，直接從 Artifact Registry 同步處理 Helm 資訊套件，也可以轉譯 Kustomize 設定中指定的 Helm 資訊套件。

您可以設定 Config Sync，從 Helm 存放區同步處理。您可以將 Helm 資訊套件儲存在 Artifact Registry，這是 Google Cloud建議使用的 Helm 存放區。如要使用這項功能，請啟用 RootSync 和 RepoSync API。Config Sync 會使用 helm template 算繪 Helm 資訊套件，因此不支援完整的 Helm 生命週期管理。

隨附的 Helm 和 Kustomize 版本：列出與對應 Config Sync 版本隨附的 Kustomize 和 Helm 版本。

事前準備

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

安裝 Google Cloud CLI。

注意：如果您先前已安裝 gcloud CLI，請執行 gcloud components update，確認您使用的是最新版本。

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

建立或選取 Google Cloud 專案。

選取或建立專案所需的角色

• 選取專案：選取專案時，不需要具備特定 IAM 角色，只要您在專案中獲派角色，即可選取該專案。
• 建立專案：如要建立專案，您需要具備專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

注意：如果您不打算保留在這項程序中建立的資源，請建立新專案，而不要選取現有專案。完成這些步驟後，您就可以刪除專案，並移除與該專案相關聯的所有資源。

• 建立 Google Cloud 專案：

  gcloud projects create PROJECT_ID

  將 PROJECT_ID 替換為您要建立的 Google Cloud 專案名稱。

• 選取您建立的 Google Cloud 專案：

  gcloud config set project PROJECT_ID

  將 PROJECT_ID 替換為 Google Cloud 專案名稱。

確認專案已啟用計費功能 Google Cloud 。

啟用 GKE、Config Sync 和 Artifact Registry API：

啟用 API 時所需的角色

如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

gcloud services enable container.googleapis.com  anthosconfigmanagement.googleapis.com  artifactregistry.googleapis.com

安裝 Google Cloud CLI。

注意：如果您先前已安裝 gcloud CLI，請執行 gcloud components update，確認您使用的是最新版本。

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

建立或選取 Google Cloud 專案。

選取或建立專案所需的角色

• 選取專案：選取專案時，不需要具備特定 IAM 角色，只要您在專案中獲派角色，即可選取該專案。
• 建立專案：如要建立專案，您需要具備專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

注意：如果您不打算保留在這項程序中建立的資源，請建立新專案，而不要選取現有專案。完成這些步驟後，您就可以刪除專案，並移除與該專案相關聯的所有資源。

• 建立 Google Cloud 專案：

  gcloud projects create PROJECT_ID

  將 PROJECT_ID 替換為您要建立的 Google Cloud 專案名稱。

• 選取您建立的 Google Cloud 專案：

  gcloud config set project PROJECT_ID

  將 PROJECT_ID 替換為 Google Cloud 專案名稱。

確認專案已啟用計費功能 Google Cloud 。

啟用 GKE、Config Sync 和 Artifact Registry API：

啟用 API 時所需的角色

如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

gcloud services enable container.googleapis.com  anthosconfigmanagement.googleapis.com  artifactregistry.googleapis.com

1. 建立或存取符合 Config Sync 需求的叢集，並使用最新版 Config Sync。
2. 安裝 nomos CLI 或升級至最新版本。
3. 安裝 Helm 3.8.0 以上版本。在舊版 Helm 中，OCI 格式的圖表支援功能為實驗功能。
4. 在叢集上啟用 Workload Identity Federation for GKE。

限制

• 您無法只變更資料來源中的值，就變更設定中的任何不可變更欄位。如要更新不可變更的欄位，請先在資料來源中進行變更，然後手動刪除叢集中的物件。Config Sync 隨後會使用新的欄位值重新建立物件。

• 下列 Helm 資訊套件包含工作，不建議透過 Config Sync 部署：

  • secrets-store-csi-driver
  • cert-manager

  如要進一步瞭解為何不建議搭配使用 Jobs 與 Config Sync，請參閱「避免使用 Config Sync 管理 Jobs」一文。

建立 Artifact Registry 存放區

在本節中，您將建立 Artifact Registry 存放區。如要進一步瞭解如何建立 Artifact Registry 存放區，請參閱「建立存放區」。

1. 啟用 Artifact Registry API：

   gcloud services enable artifactregistry.googleapis.com --project=PROJECT_ID
   

2. 建立 Artifact Registry 存放區：

   gcloud artifacts repositories create AR_REPO_NAME \
      --repository-format=docker \
      --location=AR_REGION \
      --description="Config Sync Helm repo" \
      --project=PROJECT_ID
   

更改下列內容：

• PROJECT_ID：機構的專案 ID。
• AR_REPO_NAME：存放區 ID。
• AR_REGION：存放區的區域或多區域位置。

下列章節中使用的變數：

• FLEET_HOST_PROJECT_ID：如果您使用 GKE Workload Identity Federation for GKE，這與 PROJECT_ID 相同。如果您使用機群 Workload Identity Federation for GKE，這是叢集註冊的機群專案 ID。
• GSA_NAME：要用來連線至 Artifact Registry 的自訂 Google 服務帳戶名稱。
• KSA_NAME：調解器的 Kubernetes 服務帳戶。
  • 如果是根層級存放區，且 RootSync 名稱是 root-sync，請新增 root-reconciler。否則，請新增 root-reconciler-ROOT_SYNC_NAME。
  • 如果是命名空間存放區，且 RepoSync 名稱為 repo-sync，請新增 ns-reconciler-NAMESPACE。否則，請加入 ns-reconciler-NAMESPACE-REPO_SYNC_NAME-REPO_SYNC_NAME_LENGTH，其中 REPO_SYNC_NAME_LENGTH 是 REPO_SYNC_NAME 中的字元數。

授予讀者權限

請完成下列步驟，使用 Kubernetes 服務帳戶向 Artifact Registry 進行驗證：

將 Artifact Registry 讀者 (roles/artifactregistry.reader) 身分與存取權管理角色授予具有 GKE 集區 Workload Identity Federation 的 Kubernetes 服務帳戶：

gcloud artifacts repositories add-iam-policy-binding AR_REPO_NAME \
    --location=AR_REGION \
    --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
    --role=roles/artifactregistry.reader \
    --project=PROJECT_ID

將 Helm 資訊套件推送至 Artifact Registry 存放區

在本節中，您將下載公開 Helm 資訊套件，並推送至 Artifact Registry。

1. 從公開 Helm 存放區擷取 mysql-9.3.1.tgz 套件，然後下載至本機：

   helm pull mysql --repo https://charts.bitnami.com/bitnami --version 9.3.1
   

2. 使用存取權杖進行驗證：

   Linux / macOS

   gcloud auth print-access-token | helm registry login -u oauth2accesstoken \
   --password-stdin https://AR_REGION-docker.pkg.dev
   

   Windows

   gcloud auth print-access-token
   ya29.8QEQIfY_...
   
   helm registry login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \
   https://AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME
   

   在這項指令中，oauth2accesstoken 是使用存取權杖進行驗證時要用的使用者名稱，而 gcloud auth print-access-token 是取得存取權杖的指令。存取權杖是驗證用的密碼。使用存取權杖進行驗證是最安全的驗證方法。

3. 將 Helm 資訊套件推送至 Artifact Registry：

   helm push mysql-9.3.1.tgz oci://AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME
   

設定 Config Sync，從 Helm 圖表同步處理

在本節中，您會建立 RootSync 物件，並設定 Config Sync 從 Helm 資訊圖表進行同步。

如要覆寫 Helm 圖表的預設值，您可以在 spec.helm.values 欄位中指定值，或使用 spec.helm.valuesFileRefs 欄位新增對 ConfigMap 的參照。如要進一步瞭解選填欄位，請參閱「Helm 存放區的設定」。

提示： 如要使用圖表的預設值，可以採用任一範例，並省略 spec.helm.values 或 spec.helm.valuesFileRefs 欄位。

值

1. 建立具有專屬名稱的 RootSync 物件：

   cat <<EOF>> ROOT_SYNC_NAME.yaml
   apiVersion: configsync.gke.io/v1beta1
   kind: RootSync
   metadata:
     name: ROOT_SYNC_NAME
     namespace: config-management-system
   spec:
     sourceFormat: unstructured
     sourceType: helm
     helm:
       repo: oci://AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME
       chart: mysql
       version: 9.3.1
       releaseName: my-mysql
       namespace: test
       auth: k8sserviceaccount
       # Use the optional field spec.helm.values to override default values.
       # You can use the same format as the default values file to override
       # default values.
       values:
         image:
           pullPolicy: Always
         primary:
           resources:
             limits:
               cpu: 250m
               memory: 256Mi
             requests:
               cpu: 250m
               memory: 256Mi
   EOF
   

   將 ROOT_SYNC_NAME 替換為 RootSync 物件的名稱。名稱在叢集中不得重複，且長度不得超過 26 個半形字元。如果您使用控制台或 Google Cloud CLI 安裝 Config Sync，請選擇 root-sync 以外的名稱。 Google Cloud

   在本範例中，Helm 資訊圖表部署在 test 命名空間中，因為其資源的範本包含 namespace: {{ .Release.Namespace }}。

   您可以使用 helm.values 覆寫預設值。如要瞭解選填欄位，請參閱「Helm 存放區的設定」。

2. 套用 RootSync 物件：

   kubectl apply -f ROOT_SYNC_NAME.yaml
   

3. 確認 Config Sync 是否正在從映像檔同步處理：

   nomos status --contexts=$(kubectl config current-context)
   

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

   Connecting to clusters...
   
   *cluster-name
     --------------------
     <root>:root-sync   oci://AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME/mysql:9.3.1
     SYNCED             9.3.1
     Managed resources:
         NAMESPACE  NAME                       STATUS    SOURCEHASH
         default    configmap/my-mysql         Current   9.3.1
         default    secret/my-mysql            Current   9.3.1
         default    service/my-mysql           Current   9.3.1
         default    service/my-mysql-headless  Current   9.3.1
         default    serviceaccount/my-mysql    Current   9.3.1
         default    statefulset.apps/my-mysql  Current   9.3.1
   

   您已成功將 Helm 圖表同步至叢集。

valuesFileRefs

1. 建立具有專屬名稱的 RootSync 物件：

   cat <<EOF>> ROOT_SYNC_NAME.yaml
   apiVersion: configsync.gke.io/v1beta1
   kind: RootSync
   metadata:
     name: ROOT_SYNC_NAME
     namespace: config-management-system
   spec:
     sourceFormat: unstructured
     sourceType: helm
     helm:
       repo: oci://AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME
       chart: mysql
       version: 9.3.1
       releaseName: my-mysql
       auth: k8sserviceaccount
       # use the optional field spec.helm.valuesFilesRefs to override default values
       # by referencing a ConfigMap
       valuesFileRefs:
       - name: CONFIGMAP_NAME
         dataKey: DATA_KEY
   
   EOF
   

   更改下列內容：

   • ：RootSync 物件的名稱。名稱在叢集中應是唯一的，且不得超過 26 個字元。如果使用 Google Cloud 控制台或 Google Cloud CLI 安裝 Config Sync，請選擇 root-sync 以外的名稱。ROOT_SYNC_NAME
   • CONFIGMAP_NAME：ConfigMap 的名稱。這可以是 Kubernetes 接受的任何有效 ConfigMap 名稱，且在叢集中不得重複。
   • (選用) DATA_KEY：您要從中讀取值的 ConfigMap 中的資料鍵。預設值為 values.yaml。

2. 使用您的值建立 ConfigMap 物件：

   注意： ConfigMap 不可變更，且必須與參照該 ConfigMap 的 RootSync 或 RepoSync 位於相同命名空間。

   cat <<EOF>> CONFIGMAP_NAME.yaml
   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: CONFIGMAP_NAME
     namespace: config-management-system
   immutable: true
   # You can use the same format as the default values file to override
   # default values.
   data:
     DATA_KEY: |-
       image:
         pullPolicy: Always
       primary:
         resources:
           limits:
             cpu: 250m
             memory: 256Mi
           requests:
             cpu: 250m
             memory: 256Mi
   
   EOF
   

   如果您未在 RootSync 中指定 DATA_KEY 的值，則應為預設的 values.yaml。

3. 套用 ConfigMap 物件：

   kubectl apply -f CONFIGMAP_NAME.yaml
   

4. 套用 RootSync 物件：

   kubectl apply -f ROOT_SYNC_NAME.yaml
   

5. 確認 Config Sync 是否正在從映像檔同步處理：

   nomos status --contexts=$(kubectl config current-context)
   

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

   Connecting to clusters...
   
   *cluster-name
     --------------------
     <root>:root-sync   oci://AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME/mysql:9.3.1
     SYNCED             9.3.1
     Managed resources:
         NAMESPACE  NAME                       STATUS    SOURCEHASH
         default    configmap/my-mysql         Current   9.3.1
         default    secret/my-mysql            Current   9.3.1
         default    service/my-mysql           Current   9.3.1
         default    service/my-mysql-headless  Current   9.3.1
         default    serviceaccount/my-mysql    Current   9.3.1
         default    statefulset.apps/my-mysql  Current   9.3.1
   

   您已成功將 Helm 圖表同步至叢集。

   您也可以查看叢集中其中一個已同步資源的 imagePullPolicy，確認系統是否使用 ConfigMap 中的值來算繪圖表：

   kubectl get statefulset -n test my-mysql -o yaml | grep imagePullPolicy
   

6. 由於 ConfigMap 不可變更，如要變更值，您必須建立新的 ConfigMap，並更新 RootSync 或 RepoSync 規格中的 spec.helm.valuesFileRefs，指向新的 ConfigMap。建立新的 ConfigMap 可確保值變更時，系統會重新算繪 Helm 範本，這在重新算繪時需要同時更新 spec.helm.valuesFileRefs 中參照的多個 ConfigMap 時，非常實用。如要變更用於算繪範本的值，請建立名稱不同的新 ConfigMap：

   cat <<EOF>> CONFIGMAP_NAME-2.yaml
   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: CONFIGMAP_NAME-2
     namespace: config-management-system
   immutable: true
   # You can use the same format as the default values file to override
   # default values.
   data:
     DATA_KEY: |-
       image:
         pullPolicy: Never
       primary:
         resources:
           limits:
             cpu: 100m
             memory: 256Mi
           requests:
             cpu: 250m
             memory: 200Mi
   
   EOF
   

7. 更新 RootSync 物件，以參照新的 ConfigMap：

   cat <<EOF>> ROOT_SYNC_NAME.yaml
   apiVersion: configsync.gke.io/v1beta1
   kind: RootSync
   metadata:
     name: ROOT_SYNC_NAME
     namespace: config-management-system
   spec:
     sourceFormat: unstructured
     sourceType: helm
     helm:
       repo: oci://AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME
       chart: mysql
       version: 9.3.1
       releaseName: my-mysql
       namespace: test
       auth: k8sserviceaccount
       # use the optional field spec.helm.valuesFilesRefs to override default values
       # by referencing a ConfigMap
       valuesFileRefs:
       - name: CONFIGMAP_NAME-2
         dataKey: DATA_KEY
   
   EOF
   

8. 套用 ConfigMap 物件：

   kubectl apply -f CONFIGMAP_NAME-2.yaml
   

9. 套用 RootSync 物件：

   kubectl apply -f ROOT_SYNC_NAME.yaml
   

10. 確認 Config Sync 是否正在從映像檔同步處理：

    nomos status --contexts=$(kubectl config current-context)
    

    您也可以查看叢集中其中一個已同步資源的 imagePullPolicy，確認更新後的 ConfigMap 中的新值是否用於轉譯圖表：

    注意： 資源可能需要幾分鐘才能完全同步。

    kubectl get statefulset -n test my-mysql -o yaml | grep imagePullPolicy
    

後續步驟

• 進一步瞭解如何安裝 Config Sync。