Artifact Registry から Helm チャートを同期する

このページでは、Helm チャートを作成して Artifact Registry のリポジトリに push することで、Artifact Registry から Helm チャートを同期する方法について説明します。また、Helm リポジトリからチャートを同期するサンプル構成も含まれています。

Helm リポジトリから同期するように Config Sync を構成できます。Google Cloud で推奨の Helm リポジトリである Artifact Registry に Helm チャートを保存できます。この機能を使用するには、RootSync API と RepoSync API を有効にする必要があります。Config Sync は helm template を使用して Helm チャートをレンダリングするため、完全な Helm ライフサイクル管理はサポートしていません。

バンドルされている Helm と Kustomize のバージョンに、Config Sync のバージョンと、それにバンドルされている Kustomize と Helm のバージョンのリストが示されています。

始める前に

• Helm 3.8.0 以降をインストールします。以前のバージョンの Helm では、OCI 形式のチャートに対するサポートは試験運用版です。
• クラスタで Workload Identity Federation for GKE を有効にします。

制限事項

• 信頼できる情報源の値を変更するだけでは、構成ファイル内の変更不可フィールドを変更することはできません。変更不可フィールドを更新する必要がある場合は、まず信頼できるソースで変更を行い、クラスタ内のオブジェクトを手動で削除します。Config Sync は、新しいフィールド値を使用してオブジェクトを再作成します。

• 次の Helm チャートには Job が含まれているため、Config Sync でのデプロイにはおすすめしません。

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

  Config Sync での Job の使用が推奨されない理由について詳しくは、Config Sync を使用したジョブの管理を回避するをご覧ください。

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: Reconciler の Kubernetes サービス アカウント。
  • ルート リポジトリで、RootSync 名が root-sync の場合は、root-reconciler を追加します。それ以外の場合は、root-reconciler-ROOT_SYNC_NAME を追加します。
  • Namespace リポジトリで、RepoSync 名が repo-sync の場合は ns-reconciler-NAMESPACE を追加します。それ以外の場合は、ns-reconciler-NAMESPACE-REPO_SYNC_NAME-REPO_SYNC_NAME_LENGTH を追加します。ここで、REPO_SYNC_NAME_LENGTH は REPO_SYNC_NAME の文字数です。

読み取り権限を付与する

クラスタで Config Sync バージョンが 1.17.2 以降の場合、Kubernetes サービス アカウントを使用して Artifact Registry に認証できます。それ以外の場合は、認証に Google サービス アカウントを使用します。

Kubernetes サービス アカウントの使用

Workload Identity Federation for GKE プールを使用して、Artifact Registry 読み取り（roles/artifactregistry.reader）IAM ロールを 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

Google サービス アカウントの使用

1. Google サービス アカウントに Artifact Registry 読み取り（roles/artifactregistry.reader）IAM ロールを付与します。

   gcloud artifacts repositories add-iam-policy-binding AR_REPO_NAME \
      --location=AR_REGION \
      --member=serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
      --role=roles/artifactregistry.reader \
      --project=PROJECT_ID
   

2. Kubernetes サービス アカウントと Google サービス アカウントの間に IAM ポリシー バインディングを作成します。

   gcloud iam service-accounts add-iam-policy-binding \
      --role roles/iam.workloadIdentityUser \
      --member "serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
      GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
      --project=PROJECT_ID
   

Helm チャートを Artifact Registry リポジトリに push する

このセクションでは、一般公開の Helm チャートをダウンロードして、Artifact Registry に push します。

1. mysql-9.3.1.tgz パッケージを一般公開の Helm リポジトリから取得し、ローカルにダウンロードします。

   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 に push します。

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

Helm チャートから同期するように Config Sync を構成する

このセクションでは、RootSync オブジェクトを作成し、Helm チャートから同期するように Config Sync を構成します。

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
       # The k8sserviceaccount auth type is available in version 1.17.2 and
       # later. Use "gcpserviceaccount" if using an older version.
       # auth: gcpserviceaccount
       # gcpServiceAccountEmail: GSA_NAME@PROJECT_ID.iam.gserviceaccount.com
       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 以外の名前を選択します。

   この例では、リソースのテンプレートに namespace: {{ .Release.Namespace }} が含まれているため、Helm チャートが test 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
       # The k8sserviceaccount auth type is available in version 1.17.2 and
       # later. Use "gcpserviceaccount" if using an older version.
       # auth: gcpserviceaccount
       # gcpServiceAccountEmail: GSA_NAME@PROJECT_ID.iam.gserviceaccount.com
       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 オブジェクトを作成します。

   注: ConfigMap は変更できません。また、これを参照する RootSync または RepoSync と同じ Namespace に存在する必要があります。

   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 を作成し、新しい ConfigMap を参照するように RootSync または RepoSync 仕様の spec.helm.valuesFileRefs を更新する必要があります。新しい 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. 新しい ConfigMap を参照するように 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
       # The k8sserviceaccount auth type is available in version 1.17.2 and
       # later. Use "gcpserviceaccount" if using an older version.
       # auth: gcpserviceaccount
       # gcpServiceAccountEmail: GSA_NAME@PROJECT_ID.iam.gserviceaccount.com
       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 のインストールについて学習する。