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

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

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

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

事前準備

  1. 安裝 Google Cloud CLI。

  2. 設定 gcloud CLI，使用您的聯合身分。

    詳情請參閱「 使用聯合身分登入 gcloud CLI」。

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

    gcloud init

  4. 建立或選取 Cloud de Confiance 專案。

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

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

    • 建立 Cloud de Confiance 專案：

      gcloud projects create PROJECT_ID

      將 PROJECT_ID 替換為要建立的專案名稱。 Cloud de Confiance

    • 選取您建立的 Cloud de Confiance 專案：

      gcloud config set project PROJECT_ID

      將 PROJECT_ID 替換為 Cloud de Confiance 專案名稱。

  5. 確認 Cloud de Confiance 專案已啟用計費功能。

  6. 如果尚未啟用 GKE、Config Sync 和 Artifact Registry API，請啟用：

    啟用 API 時所需的角色

    如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「服務使用管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

    gcloud services enable container.googleapis.com  anthosconfigmanagement.googleapis.com  artifactregistry.googleapis.com
  7. 建立或存取符合 Config Sync 需求的叢集，並使用最新版 Config Sync。
  8. 安裝 nomos CLI 或升級至最新版本。
  9. 安裝 Helm 3.8.0 以上版本。 在舊版 Helm 中，以 OCI 格式支援圖表是實驗功能。
  10. 在叢集上啟用 Workload Identity Federation for GKE。

限制

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

  • 下列 Helm 資訊圖表包含 Job，不建議透過 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_NUMBER：如果您使用 GKE Workload Identity Federation for GKE，這與 PROJECT_ID 的專案編號相同。如果您使用機群適用的 Workload Identity Federation for GKE，這是叢集註冊的機群專案編號。
  • FLEET_HOST_PROJECT_ID：如果您使用 GKE Workload Identity Federation for GKE，這與 PROJECT_ID 相同。如果您使用機群 Workload Identity Federation for GKE，這是叢集註冊的機群專案 ID。
  • KUBERNETES_SERVICEACCOUNT：調解器的 Kubernetes ServiceAccount：
    • 如果是根存放區，且 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 中的字元數。

授予讀取的權限

將 Artifact Registry 讀取者角色 (roles/artifactregistry.reader) 授予存放區的 Kubernetes 服務帳戶：

gcloud artifacts repositories add-iam-policy-binding AR_REPO_NAME \
    --location=AR_REGION \
    --member="principal://iam.googleapis.com/projects/FLEET_HOST_PROJECT_NUMBER/locations/global/workloadIdentityPools/FLEET_HOST_PROJECT_ID.s3ns.svc.id.goog/subject/ns/config-management-system/sa/KUBERNETES_SERVICEACCOUNT" \
    --role=roles/artifactregistry.reader \
    --project=PROJECT_ID \
    --condition=None

將 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 個字元。如果您使用 Cloud de Confiance 控制台或 Google Cloud CLI 安裝 Config Sync，請選擇 root-sync 以外的名稱。

    在本範例中，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

    更改下列內容：

    • ROOT_SYNC_NAME：RootSync 物件的名稱。名稱在叢集中不得重複，且長度不得超過 26 個字元。如果您是使用 Cloud de Confiance 控制台或 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

後續步驟