Helm Reference

Helm 쿠버네티스 패키지 매니저 레퍼런스

29개 결과

Helm Reference 소개

Helm 레퍼런스는 Helm 3의 모든 핵심 명령어와 차트 작성 패턴을 검색할 수 있는 빠른 참조 도구입니다. 차트, 템플릿, 값, 릴리스, 저장소, 훅의 여섯 가지 카테고리로 정리되어 있어 Kubernetes 엔지니어가 공식 문서를 뒤지지 않고도 필요한 구문을 바로 찾을 수 있습니다. 모든 항목에는 실제 프로젝트에 바로 적용할 수 있는 예제가 포함되어 있습니다.

차트 개발자와 플랫폼 팀은 {{ include }}, {{- range }}, toYaml | nindent 같은 템플릿 지시어뿐만 아니라 helm upgrade --install, helm rollback, helm history 같은 릴리스 관리 명령어를 이 레퍼런스로 빠르게 확인합니다. 값 오버라이드 우선순위(--set과 -f), Chart.yaml 의존성 선언, 훅의 hook-weight 및 hook-delete-policy 설정도 다룹니다.

콘텐츠는 일반적인 Helm 워크플로를 따라 구성되어 있습니다. 차트 생성과 구조 이해에서 시작해 템플릿과 값 관리, 릴리스 및 저장소 관리, 마지막으로 pre/post install·upgrade 훅을 통한 자동화로 이어집니다. 새 마이크로서비스를 패키징하든 CI/CD 파이프라인에서 실패한 업그레이드를 디버깅하든, 이 레퍼런스에서 필요한 명령어와 YAML 스니펫을 즉시 찾을 수 있습니다.

주요 기능

Helm 3 CLI 전체 커버: create, lint, package, install, upgrade, rollback, uninstall, list, status
Go 템플릿 문법: {{ .Values.key }}, {{ include }}, {{- if }}, {{- range }}, toYaml | nindent
값 오버라이드 우선순위: values.yaml, -f 파일, --set 플래그(점 표기법·이스케이프 포함)
라이프사이클 훅: pre-install, post-install, pre-upgrade, post-upgrade, test와 hook-weight·delete-policy
저장소 관리: helm repo add, update, search, list (Bitnami, Prometheus 커뮤니티 예제 포함)
Chart.yaml 구조: apiVersion v2, semver 버전 고정 의존성 선언, appVersion 필드
디버깅 워크플로: helm template 로컬 렌더링, --debug 플래그, Pod 훅 어노테이션을 사용한 helm test
릴리스 관리: 리비전 히스토리, 특정 리비전 롤백, --keep-history, --reuse-values 패턴

자주 묻는 질문

Helm이란 무엇이고 왜 Kubernetes에서 사용하나요?

Helm은 Kubernetes 패키지 매니저입니다. 복잡한 Kubernetes 애플리케이션을 버전 관리가 가능한 재사용 가능한 차트로 정의, 설치, 업그레이드할 수 있습니다. 수십 개의 YAML 매니페스트를 직접 적용하는 대신 helm install 명령 하나로 환경별 값이 적용된 템플릿을 렌더링하여 클러스터에 배포할 수 있습니다.

helm install과 helm upgrade --install의 차이는 무엇인가요?

helm install은 새 릴리스를 생성하며, 동일한 이름의 릴리스가 이미 존재하면 실패합니다. helm upgrade --install은 멱등(idempotent)적으로 동작합니다. 릴리스가 없으면 생성하고, 있으면 업그레이드합니다. CI/CD 파이프라인에서는 이전 배포 여부와 관계없이 동작하므로 --install 플래그를 널리 사용합니다.

values.yaml을 수정하지 않고 값을 오버라이드하는 방법은?

커맨드라인에서 개별 값을 변경할 때는 --set key=value를, 전체 오버라이드 파일을 로드할 때는 -f myvalues.yaml을 사용합니다. 여러 -f 파일은 왼쪽에서 오른쪽 순서로 병합되며 뒤의 파일이 우선합니다. 두 방법을 혼용할 수도 있습니다: helm upgrade my-release ./chart -f prod-values.yaml --set image.tag=v2.1.

Helm 훅은 언제 사용하나요?

Helm 훅은 helm.sh/hook 어노테이션이 달린 Kubernetes 리소스(주로 Job 또는 Pod)로, 릴리스 라이프사이클의 특정 시점에 실행됩니다. pre-install, post-install, pre-upgrade, post-upgrade, pre-delete, post-delete, test를 지원합니다. 주요 사용 사례로는 업그레이드 전 데이터베이스 마이그레이션, 설치 후 Slack 알림, helm test를 통한 통합 테스트 등이 있습니다.

toYaml | nindent 패턴은 어떻게 작동하나요?

toYaml은 values.yaml의 하위 트리를 YAML 문자열로 직렬화하고, nindent N은 줄바꿈 후 모든 줄을 N칸 들여씁니다. resources, affinity, env 배열 같은 블록형 YAML 구조를 들여쓰기가 있는 템플릿 컨텍스트에 삽입할 때 필수적입니다. nindent 없이 삽입하면 들여쓰기가 맞지 않아 매니페스트 유효성 검사가 실패합니다.

템플릿 렌더링 오류를 디버깅하는 방법은?

helm template <release-name> <chart>를 실행하면 클러스터에 연결하지 않고 로컬에서 매니페스트를 렌더링합니다. --debug를 추가하면 렌더링된 출력과 템플릿 오류를 확인할 수 있습니다. --set 또는 -f 플래그를 함께 사용해 다양한 값 조합을 테스트할 수 있습니다. helm lint <chart>는 패키징 전 Chart.yaml과 템플릿 구문의 구조적 문제를 검사합니다.

helm rollback은 언제 사용하나요?

helm rollback <release> <revision>은 릴리스를 이전에 배포된 리비전으로 되돌립니다. Helm은 모든 리비전의 렌더링된 매니페스트를 Kubernetes Secret으로 저장하므로 롤백 시 템플릿을 다시 렌더링할 필요가 없습니다. helm history <release>로 모든 리비전과 상태를 확인한 후 특정 번호로 롤백할 수 있습니다. --wait 플래그를 사용하면 롤백된 리소스가 준비될 때까지 명령이 대기합니다.

Helm 차트 의존성은 어떻게 관리하나요?

의존성은 Chart.yaml의 dependencies 필드에 name, version(semver 범위), repository URL을 지정하여 선언합니다. helm dependency update를 실행하면 .tgz 파일로 charts/ 디렉터리에 다운로드됩니다. 설치 시 Helm은 부모와 의존성 템플릿을 함께 렌더링하며, 부모 values.yaml에 의존성 이름과 동일한 섹션을 추가해 값을 전달할 수 있습니다.