Helm 핵심 개념 — Chart, Release, Values, Template

이 글의 목표: Chart / Release / Repository / Values / Template 다섯 단어로 Helm 90%를 설명할 수 있게 만든다.

그림 한 장으로 보는 Helm

[ Helm Repository (원격 저장소) ]
          │
          │   helm pull / helm dep update
          ▼
[ Chart (로컬 폴더 또는 .tgz) ]
          │
          │   helm install / upgrade
          ▼
[ Release (클러스터에 설치된 인스턴스) ]
          │
          │   템플릿 + values.yaml 을 합쳐 만든
          ▼
[ K8s Resources (Deployment, Service, Ingress ...) ]

① Chart (차트)

K8s 리소스 묶음을 만드는 템플릿 패키지

폴더 구조의 표준은 다음과 같다.

backend/                 ← 차트 폴더
├── Chart.yaml           # 차트 메타데이터 (이름, 버전, appVersion)
├── values.yaml          # 기본 변수값
├── templates/           # K8s YAML 템플릿
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   └── externalsecret.yaml
├── charts/              # 의존 차트 (subchart)들의 .tgz
└── Chart.lock           # 의존 차트의 잠긴 버전

Chart.yaml 예시 (프로젝트 helm/backend/Chart.yaml)

apiVersion: v2
name: meeny-backend
description: Hello meeny backend
type: application
version: 1.0.0          # ← 차트 자체의 버전 (Helm이 추적)
appVersion: "1.0.0"     # ← 안에 들어있는 앱의 버전 (정보용)

⚠️ version ≠ appVersion. 헷갈리지 말 것. Helm 명령어는 version을 본다.

② Release (릴리스)

차트를 클러스터에 설치한 결과물의 이름

helm install backend ./helm/backend
            ▲          ▲
            │          └─ 차트 폴더(또는 repo의 차트)
            └─ Release 이름

같은 차트를 이름만 다르게 여러 번 설치할 수도 있다.

helm install backend-blue  ./helm/backend
helm install backend-green ./helm/backend

→ 서로 다른 Release. 카나리/블루-그린 배포에 활용 가능.

설치된 Release 확인:

helm list -A
NAME            NAMESPACE    REVISION    STATUS      CHART
backend         default      3           deployed    meeny-backend-1.0.0
ingress-nginx   ingress      1           deployed    meeny-ingress-1.0.0

③ Values (값)

템플릿에 주입할 변수의 모음

우선순위 (높을수록 우선)

높음 ▲
    │  ① helm install --set image.tag=0.0.2 (CLI)
    │  ② -f values-prod.yaml (별도 파일)
    │  ③ 차트 폴더의 values.yaml (기본값)
낮음 ▼

사용 예 — helm/backend/values.yaml

replicaCount: 2
 
image:
  repository: 505947591451.dkr.ecr.ap-northeast-2.amazonaws.com/meeny/backend
  tag: "0.0.1"
 
service:
  type: ClusterIP
  port: 80
  targetPort: 8080

→ 템플릿에서 {{ .Values.replicaCount }} 처럼 참조한다.

환경별 분리 패턴

# 운영
helm upgrade backend ./helm/backend -f values-prod.yaml
 
# 개발
helm upgrade backend ./helm/backend -f values-dev.yaml

④ Templates (템플릿)

values + Go template 문법으로 K8s YAML을 자동 생성

가장 단순한 예:

# templates/deployment.yaml
spec:
  replicas: {{ .Values.replicaCount }}
  template:
    spec:
      containers:
        - name: backend
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"

values.yaml이 위와 같으면 렌더링 결과는 다음과 같다.

spec:
  replicas: 2
  template:
    spec:
      containers:
        - name: backend
          image: "505947591451.dkr.ecr.ap-northeast-2.amazonaws.com/meeny/backend:0.0.1"

자주 쓰는 템플릿 함수

프로젝트의 활용 예 — helm/backend/templates/deployment.yaml

{{- if .Values.springProfilesActive }}
- name: SPRING_PROFILES_ACTIVE
  value: {{ .Values.springProfilesActive | quote }}
{{- end }}
{{- range $k, $v := .Values.env }}
- name: {{ $k }}
  value: {{ $v | quote }}
{{- end }}

→ springProfilesActive 값이 있으면 환경변수 추가, env 맵을 순회하며 환경변수 추가.

⚠️ {{-, -}} 의 -는 앞/뒤 공백을 잘라먹는다는 뜻. 빈 줄을 깔끔하게 만들어 준다.

⑤ Repository (저장소)

여러 사람이 가져다 쓸 수 있게 차트를 호스팅하는 곳

# 외부 저장소 등록
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
 
# 차트 설치
helm install ingress-nginx ingress-nginx/ingress-nginx

프로젝트의 Chart.yaml에서 외부 차트를 의존성으로 가져오는 예:

# helm/ingress/Chart.yaml
dependencies:
  - name: ingress-nginx
    version: 4.9.1
    repository: https://kubernetes.github.io/ingress-nginx

helm dependency update 를 실행하면 charts/ingress-nginx-4.9.1.tgz 파일이 다운로드된다.

→ 즉, 우리 차트 안에 외부 차트를 끼워 넣어 같이 배포할 수 있다. 이를 Subchart 패턴이라 한다.

Subchart (서브차트) — 프로젝트가 쓰는 패턴

helm/ingress/는 직접 만든 차트지만, 안의 진짜 컨트롤러는 외부 ingress-nginx 차트다.

helm/ingress/
├── Chart.yaml              # dependencies: ingress-nginx
├── Chart.lock              # 잠긴 의존성 버전
├── values.yaml             # ingress-nginx 차트에 넘길 값
└── charts/
    └── ingress-nginx-4.9.1.tgz   # helm dep update로 받음

values.yaml에서 서브차트 값을 덮어쓸 때는 서브차트 이름을 키로 쓴다.

# helm/ingress/values.yaml
ingress-nginx:               # ← 서브차트 이름
  controller:
    service:
      type: LoadBalancer
      annotations:
        service.beta.kubernetes.io/aws-load-balancer-scheme: "internet-facing"

→ "ingress-nginx 서브차트의 controller.service 값을 이렇게 덮어써라" 라는 뜻.

⚠️ 서브차트 이름이 ingress-nginx 이면 우리 values.yaml의 최상위 키도 정확히 ingress-nginx 여야 한다.

Release Revision과 롤백

helm install backend ./helm/backend       # revision 1
helm upgrade backend ./helm/backend ...   # revision 2
helm upgrade backend ./helm/backend ...   # revision 3 (실수)
 
# 변경 이력
helm history backend
 
# 한 번에 되돌리기
helm rollback backend 2

→ Helm은 매 install/upgrade마다 이전 매니페스트 전체를 K8s Secret으로 저장한다. 그래서 롤백이 가능하다.

Hook (잠깐만)

templates/ 안 YAML에 어노테이션 helm.sh/hook이 있으면 install/upgrade 단계 중 특정 시점에만 실행된다. 흔한 용도:

• pre-install: 설치 전 마이그레이션 Job
• post-upgrade: 업그레이드 후 캐시 워밍

지금 프로젝트엔 안 쓰지만, 마이그레이션 자동화 시 자주 등장하니 단어만 기억해 두면 좋다.

핵심 요약 카드

다음 글에서는 templates/, _helpers.tpl, 자주 쓰는 템플릿 패턴을 자세히 본다.