Artifact Registry에서 Helm 차트 동기화

이 페이지에서는 Helm 차트를 만들고 Artifact Registry의 저장소에 푸시하여 Artifact Registry에서 Helm 차트를 동기화하는 방법을 설명합니다. 또한 Helm 저장소의 차트를 동기화하는 샘플 구성도 포함되어 있습니다.

Helm 저장소에서 동기화하도록 구성 동기화를 구성할 수 있습니다. Google Cloud에 권장되는 Helm 저장소인 Artifact Registry에 Helm 차트를 저장할 수 있습니다. 이 기능을 사용하려면 RootSync 및 RepoSync API를 사용 설정해야 합니다. 구성 동기화는 helm template을 사용하여 Helm 차트를 렌더링하므로 전체 Helm 수명 주기 관리를 지원하지 않습니다.

번들 Helm 및 Kustomize 버전은 구성 동기화의 해당 버전과 함께 번들로 제공되는 Kustomize 및 Helm 버전을 나열합니다.

시작하기 전에

제한사항

  • 정보 소스의 값만 변경하여 구성에서 변경할 수 없는 필드를 변경할 수 없습니다. 변경할 수 없는 필드를 업데이트해야 하는 경우 먼저 정보 소스를 변경한 후 클러스터에서 객체를 수동으로 삭제합니다. 그러면 구성 동기화는 새 필드 값으로 객체를 다시 만들 수 있습니다.

  • 다음 Helm 차트에는 작업이 포함되어 있으며 구성 동기화에서 배포에 사용하지 않는 것이 좋습니다.

    구성 동기화에 작업을 사용하지 않는 것을 권장하는 이유는 구성 동기화로 작업 관리 방지를 참조하세요.

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 워크로드 아이덴티티를 사용하는 경우 PROJECT_ID와 동일합니다. Fleet 워크로드 아이덴티티를 사용하는 경우 클러스터가 등록된 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의 문자 수입니다.

읽기 권한 부여

클러스터의 구성 동기화 버전이 1.17.2 이상인 경우 Kubernetes 서비스 계정을 사용하여 Artifact Registry에 인증할 수 있습니다. 그렇지 않으면 인증에 Google 서비스 계정을 사용합니다.

Kubernetes 서비스 계정 사용

워크로드 아이덴티티 풀이 있는 Kubernetes 서비스 계정에 Artifact Registry 리더(roles/artifactregistry.reader) IAM 역할을 부여합니다.

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. Artifact Registry 리더(roles/artifactregistry.reader) IAM 역할을 Google 서비스 계정에 부여합니다.

    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 저장소에 푸시

이 섹션에서는 공개 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/Mac OS

    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
    

Helm 차트에서 동기화하도록 구성 동기화 구성

이 섹션에서는 RootSync 객체를 만들고 Helm 차트에서 동기화하도록 구성 동기화를 구성합니다.

Helm 차트의 기본값을 재정의하려면 spec.helm.values 필드에 값을 지정하거나 spec.helm.valuesFileRefs 필드를 사용하여 ConfigMap에 대한 참조를 추가하면 됩니다(구성 동기화 버전 1.16.0 이상). 선택적 필드에 대한 자세한 내용은 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
        # 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 Console 또는 Google Cloud CLI를 사용하여 구성 동기화를 설치한 경우 root-sync 이외의 이름을 선택합니다.

    이 예시에서 Helm 차트는 리소스에 해당 템플릿의 namespace: {{ .Release.Namespace }}이 포함되어 있으므로 test 네임스페이스에 배포됩니다.

    helm.values를 사용하여 기본값을 재정의할 수 있습니다. 선택적 필드에 대한 자세한 내용은 Helm 저장소 구성을 참조하세요.

  2. RootSync 객체를 적용합니다.

    kubectl apply -f ROOT_SYNC_NAME.yaml
    
  3. 구성 동기화가 이미지에서 동기화되는지 확인합니다.

    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를 사용하여 구성 동기화를 설치한 경우 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. 구성 동기화가 이미지에서 동기화되는지 확인합니다.

    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 사양에서 새 ConfigMap을 가리키도록 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. 구성 동기화가 이미지에서 동기화되는지 확인합니다.

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

    또한 클러스터의 동기화된 리소스 중 하나에서 imagePullPolicy를 확인하여 업데이트된 ConfigMap의 새 값이 차트 렌더링에 사용되었는지 확인할 수 있습니다.

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

다음 단계