🛠️ 나만의 Helm Chart 만들기 – 설계부터 패키징까지

지난 글에서는 Bitnami가 만든 Chart를 가져다 쓰는 “소비자” 역할을 했습니다. 이번엔 직접 Chart를 만드는 “생산자” 역할로 전환합니다. Custom Chart를 만들면 우리 팀의 배포 표준을 코드로 정의하고, 어떤 환경에서든(dev/staging/prod) 동일한 방식으로 배포할 수 있습니다.

---

🏗️ Step 1 — Chart 뼈대 생성 (Scaffolding)

helm create 명령어 하나로 표준 디렉토리 구조를 자동으로 만들어줍니다.

helm create mywebapp
ls -R mywebapp

mywebapp/
├── Chart.yaml          # 차트 메타데이터 (이름, 버전)
├── values.yaml         # 기본 설정값 (변수들)
├── charts/             # 의존 차트들
└── templates/          # 실제 K8s YAML 템플릿들
    ├── deployment.yaml
    ├── service.yaml
    ├── ingress.yaml
    ├── _helpers.tpl    # 재사용 가능한 템플릿 조각
    └── ...

3가지 핵심 파일만 알면 됩니다:

• Chart.yaml — 이 차트의 이름/버전 명찰
• values.yaml — 사용자가 바꿀 수 있는 설정값들
• templates/ — 변수({{ }})가 뚫려 있는 K8s YAML 파일들

---

🎨 Step 2 — Go Template 문법 이해

Helm의 핵심은 **”데이터와 로직의 분리”**입니다.

values.yaml (데이터)  +  templates/*.yaml (틀)  =  완성된 K8s YAML

templates/deployment.yaml을 보면 이런 부분이 있습니다:

# templates/deployment.yaml (일부)
spec:
  replicas: {{ .Values.replicaCount }}   # ← 여기가 변수!

values.yaml에는:

# values.yaml
replicaCount: 1    # ← 이 값이 위 변수 자리에 들어감

즉, {{ .Values.replicaCount }} = values.yaml의 replicaCount 값.

---

🔍 클러스터 배포 없이 렌더링 미리 보기 (Dry Run)

실제로 클러스터에 배포하기 전에 최종 YAML이 어떻게 만들어지는지 확인합니다. 개발 중 실수를 잡는 핵심 도구입니다.

helm template debug-release ./mywebapp

화면에 쏟아지는 YAML이 실제로 배포될 내용입니다. kind: Deployment, kind: Service 같은 내용이 보이면 정상입니다.

---

🛠️ Step 3 — 실제 커스터마이징

기본값 변경 — replicaCount 2개로 고정

# values.yaml에서 1을 2로 변경
sed -i 's/replicaCount: 1/replicaCount: 2/' mywebapp/values.yaml

# 변경 확인
grep "replicaCount" mywebapp/values.yaml
# replicaCount: 2 ← 성공!

# 렌더링 결과에서 replicas 값 확인
helm template debug ./mywebapp | grep "replicas:"
# replicas: 2 ← 변수가 잘 연결됨

조건문으로 리소스 켜고 끄기

values.yaml의 ingress.enabled 값으로 Ingress 생성을 제어합니다.

# values.yaml에서
ingress:
  enabled: false   # true로 바꾸면 Ingress가 생성됨

templates/ingress.yaml 내부:

{{- if .Values.ingress.enabled -}}   # ← 이 조건이 true일 때만 렌더링
apiVersion: networking.k8s.io/v1
kind: Ingress
...
{{- end }}

# enabled: false → true로 변경 후 렌더링 확인
helm template debug ./mywebapp | grep "kind: Ingress"
# kind: Ingress ← 이제 Ingress가 포함됨!

---

📦 Step 4 — 패키징 및 버전 관리

불량 검사 (Lint)

배포 전에 문법 오류를 미리 잡습니다.

helm lint ./mywebapp
# 1 chart(s) linted, 0 chart(s) failed ← 통과!

패키징

helm package ./mywebapp
# mywebapp-0.1.0.tgz 생성!

ls -l *.tgz
# -rw-r--r-- 1 ... mywebapp-0.1.0.tgz

파일명 규칙: {차트이름}-{버전}.tgz입니다. 버전은 Chart.yaml의 version 필드를 따라갑니다.

버전 업그레이드 시뮬레이션

# Chart.yaml에서 버전 올리기
sed -i 's/version: 0.1.0/version: 0.2.0/' mywebapp/Chart.yaml

# 재패키징
helm package ./mywebapp

# 이제 두 버전이 공존
ls -l *.tgz
# mywebapp-0.1.0.tgz
# mywebapp-0.2.0.tgz ← 새 버전!

---

💡 왜 Chart를 직접 만들어야 하는가?

Bitnami 같은 공개 Chart는 범용적으로 만들어져서 옵션이 수백 개입니다. 우리 팀에 딱 맞는 설정은 직접 만드는 게 낫습니다.

Custom Chart를 쓰면 이런 게 가능합니다:

# dev 환경 배포
helm install myapp ./mywebapp -f values-dev.yaml

# production 환경 배포 (같은 Chart, 다른 values)
helm install myapp ./mywebapp -f values-prod.yaml

하나의 Chart 소스로 여러 환경을 찍어낼 수 있습니다. CI/CD 파이프라인에 넣기도 딱 좋습니다.

---

📋 Chart 개발 핵심 명령어

구분	명령어	설명
생성	helm create [이름]	새 차트 디렉토리 생성
검증	helm template [릴리즈] [경로]	렌더링 결과 미리보기
	helm lint [경로]	문법 오류 검사
패키징	helm package [경로]	.tgz 압축 파일 생성
	ls -l *.tgz	생성된 패키지 확인

---

✅ Helm 시리즈 정리

• Step 1: 남의 Chart 쓰기 (설치, 업그레이드, 롤백) → Helm의 소비자
• Step 2 (이번 글): 내 Chart 만들기 (뼈대 생성, 템플릿, 패키징) → Helm의 생산자

이제 다음 단계인 GitOps입니다. 이 Chart를 Git에 올리고, ArgoCD가 자동으로 가져가서 클러스터에 배포하게 만들 차례입니다.

다음 글에서는 ArgoCD로 GitOps 파이프라인을 구성하고, “Git Push 하나로 배포가 완성되는” 자동화를 완성합니다.