Helm

Argo CD에서 Helm 차트를 사용하는 방법을 다룹니다. Helm은 helm template으로 차트를 부풀리는 데만 사용되고, 애플리케이션의 수명주기는 Helm이 아닌 Argo CD가 처리합니다. 선언적 구문, 값 파일, 헬름 파라미터, 훅, 플러그인 등을 다룹니다.

출처: 문서

본문

Helm

선언적(Declarative)

Helm 차트는 UI 또는 선언적 GitOps 방식으로 설치할 수 있습니다. Helm은 helm template으로 차트를 부풀리는 데만 사용됩니다. 애플리케이션의 수명주기는 Helm이 아닌 Argo CD가 처리합니다. 예시:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: sealed-secrets
  namespace: argocd
spec:
  project: default
  source:
    chart: sealed-secrets
    repoURL: https://bitnami-labs.github.io/sealed-secrets
    targetRevision: 1.16.1
    helm:
      releaseName: sealed-secrets
  destination:
    server: "https://kubernetes.default.svc"
    namespace: kubeseal

공개 OCI helm 차트를 사용하는 또 다른 예시:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: nginx
spec:
  project: default
  source:
    chart: nginx
    repoURL: registry-1.docker.io/bitnamicharts  # note: the oci:// syntax is not included.
    targetRevision: 15.9.0
  destination:
    name: "in-cluster"
    namespace: nginx

참고: Helm을 사용할 때 값을 제공하는 여러 방법이 있습니다. 우선 순위는 parameters > valuesObject > values > valueFiles > helm repository values.yaml입니다. 더 상세한 예시는 Value precedence에서 확인하세요.

Helm의 Declarative Setup 섹션에는 프라이빗 Helm 저장소와 프라이빗 OCI 레지스트리 구성 방법에 대한 추가 정보가 있습니다.

값 파일(Values Files)

Helm은 파라미터를 파생하기 위해 다른 또는 여러 "values.yaml" 파일을 사용할 수 있습니다. 대체 또는 여러 값 파일은 --values 플래그로 지정할 수 있습니다. 여러 값 파일을 지원하기 위해 플래그를 반복할 수 있습니다:

argocd app set helm-guestbook --values values-production.yaml

참고: Argo CD v2.6 이전에는 값 파일이 Helm 차트와 같은 git 저장소에 있어야 합니다. 파일은 다른 위치에 있을 수 있으며, 이 경우 Helm 차트 루트 디렉터리를 기준으로 하는 상대 경로로 접근할 수 있습니다. v2.6부터 값 파일은 애플리케이션용 다중 소스를 활용해 Helm 차트와 다른 저장소에서 가져올 수 있습니다.

선언적 구문에서:

source:
  helm:
    valueFiles:
    - values-production.yaml

템플릿 확장 중 Helm에 존재하지 않는 값 파일이 전달되면 오류가 발생합니다. 누락된 값 파일은 --ignore-missing-value-files로 무시(즉, Helm에 전달하지 않음)할 수 있습니다. 이는 Application Sets로 default/override 패턴을 구현할 때 특히 유용합니다.

선언적 구문에서:

source:
  helm:
    valueFiles:
    - values-common.yaml
    - values-optional-override.yaml
    ignoreMissingValueFiles: true

값 파일의 Glob 패턴

valueFiles 항목에서 glob 패턴을 사용해 여러 파일을 한 번에 일치시킬 수 있습니다. 이는 환경별 override 파일 세트를 미리 알 수 없거나, Application 스펙을 업데이트하지 않고 새 파일을 자동으로 가져오고 싶을 때 유용합니다.

# Single quotes prevent the shell from expanding the glob before Argo CD receives it
argocd app set helm-guestbook --values 'envs/*.yaml'

선언적 구문에서:

source:
  helm:
    valueFiles:
    - envs/*.yaml

지원되는 패턴 구문

Glob 확장은 doublestar 라이브러리를 사용합니다.

패턴	설명
*	단일 디렉터리 수준 내에서 비구분자 문자의 모든 시퀀스와 일치
?	단일 비구분자 문자와 일치
[abc]	괄호 안에 나열된 문자 중 하나와 일치
[a-z]	주어진 범위의 모든 문자와 일치
**	/를 포함한 모든 문자 시퀀스와 일치(디렉터리 수준을 가로질러 재귀)

파일이 Helm에 전달되는 방식

일치하는 각 파일은 확장 후 나타나는 순서대로 별도의 --values <path> 플래그로 helm template에 전달됩니다. 이는 각 파일을 valueFiles에 개별적으로 나열하는 것과 동일합니다. Argo CD는 Helm을 호출하기 전에 확장을 수행합니다.

일치하는 파일은 valueFiles 목록 안에서 제자리에서 확장되고 어휘(알파벳) 순서로 정렬됩니다. Helm은 나중의 --values 플래그에 더 높은 우선 순위를 주므로, 같은 키가 여러 파일에 있을 때 어떤 파일이 이기는지를 어휘 순서가 결정합니다.

envs/
  a.yaml   # sets foo: a-value
  b.yaml   # sets foo: b-value

# envs/*.yaml expands to: envs/a.yaml, envs/b.yaml (lexical order)
# b.yaml is last → foo = "b-value"
source:
  helm:
    valueFiles:
    - envs/*.yaml

valueFiles에 여러 항목이 있으면 항목 간의 상대적 순서는 유지됩니다. Glob 확장은 단일 패턴 내에서만 파일을 재정렬합니다:

valueFiles:
- base.yaml        # passed first
- overrides/*.yaml # expanded in lexical order, passed after base.yaml
- final.yaml       # passed last, highest precedence

**를 사용한 재귀 매칭

**를 사용해 디렉터리 아래의 모든 깊이의 파일을 일치시킵니다:

# envs/**/*.yaml processes each directory's own files before descending into subdirectories,
# with directories and files sorted alphabetically at each level.
#
#   envs/a.yaml           ← 'a' (flat file in envs/)
#   envs/z.yaml           ← 'z' (flat file in envs/, processed before descending)
#   envs/nested/c.yaml    ← inside envs/nested/, processed after envs/ flat files
#
# nested/c.yaml is last → foo = "nested-value"
source:
  helm:
    valueFiles:
    - envs/**/*.yaml

참고: **은 0개 이상의 경로 세그먼트와 일치하므로 envs/**/*.yaml은 envs/ 바로 안의 파일(하위 디렉터리뿐 아니라)도 일치시킵니다. doublestar는 디렉터리를 어휘 순서로 탐색하고 각 디렉터리의 자체 파일을(알파벳순으로) 처리한 다음 하위 디렉터리로 내려갑니다. 이는 알파벳순으로 'n' < 'z'여도 envs/z.yaml이 항상 envs/nested/c.yaml보다 먼저 옴을 의미합니다. 순서를 완전히 명시적이고 예측 가능하게 만들려면 숫자 접두사를 사용하세요(Naming conventions 참조).

glob 패턴에서 환경 변수 사용

빌드 환경 변수는 glob이 평가되기 전에 대체되므로 패턴을 동적으로 구성할 수 있습니다:

source:
  helm:
    valueFiles:
    - envs/$ARGOCD_APP_NAME/*.yaml

이렇게 하면 단일 Application 템플릿이 앱 이름별로 올바른 파일 세트로 확장될 수 있습니다.

다중 소스에서의 glob 패턴

Glob 패턴은 외부 저장소의 값 파일과 함께 작동합니다. $ref 변수가 먼저 외부 저장소의 루트로 해석되고, 나머지 패턴은 그 저장소의 디렉터리 트리 안에서 평가됩니다:

sources:
- repoURL: https://git.example.com/my-configs.git
  ref: configs
- repoURL: https://git.example.com/my-chart.git
  path: chart
  helm:
    valueFiles:
    - $configs/envs/*.yaml  # matches files in the 'my-configs' repo under envs/

명명 규칙(Naming conventions)

파일이 어휘 순서로 정렬되므로 정렬 순서가 병합 우선 순위를 제어합니다. 의도한 순서를 명시적으로 만들기 위해 숫자 접두사를 사용하는 것이 일반적인 패턴입니다:

values/
  00-defaults.yaml
  10-region.yaml
  20-env.yaml
  30-override.yaml

valueFiles:
- values/*.yaml
# expands to: 00-defaults.yaml, 10-region.yaml, 20-env.yaml, 30-override.yaml
# 30-override.yaml has the highest precedence

접두사가 없으면 순수 알파벳 순서가 적용됩니다. 예를 들어 values-10.yaml은 "1" < "9"이므로 어휘상 values-9.yaml보다 앞에 정렬됩니다. 예상치 못하게 정렬되는 이름에 주의하세요.

제약과 한계

경로 경계: glob 패턴은 ../../secrets/*.yaml 같은 패턴도 저장소 루트 밖의 파일을 일치시킬 수 없습니다. Argo CD는 확장 전에 패턴의 기본 경로를 저장소 루트 기준으로 해석하며, 루트를 벗어나는 모든 일치는 거부됩니다.

심볼릭 링크: Argo CD는 경로 경계를 확인할 때 심볼릭 링크를 따릅니다. 저장소 안에 있지만 저장소 루트 밖의 대상을 가리키는 심볼릭 링크는, 심볼릭 링크 자체의 경로가 저장소 안이더라도 거부됩니다. 이 확인은 glob 확장이 생성하는 모든 파일(다중 홉 심볼릭 링크 체인 포함)에 적용됩니다. 저장소 안에 있는 대상으로 해석되는 심볼릭 링크는 허용됩니다.

절대 경로: /로 시작하는 경로는 파일 시스템 루트가 아닌 저장소 루트 기준으로 취급됩니다. 패턴 /configs/*.yaml은 저장소 상단의 configs/ 디렉터리의 파일과 일치합니다.

원격 URL은 glob 확장되지 않습니다: 원격 URL(예: https://raw.githubusercontent.com/.../values.yaml)인 항목은 있는 그대로 Helm에 전달됩니다. URL의 glob 문자는 특별한 의미가 없으며, 리터럴 문자가 URL의 일부가 아니면 URL이 실패하게 됩니다.

CLI의 셸 인용: 셸은 프로그램에 인자를 전달하기 전에 glob 패턴을 확장합니다. 의도하지 않은 셸 확장을 방지하려면 항상 패턴을 인용하세요:

# Correct: single quotes pass the literal pattern to Argo CD
argocd app set myapp --values 'envs/*.yaml'

# Incorrect: the shell expands *.yaml against the current directory first
argocd app set myapp --values envs/*.yaml

중복 제거(Deduplication)

각 파일은 한 번만 포함되지만, 위치를 결정할 때 명시적 항목이 glob 일치보다 우선합니다. 파일이 glob 패턴과 명시적 항목 둘 다에 나타나면 glob은 그것을 건너뛰고 명시적 항목이 선언된 위치에 배치합니다.

valueFiles:
- envs/*.yaml        # expands to base.yaml, prod.yaml — but prod.yaml is listed explicitly below,
                     # so the glob skips it: only base.yaml is added here
- envs/prod.yaml     # placed here at the end, giving it highest Helm precedence

이렇게 하면 glob으로 디렉터리의 모든 파일을 가져온 다음, 특정 파일을 glob 뒤에 명시적으로 나열해 끝(가장 높은 우선 순위)에 고정할 수 있습니다.

같은 파일(같은 절대 경로)이 두 glob 패턴과 일치하면 첫 번째 일치 위치에 포함됩니다. 정확한 경로에 대한 후속 glob 일치는 조용히 무시됩니다. 이름은 같지만 경로가 다른 파일은 서로 다른 파일로 취급되며 항상 포함됩니다.

valueFiles:
- envs/*.yaml        # matches envs/base.yaml, envs/prod.yaml
- envs/**/*.yaml     # envs/prod.yaml already matched above and is skipped;
                     # envs/nested/prod.yaml is a different path and is still included

일치 없음 동작

glob 패턴이 파일과 일치하지 않으면 Argo CD는 Application 스펙을 저장하고(스펙이 유효하지 않은 것이 아니며 파일은 나중에 저장소에 추가될 수 있음) Application에 ComparisonError 조건을 표면화합니다:

values file glob "nonexistent/*.yaml" matched no files

앱은 패턴이 최소 하나의 파일과 일치하거나 패턴이 제거될 때까지 degraded 상태로 유지됩니다. 파일이 저장소에 추가되면 스펙 업데이트는 필요하지 않습니다.

파일과 일치하지 않는 패턴을 오류 대신 조용히 건너뛰려면 glob을 ignoreMissingValueFiles와 결합하세요:

source:
  helm:
    valueFiles:
    - envs/*.yaml
    ignoreMissingValueFiles: true

이는 override 파일이 모든 환경에 존재하지 않을 수 있는 default/override 패턴을 구현할 때 유용합니다.

값(Values)

Argo CD는 source.helm.valuesObject 키를 사용해 Application 매니페스트에 직접 값 파일과 동등한 것을 지원합니다.

source:
  helm:
    valuesObject:
      ingress:
        enabled: true
        path: /
        hosts:
          - mydomain.example.com
        annotations:
          kubernetes.io/ingress.class: nginx
          kubernetes.io/tls-acme: "true"
        labels: {}
        tls:
          - secretName: mydomain-tls
            hosts:
              - mydomain.example.com

대안으로 값은 source.helm.values 키를 사용해 문자열로 전달할 수 있습니다.

source:
  helm:
    values: |
      ingress:
        enabled: true
        path: /
        hosts:
          - mydomain.example.com
        annotations:
          kubernetes.io/ingress.class: nginx
          kubernetes.io/tls-acme: "true"
        labels: {}
        tls:
          - secretName: mydomain-tls
            hosts:
              - mydomain.example.com

Helm 파라미터

Helm은 values.yaml의 모든 값을 재정의하는 파라미터 값을 설정할 수 있습니다. 예를 들어 service.type은 Helm 차트에서 노출되는 일반적인 파라미터입니다:

helm template . --set service.type=LoadBalancer

마찬가지로 Argo CD는 argocd app set 명령으로 values.yaml 파라미터의 값을 -p PARAM=VALUE 형식으로 재정의할 수 있습니다. 예:

argocd app set helm-guestbook -p service.type=LoadBalancer

선언적 구문에서:

source:
  helm:
    parameters:
    - name: "service.type"
      value: LoadBalancer

Helm 값 우선 순위

값 주입은 다음 우선 순위를 가집니다: parameters > valuesObject > values > valueFiles > helm repository values.yaml

즉,

    lowest  -> valueFiles
            -> values
            -> valuesObject
    highest -> parameters

따라서 valuesObject는 values를 이기므로 values는 무시됩니다. 그리고 valuesObject와 values 둘 다 valueFiles를 이깁니다. Parameters는 그것들 모두를 이깁니다.

여러 valueFiles의 우선 순위: 여러 valueFiles가 지정되면 마지막에 나열된 파일이 가장 높은 우선 순위를 가집니다:

valueFiles:
  - values-file-2.yaml
  - values-file-1.yaml

In this case, values-file-1.yaml will override values from values-file-2.yaml.

같은 키가 여러 번 발견되면 마지막 것이 이깁니다. 즉,

e.g. if we only have values-file-1.yaml and it contains

param1: value1
param1: value3000

we get param1=value3000

parameters:
  - name: "param1"
    value: value2
  - name: "param1"
    value: value1

the result will be param1=value1

values: |
  param1: value2
  param1: value5

the result will be param1=value5

참고: valueFiles 또는 values를 사용할 때 차트는 여기 문서화된 대로 기대되는 순서로 병합된 다양한 가능한 소스의 값 세트와 파라미터를 사용해 올바르게 렌더링됩니다. UI에는 파라미터만 표시되는 버그가 있습니다(이 이슈 참조), 즉 완전한 값 세트를 나타내지 않습니다. 우회 방법으로 values/valuesObject 대신 parameters를 사용하면 리소스에 무엇이 사용될지 더 잘 파악할 수 있습니다.

Helm --set-file 지원

helm의 --set-file 인자는 CLI에서 다음 구문으로 사용할 수 있습니다:

argocd app set helm-guestbook --helm-set-file some.key=path/to/file.ext

또는 yaml에서 fileParameters를 사용:

source:
  helm:
    fileParameters:
      - name: some.key
        path: path/to/file.ext

Helm 릴리스 이름

기본적으로 Helm 릴리스 이름은 그것이 속한 Application 이름과 같습니다. 특히 중앙 집중식 Argo CD에서는 그 이름을 잘 재정의하고 싶을 수 있으며, CLI의 release-name 플래그로 가능합니다:

argocd app set helm-guestbook --release-name myRelease

또는 yaml에서 releaseName을 사용:

source:
    helm:
      releaseName: myRelease

경고: 릴리스 이름 재정의에 관한 중요 공지 — Helm 릴리스 이름을 재정의하면 배포하는 차트가 app.kubernetes.io/instance 라벨을 사용할 때 문제를 일으킬 수 있습니다. Argo CD는 추적 목적으로 이 라벨에 Application 이름 값을 주입합니다. 따라서 릴리스 이름을 재정의하면 Application 이름이 릴리스 이름과 같지 않게 됩니다. Argo CD가 라벨을 Application 이름으로 덮어쓰기 때문에 리소스의 일부 셀렉터가 작동을 멈출 수 있습니다. 이를 피하려면 ArgoCD configmap(argocd-cm.yaml)에서 Argo CD가 추적에 다른 라벨을 사용하도록 구성할 수 있습니다. application.instanceLabelKey를 설명하는 줄을 확인하세요.

Helm 훅

Helm 훅은 Argo CD 훅과 유사합니다. Helm에서 훅은 helm.sh/hook 어노테이션으로 주석이 달린 일반 Kubernetes 리소스입니다.

Argo CD는 Helm 어노테이션을 Argo CD 자체 훅 어노테이션에 매핑하여 많은(대부분?) Helm 훅을 지원합니다. 이것은 어노테이션 호환성이며, 훅 수명주기 의미가 Helm과 동일하다는 보장은 아닙니다:

Helm 어노테이션	참고
helm.sh/hook: crd-install	일반 Argo CD CRD 처리와 동등한 것으로 지원됨.
helm.sh/hook: pre-delete	argocd.argoproj.io/hook: PreDelete와 동등한 것으로 지원됨
helm.sh/hook: pre-rollback	지원 안 함. Helm stable에서 사용된 적 없음.
helm.sh/hook: pre-install	argocd.argoproj.io/hook: PreSync와 동등한 것으로 지원됨.
helm.sh/hook: pre-upgrade	argocd.argoproj.io/hook: PreSync와 동등한 것으로 지원됨.
helm.sh/hook: post-upgrade	argocd.argoproj.io/hook: PostSync와 동등한 것으로 지원됨.
helm.sh/hook: post-install	argocd.argoproj.io/hook: PostSync와 동등한 것으로 지원됨.
helm.sh/hook: post-delete	argocd.argoproj.io/hook: PostDelete와 동등한 것으로 지원됨.
helm.sh/hook: post-rollback	지원 안 함. Helm stable에서 사용된 적 없음.
helm.sh/hook: test-success	지원 안 함. Argo CD에 동등물 없음.
helm.sh/hook: test-failure	지원 안 함. Argo CD에 동등물 없음.
helm.sh/hook-delete-policy	지원됨. 정리는 여전히 Argo CD sync 의미를 따르며, 이는 Helm의 훅 이벤트 수명주기와 다를 수 있음. argocd.argoproj.io/hook-delete-policy 참조.
helm.sh/hook-delete-timeout	지원 안 함. Helm stable에서 사용된 적 없음
helm.sh/hook-weight	argocd.argoproj.io/sync-wave와 동등한 것으로 지원됨.
helm.sh/resource-policy: keep	argocd.argoproj.io/sync-options: Delete=false와 동등한 것으로 지원됨.

지원되지 않는 훅은 무시됩니다. Argo CD에서 훅은 kubectl create가 아닌 kubectl apply로 생성됩니다. 즉, 훅이 이름이 있고 이미 존재한다면 before-hook-creation으로 주석을 달지 않는 한 변경되지 않습니다.

경고: Helm 훅 + ArgoCD 훅 — Argo CD 훅을 정의하면 모든 Helm 훅이 무시됩니다.

경고: 'install' vs 'upgrade' vs 'sync' — Argo CD는 처음 "install"을 실행하는지 "upgrade"인지 알 수 없습니다. 모든 작업은 "sync"입니다. 즉, 기본적으로 pre-install과 pre-upgrade가 있는 앱은 해당 훅이 동시에 실행됩니다.

참고: 훅 삭제 의미는 Helm과 다릅니다 — Helm 훅 어노테이션은 Argo CD 훅에 매핑되지만, 삭제 정책은 여전히 Argo CD sync 단계와 sync 결과 의미를 사용해 평가됩니다. 이는 Helm의 훅 이벤트별 수명주기와 다릅니다. 특히 ServiceAccount 같은 수동 리소스는 Job이나 Workflow 같은 Kubernetes 완료 상태가 없으므로, hook-succeeded / HookSucceeded가 Helm에서 관찰하는 시점과 다른 시점에 평가될 수 있습니다.

훅 팁

훅을 멱등(idempotent)하게 만드세요.
pre-install과 post-install에 hook-weight: "-1"로 주석을 달면 업그레이드 훅보다 먼저 성공까지 실행됩니다.
pre-upgrade와 post-upgrade에 hook-delete-policy: before-hook-creation으로 주석을 달면 모든 sync에서 실행됩니다.

Argo 훅과 Helm 훅에 대해 더 읽어보세요.

랜덤 데이터(Random Data)

Helm 템플릿은 차트 렌더링 중 randAlphaNum 함수로 랜덤 데이터를 생성할 수 있습니다. charts 저장소의 많은 helm 차트가 이 기능을 사용합니다. 예를 들어 다음은 redis helm 차트의 secret입니다:

data:
  {{- if .Values.password }}
  redis-password: {{ .Values.password | b64enc | quote }}
  {{- else }}
  redis-password: {{ randAlphaNum 10 | b64enc | quote }}
  {{- end }}

Argo CD 애플리케이션 컨트롤러는 주기적으로 Git 상태와 라이브 상태를 비교하며 helm template <CHART> 명령을 실행해 helm 매니페스트를 생성합니다. 랜덤 값은 비교할 때마다 다시 생성되므로 randAlphaNum 함수를 사용하는 모든 애플리케이션은 항상 OutOfSync 상태입니다. 이는 values.yaml에서 값을 명시적으로 설정하거나 argocd app set 명령으로 값을 재정의해 각 비교 사이에 값이 안정적으로 유지되게 하면 완화할 수 있습니다. 예:

argocd app set redis -p password=abc123

빌드 환경

Helm 앱은 파라미터 대체를 통해 표준 빌드 환경에 접근할 수 있습니다.

예를 들어 CLI를 통해:

argocd app create APPNAME \
  --helm-set-string 'app=${ARGOCD_APP_NAME}'

또는 선언적 구문으로:

  spec:
    source:
      helm:
        parameters:
        - name: app
          value: $ARGOCD_APP_NAME

Helm 값 파일 경로에 빌드 환경 변수를 사용하는 것도 가능합니다:

  spec:
    source:
      helm:
        valueFiles:
        - values.yaml
        - myprotocol://somepath/$ARGOCD_APP_NAME/$ARGOCD_APP_REVISION

Helm 플러그인

Argo CD는 사용하는 클라우드 제공자와 Helm 플러그인 종류에 대해 중립적이므로 ArgoCD 이미지에는 플러그인이 제공되지 않습니다.

하지만 때로는 커스텀 플러그인을 사용하고 싶을 수 있습니다. 예를 들어 Helm 차트를 저장하기 위해 Google Cloud Storage나 Amazon S3 스토리지를 사용하고 싶을 수 있습니다. 예: https://github.com/hayorov/helm-gcs 에서 gs:// 프로토콜로 Helm 차트 저장소에 접근할 수 있습니다. 커스텀 플러그인을 설치하는 방법은 두 가지입니다: ArgoCD 컨테이너 이미지를 수정하거나 Kubernetes initContainer를 사용하는 것입니다.

ArgoCD 컨테이너 이미지 수정

이 플러그인을 사용하는 한 가지 방법은 플러그인이 포함된 자체 ArgoCD 이미지를 준비하는 것입니다.

예시 Dockerfile:

FROM argoproj/argocd:v1.5.7

USER root
RUN apt-get update && \
    apt-get install -y \
        curl && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

USER argocd

ARG GCS_PLUGIN_VERSION="0.3.5"
ARG GCS_PLUGIN_REPO="https://github.com/hayorov/helm-gcs.git"

RUN helm plugin install ${GCS_PLUGIN_REPO} --version ${GCS_PLUGIN_VERSION}

ENV HELM_PLUGINS="/home/argocd/.local/share/helm/plugins/"

ArgoCD가 플러그인을 올바르게 찾으려면 HELM_PLUGINS 환경 변수가 필요합니다.

빌드 후 ArgoCD 설치에 커스텀 이미지를 사용하세요.

initContainers 사용

또 다른 옵션은 Kubernetes initContainers로 Helm 플러그인을 설치하는 것입니다. 일부 사용자는 ArgoCD 컨테이너 이미지 자체 버전을 유지하는 것보다 이 패턴을 선호합니다.

아래는 공식 ArgoCD helm 차트로 ArgoCD를 설치할 때 Helm 플러그인을 추가하는 방법의 예시입니다:

repoServer:
  volumes:
    - name: gcp-credentials
      secret:
        secretName: my-gcp-credentials
  volumeMounts:
    - name: gcp-credentials
      mountPath: /gcp
  env:
    - name: HELM_CACHE_HOME
      value: /helm-working-dir
    - name: HELM_CONFIG_HOME
      value: /helm-working-dir
    - name: HELM_DATA_HOME
      value: /helm-working-dir
  initContainers:
    - name: helm-gcp-authentication
      image: alpine/helm:3.16.1
      volumeMounts:
        - name: helm-working-dir
          mountPath: /helm-working-dir
        - name: gcp-credentials
          mountPath: /gcp
      env:
        - name: HELM_CACHE_HOME
          value: /helm-working-dir
        - name: HELM_CONFIG_HOME
          value: /helm-working-dir
        - name: HELM_DATA_HOME
          value: /helm-working-dir
      command: [ "/bin/sh", "-c" ]
      args:
        - apk --no-cache add curl;
          helm plugin install https://github.com/hayorov/helm-gcs.git;
          helm repo add my-gcs-repo gs://my-private-helm-gcs-repository;
          chmod -R 777 $HELM_DATA_HOME;

Helm 버전

이 필드는 과거에 Helm 2에서 Helm 3으로의 전환 기간 동안 사용되었습니다. Helm 2가 EOL이 되기 전, Argo CD는 Helm 바이너리(v2와 v3) 둘 다와 함께 제공되었고 사용자는 이 필드를 설정해 Argo CD가 차트를 렌더링하는 데 사용할 Helm 바이너리를 지정할 수 있었습니다.

Helm 2가 EOL이 된 이후로 이 필드는 더 이상 구성할 필요가 없습니다. 하위 호환성 용도로만 존재합니다. Argo CD(3.5 버전부터)에서 차트 렌더링에 사용되는 유일한 Helm 바이너리는 v4입니다.

Helm 애플리케이션에 과거에 다음 설정이 있었다면:

spec:
  source:
    helm:
      version: v3

이 필드를 업데이트하거나 제거할 필요는 없으며 그대로 둘 수 있습니다.

Helm --pass-credentials

Helm은 v3.6.1부터 저장소와 다른 도메인에서 제공되는 차트를 다운로드할 때 저장소 자격 증명을 보내지 않습니다.

필요하다면 CLI에서 helm-pass-credentials 플래그를 설정해 모든 도메인에 자격 증명을 전달하도록 선택할 수 있습니다:

argocd app set helm-guestbook --helm-pass-credentials

또는 선언적 구문:

spec:
  source:
    helm:
      passCredentials: true

Helm --skip-crds

Helm은 CRD가 존재하지 않으면 기본적으로 crds 폴더에 커스텀 리소스 정의를 설치합니다. 자세한 내용은 CRD best practices를 참조하세요.

필요하다면 CLI의 helm-skip-crds 플래그로 CRD 설치 단계를 건너뛸 수 있습니다:

argocd app set helm-guestbook --helm-skip-crds

또는 선언적 구문:

spec:
  source:
    helm:
      skipCrds: true

Helm --skip-schema-validation

Helm은 values.schema.json 파일을 사용해 values.yaml 파일을 검증합니다. 자세한 내용은 Schema files를 참조하세요.

필요하다면 CLI의 helm-skip-schema-validation 플래그로 스키마 검증 단계를 건너뛸 수 있습니다:

argocd app set helm-guestbook --helm-skip-schema-validation

또는 선언적 구문:

spec:
  source:
    helm:
      skipSchemaValidation: true

Helm --skip-tests

기본적으로 Helm은 템플릿 렌더링 시 테스트 매니페스트를 포함합니다. Argo CD는 현재 Helm 테스트 훅을 포함한 Argo CD가 지원하지 않는 훅이 있는 매니페스트를 건너뜁니다. 이 기능은 많은 테스트 사용 사례를 다루지만 --skip-tests와 완전히 일치하지는 않으므로 --skip-tests 옵션을 사용할 수 있습니다.

필요하다면 CLI의 helm-skip-tests 플래그로 테스트 매니페스트 설치 단계를 건너뛸 수 있습니다:

argocd app set helm-guestbook --helm-skip-tests

또는 선언적 구문:

spec:
  source:
    helm:
      skipTests: true # or false

Helm

Helm

본문

Helm

선언적(Declarative)

값 파일(Values Files)

값 파일의 Glob 패턴

지원되는 패턴 구문

파일이 Helm에 전달되는 방식

**를 사용한 재귀 매칭

glob 패턴에서 환경 변수 사용

다중 소스에서의 glob 패턴

명명 규칙(Naming conventions)

제약과 한계

중복 제거(Deduplication)

일치 없음 동작

값(Values)

Helm 파라미터

Helm 값 우선 순위

Helm --set-file 지원

Helm 릴리스 이름

Helm 훅

훅 팁

랜덤 데이터(Random Data)

빌드 환경

Helm 플러그인

ArgoCD 컨테이너 이미지 수정

initContainers 사용

Helm 버전

Helm --pass-credentials

Helm --skip-crds

Helm --skip-schema-validation

Helm --skip-tests

더 알아보기 (Learn more)