소개

Helm은 쿠버네티스(Kubernetes)를 위한 패키지 매니저입니다. 복잡한 쿠버네티스 애플리케이션을 정의, 설치 및 업그레이드하는 과정을 단순화해줍니다. 신입 개발자가 쿠버네티스 환경에서 애플리케이션을 효과적으로 관리하려면 Helm 사용법을 익히는 것이 중요합니다. 이 가이드는 Helm의 핵심 명령어와 함께 개발, 배포, 운영 단계에서 유용한 팁들을 제공하여 신입 개발자들이 Helm을 능숙하게 사용할 수 있도록 돕는 것을 목표로 합니다.

Helm 기본

Helm 설치 확인 및 버전 정보

Helm CLI가 올바르게 설치되었는지 확인합니다.

helm version

이 명령어는 클라이언트의 버전 정보를 보여줍니다. 만약 Tiller (Helm v2)를 사용 중이라면 서버 버전 정보도 함께 표시됩니다. Helm v3부터는 Tiller가 제거되어 클라이언트 측에서만 작동합니다.

기본 명령어 도움말

Helm은 각 명령어에 대한 상세한 도움말을 제공합니다.

helm --help # 전체 명령어 목록
helm <command> --help # 특정 명령어에 대한 도움말 (예: helm install --help)

Helm 차트(Chart) 개발 가이드

Helm 차트는 쿠버네티스 리소스를 정의하는 파일들의 모음입니다. 애플리케이션을 패키징하는 기본 단위입니다.

새로운 차트 생성

helm create <chart-name>

예를 들어, my-app이라는 이름의 차트를 생성하려면 다음 명령어를 사용합니다.

helm create my-app

이 명령어는 my-app/ 디렉토리 내에 기본적인 차트 구조(디렉토리 및 파일)를 생성합니다.

  • Chart.yaml: 차트에 대한 정보(이름, 버전, 설명 등)를 담고 있습니다.
  • values.yaml: 차트의 기본 설정 값을 정의합니다. 이 값들은 템플릿에서 사용되며, 설치 시 오버라이드될 수 있습니다.
  • charts/: 의존하는 다른 차트들(서브차트)을 저장하는 디렉토리입니다.
  • templates/: 쿠버네티스 매니페스트 템플릿 파일들을 저장하는 디렉토리입니다. NOTES.txt도 여기에 포함되어 릴리스 후 사용자에게 안내 메시지를 제공합니다.

차트 문법 검사 (Linting)

차트의 문법이나 구조가 올바른지 확인합니다.

helm lint <chart-path>

예:

helm lint ./my-app

차트 템플릿 렌더링 테스트 (Dry Run)

실제로 클러스터에 배포하지 않고, values.yaml 파일과 사용자가 제공하는 값을 기반으로 템플릿이 어떻게 렌더링되는지 확인할 수 있습니다. 디버깅에 매우 유용합니다.

helm install <release-name> <chart-path> --dry-run --debug

예:

helm install my-release ./my-app --dry-run --debug

--debug 플래그는 렌더링된 YAML 파일을 출력해줍니다. 특정 값으로 테스트하려면 --set 또는 -f (values 파일 지정) 옵션을 사용합니다.

helm install my-release ./my-app --dry-run --debug --set replicaCount=3
helm install my-release ./my-app --dry-run --debug -f my-values.yaml

차트 패키징

개발이 완료된 차트는 배포하거나 공유하기 위해 .tgz 파일로 패키징할 수 있습니다.

helm package <chart-path>

예:

helm package ./my-app

이 명령어는 my-app-0.1.0.tgz (Chart.yaml의 버전 정보에 따라 다름)와 같은 파일을 생성합니다.

차트 의존성 관리

Chart.yaml 파일의 dependencies 섹션에 서브차트 의존성을 정의할 수 있습니다.

# Chart.yaml
dependencies:
  - name: nginx
    version: "15.x.x"
    repository: "https://charts.bitnami.com/bitnami"
  - name: mariadb
    version: "14.x.x"
    repository: "https://charts.bitnami.com/bitnami"
    condition: mariadb.enabled # 조건부 활성화

의존성 업데이트 및 다운로드:

helm dependency update <chart-path> # Chart.lock 파일 업데이트 및 charts/ 디렉토리에 다운로드
helm dependency build <chart-path>  # Chart.lock 기반으로 charts/ 디렉토리에 다운로드
helm dependency list <chart-path>   # 의존성 목록 확인

Helm 배포 가이드

작성하고 테스트한 차트를 쿠버네티스 클러스터에 배포합니다.

Helm 리포지토리 관리

Helm 리포지토리는 패키징된 차트를 저장하고 공유하는 곳입니다.

  • 리포지토리 추가:

    helm repo add <repo-name> <repo-url>

    예: Bitnami 리포지토리 추가.

    helm repo add bitnami https://charts.bitnami.com/bitnami

  • 리포지토리 목록 보기:

    helm repo list

  • 리포지토리 정보 업데이트: 로컬에 캐시된 리포지토리의 최신 차트 정보를 가져옵니다.

    helm repo update

  • 리포지토리에서 차트 검색:

    helm search repo <keyword>

    예: nginx 검색.

    helm search repo nginx

    특정 버전까지 검색하려면 --versions 플래그를 사용합니다. --devel은 개발 버전도 포함합니다.

    helm search repo bitnami/nginx --versions

차트 설치 (helm install)

리포지토리의 차트 또는 로컬 경로의 차트를 클러스터에 설치합니다. 설치된 차트의 인스턴스를 ‘릴리스(release)’라고 합니다.

  • 리포지토리 차트 설치:

    helm install <release-name> <repo-name>/<chart-name>

    예: my-nginx라는 릴리스 이름으로 Bitnami의 nginx 차트 설치.

    helm install my-nginx bitnami/nginx

  • 로컬 차트 설치:

    helm install <release-name> <path-to-chart-directory-or-tgz>

    예:

    helm install my-app-release ./my-app
helm install my-app-release ./my-app-0.1.0.tgz

  • 특정 네임스페이스에 설치: --namespace 또는 -n 플래그를 사용합니다. 네임스페이스가 없으면 Helm이 생성하려고 시도할 수 있습니다 (--create-namespace 사용 시 명시적으로 생성).

    helm install my-nginx bitnami/nginx -n web-apps --create-namespace
  • 설정 값 오버라이드: values.yaml의 값을 변경하여 설치할 수 있습니다.
    • --set <key>=<value>: 단일 값 변경.
    • --set-string <key>=<value>: 값을 문자열로 강제.
    • --set-file <key>=<path-to-file>: 파일 내용을 값으로 사용.
    • -f <values-file.yaml> 또는 --values <values-file.yaml>: 커스텀 values 파일을 사용. 여러 개 지정 가능하며, 뒤에 오는 파일이 앞의 파일을 덮어씁니다.
    helm install my-nginx bitnami/nginx --set replicaCount=2
helm install my-nginx bitnami/nginx -f custom-values.yaml --set image.tag=latest

  • 특정 버전의 차트 설치: --version 플래그를 사용합니다.

    helm install my-nginx bitnami/nginx --version 15.0.0

릴리스 상태 확인 (helm status)

특정 릴리스의 상태와 배포된 리소스 정보를 확인합니다.

helm status <release-name>

예:

helm status my-nginx -n web-apps

릴리스 목록 보기 (helm list 또는 helm ls)

현재 네임스페이스 또는 모든 네임스페이스에 설치된 릴리스 목록을 보여줍니다.

helm list # 현재 네임스페이스
helm list -n <namespace-name> # 특정 네임스페이스
helm list -A # 모든 네임스페이스
helm list --filter <keyword> # 필터링
helm list --deployed # 배포 성공한 릴리스만
helm list --failed # 배포 실패한 릴리스만
helm list --pending # 배포 중인 릴리스만

Helm 운영 가이드

배포된 릴리스를 관리하고 업데이트하는 방법을 다룹니다.

릴리스 업그레이드 (helm upgrade)

설치된 릴리스의 차트 버전이나 설정을 변경합니다.

helm upgrade <release-name> <chart-name-or-path> [flags]

  • 새로운 버전의 차트로 업그레이드:

    helm upgrade my-nginx bitnami/nginx --version 15.0.1

  • 설정 값 변경하여 업그레이드:

    helm upgrade my-nginx bitnami/nginx --set replicaCount=3
helm upgrade my-nginx bitnami/nginx -f new-values.yaml

  • 릴리스가 없으면 설치 (--install 또는 -i): upgrade 명령어에 -i 옵션을 사용하면, 해당 릴리스가 존재하지 않을 경우 새로 설치합니다 (upsert 동작).

    helm upgrade --install my-nginx bitnami/nginx --set replicaCount=3 -n web-apps --create-namespace

릴리스 롤백 (helm rollback)

문제가 발생했을 때 이전 리비전(revision)으로 릴리스를 되돌립니다.

  • 릴리스 히스토리 보기:

    helm history <release-name>

    예:

    helm history my-nginx -n web-apps

  • 특정 리비전으로 롤백:

    helm rollback <release-name> <revision-number>

    revision-number를 생략하면 바로 이전 리비전으로 롤백합니다.

    helm rollback my-nginx 1 -n web-apps # 리비전 1로 롤백
helm rollback my-nginx -n web-apps # 이전 리비전으로 롤백

  • 롤백 시 dry run: --dry-run 플래그를 사용하여 롤백 결과를 미리 확인할 수 있습니다.

릴리스 삭제 (helm uninstall 또는 helm delete)

클러스터에서 릴리스를 제거합니다. 관련된 모든 쿠버네티스 리소스가 삭제됩니다.

helm uninstall <release-name>

예:

helm uninstall my-nginx -n web-apps

--keep-history 플래그를 사용하면 릴리스 히스토리는 남겨두고 리소스만 삭제할 수 있습니다. (이 경우 나중에 helm rollback은 불가능)

차트 소스 가져오기 (helm pull)

리포지토리에서 차트 아카이브(.tgz)를 다운로드합니다.

helm pull <repo-name>/<chart-name>

예:

helm pull bitnami/nginx --version 15.0.0 # 특정 버전 다운로드
helm pull bitnami/nginx --untar # 다운로드 후 압축 해제

릴리스 관련 정보 가져오기 (helm get)

배포된 릴리스의 다양한 정보를 가져옵니다.

  • 릴리스의 Values 가져오기:

    helm get values <release-name> # 사용자가 설정한 값들
helm get values <release-name> --all # 계산된 모든 값들(기본값 + 사용자 설정)

  • 릴리스의 매니페스트 가져오기: 쿠버네티스 클러스터에 배포된 실제 YAML 매니페스트를 보여줍니다.

    helm get manifest <release-name>

  • 릴리스의 Notes 가져오기: 차트의 templates/NOTES.txt 파일 내용을 보여줍니다.

    helm get notes <release-name>

  • 릴리스의 Hooks 가져오기:

    helm get hooks <release-name>

Helm 플러그인

Helm의 기능을 확장하는 플러그인을 사용할 수 있습니다.

  • 플러그인 목록:

    helm plugin list

  • 플러그인 설치:

    helm plugin install <plugin-url-or-path>

    예: helm-diff 플러그인 설치 (릴리스 간 변경사항 비교).

    helm plugin install https://github.com/databus23/helm-diff

  • 플러그인 사용: 플러그인 이름으로 호출합니다.

    helm diff upgrade my-release ./my-chart

고급 팁 및 모범 사례

  • Secrets 관리: Helm 자체는 secrets를 직접 암호화하지 않습니다. 민감한 데이터는 values.yaml에 직접 넣지 말고, Helm 외부에서 관리되는 쿠버네티스 Secrets를 참조하거나, Helm Secrets 같은 플러그인을 사용하여 values 파일을 암호화하는 것을 고려하세요.
  • 네임스페이스 전략: 애플리케이션이나 환경별로 네임스페이스를 분리하여 사용하는 것이 좋습니다.

  • Values 파일 관리: 환경별(개발, 스테이징, 프로덕션)로 values 파일을 분리하여 관리하고, 공통된 값은 기본 values.yaml에, 환경별 특화된 값은 values-dev.yaml, values-prod.yaml 등으로 관리합니다.

    helm install my-release ./my-app -f values.yaml -f values-prod.yaml
  • 차트 버전 관리: SemVer(Semantic Versioning)를 따라 차트 버전을 관리하고, 변경 사항이 있을 때마다 버전을 적절히 올립니다.
  • CI/CD 연동: helm lint, helm package, helm upgrade --install 등의 명령어를 CI/CD 파이프라인에 통합하여 배포 자동화를 구현할 수 있습니다.

마무리

이 가이드는 신입 개발자가 Helm을 시작하고 쿠버네티스 애플리케이션을 효율적으로 관리하는 데 필요한 기본적인 명령어와 개념들을 다루었습니다. Helm은 매우 강력하고 유연한 도구이므로, 공식 문서와 커뮤니티 자료를 통해 더 많은 기능을 탐색하고 실제 프로젝트에 적용해보는 것이 중요합니다. 꾸준한 학습과 실습을 통해 Helm 전문가로 성장하시길 바랍니다.

이 시리즈의 다른 글 보기: (만약 시리즈의 일부라면 여기에 목록을 추가하세요. 지금은 단독 글이므로 비워둡니다.)

참고