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 3.8.0 이상을 설치합니다. 이전 버전의 Helm에서는 OCI 형식의 차트가 실험용 기능으로 지원됩니다.
클러스터에서 워크로드 아이덴티티를 사용 설정합니다.

제한사항

정보 소스의 값만 변경하여 구성에서 변경할 수 없는 필드를 변경할 수 없습니다. 변경할 수 없는 필드를 업데이트해야 하는 경우 먼저 정보 소스를 변경한 후 클러스터에서 객체를 수동으로 삭제합니다. 그러면 구성 동기화는 새 필드 값으로 객체를 다시 만들 수 있습니다.
다음 Helm 차트는 작업이 포함되어 있으며 구성 동기화에서 배포에 사용하지 않는 것이 좋습니다.
- secrets-store-csi-driver
- cert-manager
구성 동기화에 작업을 사용하지 않는 것을 권장하는 이유는 구성 동기화로 작업 관리 방지를 참조하세요.

Artifact Registry 저장소 만들기

이 섹션에서는 Artifact Registry 저장소를 만듭니다. Artifact Registry 저장소 만들기에 대한 자세한 내용은 저장소 만들기를 참조하세요.

Artifact Registry API를 사용 설정합니다.

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

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_LENGTH는 REPO_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 서비스 계정 사용

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

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로 푸시합니다.

공개 Helm 저장소에서 mysql-9.3.1.tgz 패키지를 검색하고 로컬로 다운로드합니다.
```
helm pull mysql --repo https://charts.bitnami.com/bitnami --version 9.3.1
```
액세스 토큰으로 인증
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은 액세스 토큰을 가져오는 명령어입니다. 액세스 토큰은 인증에 사용되는 비밀번호입니다. 액세스 토큰을 사용한 인증은 가장 안전한 인증 방법입니다.

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 저장소 구성을 참조하세요.

값

고유한 이름으로 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 저장소 구성을 참조하세요.

RootSync 객체를 적용합니다.
```
kubectl apply -f ROOT_SYNC_NAME.yaml
```

구성 동기화가 이미지에서 동기화되는지 확인합니다.

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

고유한 이름으로 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입니다.

값을 사용하여 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입니다.

ConfigMap 객체를 적용합니다.
```
kubectl apply -f CONFIGMAP_NAME.yaml
```
RootSync 객체를 적용합니다.
```
kubectl apply -f ROOT_SYNC_NAME.yaml
```