從 Artifact Registry 同步 Helm 資訊套件

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

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

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

事前準備

限制

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

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

    如要進一步瞭解為何不建議搭配使用 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 相同。如果您使用 GKE 適用的 Fleet 工作負載身分聯盟,這個 ID 是叢集註冊的 Fleet 專案 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_LENGTHREPO_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 存放區的設定」。

  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 控制台或 Google Cloud CLI 安裝 Config Sync,請選擇 root-sync 以外的名稱。

    在本範例中,Helm 範本的資源包含 namespace: {{ .Release.Namespace }},因此 Helm 範本會部署在 test 命名空間中。

    您可以使用 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
    

    更改下列內容:

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

    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
    

後續步驟