Helm이란? Kubernetes 패키지 관리와 배포

기준 버전: Helm 4.3.0
관련 기술: Kubernetes, Docker, OCI Registry, YAML, Go Template

1. Helm이란?#

Helm은 Kubernetes용 패키지 관리자 (Package Manager)입니다.

Kubernetes에서는 애플리케이션 하나를 배포하기 위해 Deployment, Service, ConfigMap, Secret, Ingress 등 여러 리소스의 매니페스트를 작성하고 관리해야 합니다. 애플리케이션의 환경별 설정이나 버전이 늘어나면 이러한 YAML 파일을 반복해서 수정하고 관리하는 일이 복잡해질 수 있습니다.

Helm은 이러한 Kubernetes 리소스를 Chart라는 패키지 형태로 묶고, 템플릿과 설정 값을 이용하여 여러 환경에 일관되게 배포할 수 있도록 도와줍니다.

Helm 공식 문서에서는 Helm을 Kubernetes의 패키지 관리자로 설명하며, 현재 Helm 4가 최신 주요 버전입니다.

1.1 Helm을 사용하는 이유#

Helm을 사용하면 다음과 같은 작업을 체계적으로 관리할 수 있습니다.

  • Kubernetes 애플리케이션을 Chart로 패키징
  • 환경별 설정 값을 분리하여 관리
  • 동일한 애플리케이션을 여러 환경에 반복 배포
  • 애플리케이션의 설치 및 업그레이드 관리
  • 배포 이력 확인 및 롤백
  • Chart의 버전 관리
  • 공개 또는 사설 Chart 배포 및 공유
  • OCI Registry를 이용한 Chart 저장 및 배포

즉, Helm은 단순히 YAML 파일을 줄이는 도구라기보다 Kubernetes 애플리케이션의 패키징, 설정, 배포, 버전 관리 과정을 표준화하는 도구로 이해하는 것이 좋습니다.

2. Helm의 핵심 개념#

Helm을 이해하려면 먼저 다음 네 가지 개념을 구분해야 합니다.

개념 설명
Chart Kubernetes 애플리케이션을 정의하는 Helm 패키지
Values Chart에 전달하는 설정 값
Template Values를 이용해 Kubernetes 매니페스트를 생성하는 템플릿
Release 특정 설정으로 설치된 Chart의 인스턴스

2.1 Chart#

Chart는 Helm의 기본 패키지 형식입니다.

Chart에는 Kubernetes 리소스를 정의하는 템플릿과 기본 설정, 메타데이터 등이 들어 있습니다.

예를 들어 하나의 웹 애플리케이션 Chart에는 다음과 같은 리소스가 포함될 수 있습니다.

  • Deployment
  • Service
  • ConfigMap
  • Secret
  • Ingress
  • ServiceAccount
  • HorizontalPodAutoscaler

Chart는 로컬 디렉터리 형태로 사용할 수도 있고 패키징하여 저장소나 OCI Registry에 배포할 수도 있습니다.

2.2 Values#

values.yaml은 Chart의 기본 설정 값을 정의하는 파일입니다.

예를 들어 다음과 같이 이미지와 복제본 수를 정의할 수 있습니다.

replicaCount: 2

image:
  repository: nginx
  tag: "1.29"

service:
  type: ClusterIP
  port: 80

사용자는 설치할 때 별도의 값을 전달하여 기본 설정을 변경할 수 있습니다.

helm install my-web ./my-chart \
  --set replicaCount=3

또는 별도의 values 파일을 사용할 수 있습니다.

helm install my-web ./my-chart \
  -f values-prod.yaml

2.3 Template#

templates/ 디렉터리에는 Kubernetes 매니페스트를 생성하기 위한 템플릿이 들어갑니다.

예를 들어 Deployment 템플릿에서 다음과 같이 값을 사용할 수 있습니다.

spec:
  replicas: {{ .Values.replicaCount }}

Helm은 Chart와 Values를 조합하여 Kubernetes에 전달할 최종 매니페스트를 생성합니다.

2.4 Release#

Release는 Chart가 특정 설정과 함께 Kubernetes 클러스터에 설치된 결과를 의미합니다.

하나의 Chart를 여러 이름으로 설치할 수도 있습니다.

helm install web-dev ./my-chart
helm install web-prod ./my-chart

이 경우 동일한 Chart를 사용하지만 web-dev와 web-prod라는 서로 다른 Release가 만들어집니다.

3. Helm Chart의 구조#

Helm Chart는 일반적으로 다음과 같은 디렉터리 구조를 사용합니다.

my-chart/
├── Chart.yaml
├── values.yaml
├── templates/
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   ├── configmap.yaml
│   ├── _helpers.tpl
│   └── NOTES.txt
├── charts/
└── .helmignore

3.1 Chart.yaml#

Chart의 기본 메타데이터를 정의합니다.

apiVersion: v2
name: my-chart
description: A Helm chart for Kubernetes
type: application
version: 0.1.0
appVersion: "1.0.0"

주요 항목은 다음과 같습니다.

  • apiVersion: Chart 형식의 버전
  • name: Chart 이름
  • description: Chart 설명
  • type: application 또는 library
  • version: Chart 자체의 버전
  • appVersion: Chart가 배포하는 애플리케이션의 버전

주의: version과 appVersion은 서로 다른 개념입니다.

  • version: Helm Chart의 버전
  • appVersion: Chart가 배포하는 애플리케이션의 버전

3.2 values.yaml#

Chart의 기본 설정을 정의합니다.

replicaCount: 2

image:
  repository: nginx
  tag: "1.29"
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 80

운영 환경에서는 별도의 파일을 만들어 환경별 값을 관리할 수 있습니다.

values.yaml
values-dev.yaml
values-staging.yaml
values-prod.yaml

3.3 templates/#

Kubernetes 리소스의 템플릿을 저장합니다.

templates/
├── deployment.yaml
├── service.yaml
├── ingress.yaml
├── configmap.yaml
└── _helpers.tpl

Helm의 템플릿 기능은 Go 템플릿 문법과 Helm에서 제공하는 템플릿 함수를 기반으로 동작합니다.

3.4 charts/#

Chart의 종속 Chart를 포함할 수 있는 디렉터리입니다.

최근 Helm에서는 Chart 의존성을 Chart.yaml의 dependencies로 선언하고 helm dependency update 등의 명령으로 관리하는 방식이 일반적입니다.

3.5 .helmignore#

Chart를 패키징할 때 제외할 파일을 지정합니다.

Git의 .gitignore와 비슷한 역할을 합니다.

4. Helm Chart 생성하기#

새 Chart는 다음 명령으로 생성할 수 있습니다.

helm create my-chart

생성 결과는 다음과 비슷합니다.

my-chart/
├── Chart.yaml
├── Chart.lock
├── values.yaml
├── charts/
├── templates/
└── .helmignore

자동 생성된 Chart는 학습과 시작점으로 활용할 수 있지만, 실제 운영 환경에서는 필요하지 않은 템플릿과 설정을 정리하여 사용하는 것이 좋습니다.

5. Helm Template의 기본#

Helm의 핵심 기능 중 하나는 템플릿 기반 매니페스트 생성입니다.

예를 들어 values.yaml에 다음 설정이 있다고 가정합니다.

replicaCount: 3

image:
  repository: nginx
  tag: "1.29"

Deployment 템플릿에서는 다음과 같이 사용할 수 있습니다.

spec:
  replicas: {{ .Values.replicaCount }}

  template:
    spec:
      containers:
        - name: nginx
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"

Helm은 설치 과정에서 Values를 템플릿에 적용하여 Kubernetes 매니페스트를 생성합니다.

5.1 조건문#

{{- if .Values.ingress.enabled }}
apiVersion: networking.k8s.io/v1
kind: Ingress
...
{{- end }}

5.2 반복문#

{{- range .Values.env }}
- name: {{ .name }}
  value: {{ .value | quote }}
{{- end }}

5.3 기본값#

replicas: {{ .Values.replicaCount | default 1 }}

5.4 템플릿 함수#

Helm은 다양한 템플릿 함수를 제공합니다.

name: {{ include "my-chart.fullname" . }}

복잡한 Chart에서는 _helpers.tpl을 활용하여 이름 생성이나 공통 템플릿을 관리할 수 있습니다.

6. Helm Chart 검증과 렌더링#

실제로 클러스터에 설치하기 전에 Chart를 검사하는 것이 좋습니다.

6.1 lint#

helm lint ./my-chart

Chart의 구조와 문법상의 문제를 검사합니다.

6.2 template#

실제 클러스터에 설치하지 않고 렌더링 결과를 확인할 수 있습니다.

helm template my-web ./my-chart

특정 Values 파일을 사용하려면 다음과 같이 합니다.

helm template my-web ./my-chart \
  -f values-prod.yaml

운영 환경에서는 helm template을 이용해 최종 Kubernetes 매니페스트를 먼저 확인하는 습관이 중요합니다.

6.3 install --dry-run#

설치 과정을 시뮬레이션할 때 사용할 수 있습니다.

helm install my-web ./my-chart \
  --dry-run

민감한 설정 값이 출력될 수 있으므로 실제 환경에서 사용할 때는 출력 내용에 주의해야 합니다.

7. Helm 설치#

Helm은 다양한 운영체제에서 설치할 수 있습니다.

공식 문서에서는 패키지 관리자 또는 바이너리를 이용한 설치 방법을 제공합니다.

7.1 macOS#

Homebrew를 사용하는 경우:

brew install helm

7.2 Windows#

Chocolatey:

choco install kubernetes-helm

WinGet:

winget install Helm.Helm

7.3 Linux#

Snap을 사용하는 경우:

sudo snap install helm --classic

배포판이나 환경에 따라 바이너리 또는 다른 패키지 관리자를 사용할 수도 있습니다.

설치 후 다음 명령으로 확인합니다.

helm version

현재 Helm 공식 문서의 최신 버전은 Helm 4.3.0입니다.

8. Helm과 Kubernetes 연결#

Helm은 별도의 Tiller 서버를 설치하는 방식이 아닙니다.

현재 Helm은 helm CLI를 사용하여 Kubernetes API와 상호작용합니다.

따라서 Helm을 사용하려면 기본적으로 다음 조건이 필요합니다.

  1. Kubernetes 클러스터가 실행 중이어야 합니다.
  2. kubectl이 클러스터에 접근할 수 있어야 합니다.
  3. Helm이 사용할 Kubernetes 컨텍스트가 올바르게 설정되어 있어야 합니다.

먼저 다음 명령을 확인할 수 있습니다.

kubectl cluster-info

현재 Kubernetes 컨텍스트는 다음 명령으로 확인합니다.

kubectl config current-context

9. Helm Chart 설치#

Chart 설치의 기본 형식은 다음과 같습니다.

helm install RELEASE_NAME CHART

로컬 Chart를 설치하는 예:

helm install my-web ./my-chart

특정 Namespace에 설치하려면:

helm install my-web ./my-chart \
  --namespace web \
  --create-namespace

설치된 Release를 확인합니다.

helm list

특정 Namespace를 확인하려면:

helm list -n web

10. Helm Release 관리#

10.1 Release 상태 확인#

helm status my-web

10.2 Release 목록#

helm list

10.3 Release 상세 정보#

helm get all my-web

필요한 정보만 조회할 수도 있습니다.

helm get values my-web
helm get manifest my-web
helm get notes my-web

10.4 Release 이력#

helm history my-web

Helm은 Release의 revision을 관리하므로 변경 이력을 확인할 수 있습니다.

11. Helm 업그레이드와 롤백#

11.1 업그레이드#

Chart의 설정을 변경한 뒤 다음과 같이 업그레이드할 수 있습니다.

helm upgrade my-web ./my-chart

Values 파일을 사용하는 경우:

helm upgrade my-web ./my-chart \
  -f values-prod.yaml

Release가 없으면 설치까지 수행하도록 하려면 --install을 사용할 수 있습니다.

helm upgrade --install my-web ./my-chart \
  -f values-prod.yaml

이 방식은 CI/CD 환경에서 자주 활용됩니다.

11.2 롤백#

Release의 이력을 확인합니다.

helm history my-web

특정 revision으로 되돌립니다.

helm rollback my-web 2

롤백은 문제가 발생한 배포를 이전 Release revision으로 되돌리는 데 사용할 수 있습니다.

11.3 삭제#

helm uninstall my-web

필요한 경우 --keep-history를 사용하여 Release 이력을 유지할 수 있습니다.

12. Helm Chart Repository#

전통적인 Helm Chart Repository는 패키징된 Chart를 저장하고 공유하는 저장소입니다.

일반적인 Chart Repository는 HTTP를 통해 Chart와 메타데이터를 제공하며 index.yaml을 사용하는 방식이 대표적입니다.

Repository를 추가하는 기본 형식:

helm repo add REPOSITORY_NAME REPOSITORY_URL

등록된 Repository 확인:

helm repo list

Repository 정보 갱신:

helm repo update

Repository 제거:

helm repo remove REPOSITORY_NAME

12.1 Chart 검색#

등록된 Repository에서 검색합니다.

helm search repo nginx

Artifact Hub에서 검색하려면:

helm search hub nginx

Artifact Hub는 여러 Helm Chart Repository의 Chart를 검색할 수 있는 대표적인 공개 서비스입니다.

13. OCI Registry와 Helm#

현재 Helm을 학습할 때는 전통적인 Chart Repository뿐 아니라 OCI Registry를 이용한 Chart 배포도 함께 이해하는 것이 중요합니다.

Helm은 OCI를 지원하며, Helm 3.8부터 OCI 지원이 기본적으로 활성화되었습니다.

OCI 방식에서는 다음과 같이 oci:// 형식의 주소를 사용합니다.

helm install my-web \
  oci://ghcr.io/example/charts/my-web

특정 버전을 지정할 수도 있습니다.

helm install my-web \
  oci://ghcr.io/example/charts/my-web \
  --version 1.2.0

Chart를 OCI Registry에 로그인하려면:

helm registry login ghcr.io

Chart 패키지를 업로드하려면:

helm package my-chart
helm push my-chart-0.1.0.tgz \
  oci://ghcr.io/example/charts

OCI 방식은 컨테이너 이미지와 비슷한 Registry 인프라를 활용할 수 있다는 점에서 현재 Helm 운영 환경에서 중요성이 높습니다.

14. Chart Repository와 OCI Registry의 차이#

두 방식을 구분해 두면 Helm을 이해하기 쉽습니다.

구분 Chart Repository OCI Registry
대표 주소 https://... oci://...
전통적인 방식 O X
index.yaml 사용 사용하지 않음
Chart 저장 .tgz 기반 OCI Artifact
검색 helm search repo Registry/Artifact Hub 등 활용
활용 기존 Chart Repository 현대적인 Registry 기반 배포

새로운 환경을 설계할 때는 조직에서 이미 사용하는 OCI Registry가 있는지 확인하고 배포 전략을 결정하는 것이 좋습니다.

15. Helm 4의 주요 변화#

Helm 4는 Helm 3 이후의 주요 버전입니다.

Helm 공식 문서에 따르면 Helm 4에서는 다음과 같은 변화가 이루어졌습니다.

  • WebAssembly(Wasm) 기반 플러그인 지원
  • kstatus 기반 리소스 상태 관찰 기능
  • OCI Digest 지원 강화
  • 다중 문서 Values 지원
  • JSON 인수 지원
  • 플러그인 시스템 재설계
  • 패키지 구조 개편
  • CLI 플래그 변경
  • 콘텐츠 기반 캐싱
  • 보안 및 TLS 관련 개선
  • Server-Side Apply 지원

Helm 4는 Chart에 대한 호환성을 유지하면서도 내부 아키텍처와 플러그인 시스템을 크게 개선한 메이저 버전입니다.

따라서 새로운 ThinkX 문서에서는 Helm v3를 현재 기준으로 설명하기보다 Helm 4를 기본으로 설명하고, Helm 3와의 차이를 별도 문서에서 다루는 방식이 적합합니다.

16. Helm 2, Helm 3, Helm 4의 차이#

항목 Helm 2 Helm 3 Helm 4
Tiller 사용 제거 제거
기본 사용 방식 Client + Tiller Helm CLI 중심 Helm CLI 중심
주요 Chart API v1 v2 v2 및 최신 기능
OCI 지원 제한적/없음 지원 강화
플러그인 시스템 기존 방식 기존 방식 재설계
현재 활용 레거시 유지보수/기존 환경 현재 주력 버전

Helm 2의 Tiller는 현재 Helm을 처음 배우는 사람이 반드시 설치해야 하는 구성 요소가 아닙니다.

기존 문서에서 Helm Client와 Tiller를 중심으로 설명하는 경우 Helm 2 시대의 내용과 현재 Helm의 내용을 분리해야 합니다.

17. Helm v3를 알아야 하는 이유#

Helm 4가 현재 최신 버전이지만, 실제 Kubernetes 환경에서는 Helm 3를 사용하는 기존 시스템을 만날 수 있습니다.

따라서 운영 또는 유지보수 업무를 위해서는 Helm 3의 특징도 알아둘 필요가 있습니다.

Helm 3의 가장 큰 변화는 Helm 2의 Tiller를 제거한 것입니다.

Helm 3에서는 Helm CLI가 Kubernetes API와 직접 상호작용하며, 권한은 Kubernetes의 인증 및 RBAC 체계를 기반으로 관리합니다.

따라서 다음과 같은 표현은 현재 문서에서 구분해서 사용하는 것이 좋습니다.

  • Helm Client → 현재는 일반적으로 Helm CLI라고 표현
  • Tiller → Helm 2의 레거시 구성 요소
  • Helm v3 방식 → 현재에도 많은 기존 환경에서 사용되는 방식
  • Helm v4 → 현재 최신 주요 버전

18. Helm Chart 의존성 관리#

Chart가 다른 Chart를 필요로 하는 경우 의존성을 정의할 수 있습니다.

예를 들어 Chart.yaml에 다음과 같이 작성할 수 있습니다.

dependencies:
  - name: redis
    version: "20.x.x"
    repository: "https://charts.example.com"

의존성을 다운로드하고 갱신하려면:

helm dependency update

현재 Chart의 의존성 상태를 확인하려면:

helm dependency list

의존성이 많은 애플리케이션에서는 Chart 간 버전 관계를 명확하게 관리하는 것이 중요합니다.

19. Helm Hooks와 테스트#

Helm은 단순한 설치와 업그레이드 외에도 Chart의 동작을 확장할 수 있는 기능을 제공합니다.

19.1 Hooks#

Hook을 사용하면 특정 Helm 작업의 특정 시점에 Kubernetes 리소스를 실행하도록 구성할 수 있습니다.

예를 들어 다음과 같은 작업에 활용할 수 있습니다.

  • 설치 전 초기화
  • 업그레이드 전 작업
  • 설치 후 초기화 작업
  • 삭제 전 정리 작업

19.2 Chart Test#

Chart에 테스트를 정의하고 다음 명령으로 실행할 수 있습니다.

helm test my-web

운영 환경에서는 설치가 성공했다는 사실과 애플리케이션이 실제로 정상 동작한다는 사실을 구분해야 하므로 테스트 구성이 중요합니다.

20. Helm을 이용한 배포 흐름#

실제 프로젝트에서는 다음과 같은 흐름으로 Helm을 사용할 수 있습니다.

개발자가 Chart 작성
      ↓
values.yaml 작성
      ↓
helm lint
      ↓
helm template
      ↓
Chart 패키징
      ↓
Chart Repository / OCI Registry
      ↓
Kubernetes 클러스터
      ↓
helm install / upgrade
      ↓
Release 관리
      ↓
helm history / status
      ↓
문제 발생 시 helm rollback

CI/CD를 사용하는 환경에서는 이 과정을 자동화할 수 있습니다.

Git
 ↓
CI
 ↓
Chart 검증
 ↓
Chart 패키징
 ↓
Registry 저장
 ↓
CD
 ↓
Kubernetes

21. Helm 사용 시 주의할 점#

Helm을 사용한다고 해서 Kubernetes 운영이 자동으로 단순해지는 것은 아닙니다.

다음 사항을 함께 고려해야 합니다.

21.1 Values 관리#

환경별 설정이 지나치게 많아지면 values.yaml 자체가 복잡해질 수 있습니다.

개발·스테이징·운영 환경의 설정을 명확하게 분리하고, 어떤 값이 기본값인지 문서화하는 것이 좋습니다.

21.2 Secret 관리#

비밀번호, API Key, Token 등의 민감한 정보를 일반적인 Values 파일에 평문으로 저장하는 것은 주의해야 합니다.

실제 운영 환경에서는 Kubernetes Secret 또는 외부 Secret 관리 시스템 등 조직의 보안 정책에 맞는 방법을 사용해야 합니다.

21.3 Chart 버전과 애플리케이션 버전 구분#

다음 두 버전은 서로 다를 수 있습니다.

Chart version
Application version

애플리케이션이 업데이트되지 않았더라도 Chart의 설정이나 템플릿이 변경되면 Chart 버전은 변경될 수 있습니다.

21.4 Kubernetes API 호환성#

Chart가 사용하는 Kubernetes API가 대상 클러스터 버전에서 지원되는지 확인해야 합니다.

특히 오래된 Chart를 최신 Kubernetes에 설치할 때는 Deprecated API 여부를 확인하는 것이 중요합니다.

22. 자주 사용하는 Helm 명령어#

Chart 생성#

helm create my-chart

Chart 검사#

helm lint ./my-chart

템플릿 렌더링#

helm template my-web ./my-chart

Chart 패키징#

helm package ./my-chart

Chart 설치#

helm install my-web ./my-chart

설치 또는 업그레이드#

helm upgrade --install my-web ./my-chart

Release 목록#

helm list

Release 상태#

helm status my-web

Release 이력#

helm history my-web

Release 업그레이드#

helm upgrade my-web ./my-chart

Release 롤백#

helm rollback my-web 2

Release 삭제#

helm uninstall my-web

Repository 추가#

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

Repository 갱신#

helm repo update

Repository 검색#

helm search repo nginx

Artifact Hub 검색#

helm search hub nginx

23. 마무리#

Helm은 Kubernetes 애플리케이션을 패키징하고, 설정하고, 배포하고, 업그레이드하고, 롤백하는 과정을 관리하는 Kubernetes 패키지 관리자입니다.

핵심 개념은 다음과 같이 정리할 수 있습니다.

Chart
 ├── Chart.yaml
 ├── values.yaml
 └── templates/
          ↓
      Helm Template
          ↓
 Kubernetes Manifest
          ↓
 Kubernetes API
          ↓
       Release

Helm을 처음 학습한다면 다음 순서로 접근하는 것이 좋습니다.

  1. Kubernetes YAML 이해
  2. Helm Chart 구조 이해
  3. values.yaml 이해
  4. Template 문법 이해
  5. helm create로 Chart 생성
  6. helm lint와 helm template 사용
  7. helm install과 helm upgrade 사용
  8. Release와 Revision 이해
  9. helm rollback 사용
  10. Chart Repository와 OCI Registry 이해
  11. CI/CD에서 Helm 활용
  12. Helm 4의 새로운 기능과 운영 전략 학습

Helm을 제대로 이해하면 Kubernetes 애플리케이션을 반복 가능하고 일관된 방식으로 배포할 수 있으며, 이후 GitOps와 CI/CD 같은 클라우드 네이티브 운영 기술을 이해하는 데도 도움이 됩니다.

관련 문서#

  • Kubernetes
  • Docker
  • kubectl
  • Kustomize
  • GitOps
  • Argo CD
  • CI/CD
  • OCI Registry
  • Kubernetes Deployment
  • Kubernetes Service

이 페이지의 목차