⎈
Helm Chart 치트시트

쿠버네티스 패키지 매니저 Helm 3 최신 기준 초보자 완벽 가이드: 필수 사전 설치, Chart-Repository-Release 3대 개념, 공식 차트 배포, values.yaml 커스터마이징, 나만의 차트 생성(Scaffolding), Go 템플릿 문법 & Sprig 함수, 의존성 서브차트, 롤백, OCI 배포 및 실무 CLI 치트시트
#helm#helm-chart#kubernetes#k8s#devops#cloud#package-manager#deployment#values-yaml최종 업데이트: 2026-10-06
Helm Chart 치트시트 핵심 명령어 및 실전 가이드

## 1. 필수 사전 설치 요건 & 환경 구성 (Prerequisites)

Helm(헬름)은 **"쿠버네티스를 위한 apt/yum/npm"**과 같은 공식 표준 패키지 매니저입니다. 복잡한 수십 개의 쿠버네티스 YAML 매니페스트(Deployment, Service, Ingress, ConfigMap 등)를 단 하나의 차트(Chart)로 묶어 배포, 업그레이드, 롤백을 자동화합니다.

### ☸️ 1. 사전 쿠버네티스 클러스터 연결 확인
Helm은 쿠버네티스 클러스터와 통신하므로, 로컬 또는 원격 클러스터와 `kubectl`이 정상 연결되어 있어야 합니다.

```bash
# 쿠버네티스 클러스터 연결 상태 확인 (Docker Desktop k8s, Minikube, Kind 등)
kubectl cluster-info

# 현재 연결된 노드 상태 확인 (Ready 상태여야 함)
kubectl get nodes
```

---

### 💻 2. OS별 Helm 3 클라이언트 설치

| 운영체제 (OS) | 설치 명령어 / 방법 |
| :--- | :--- |
| **Windows** | 터미널(관리자)에서 Chocolatey 또는 Scoop 실행:<br>`choco install kubernetes-helm`<br>또는 `scoop install helm` |
| **macOS** | Homebrew를 통한 설치:<br>`brew install helm` |
| **Linux (Ubuntu/Debian)** | 공식 스크립트 또는 APT 설치:<br>`curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 \| bash` |

설치 후 정상 동작 및 버전 확인:
```bash
helm version
# 출력 예시: version.BuildInfo{Version:"v3.16.2", GitCommit:"...", GitTreeState:"clean", GoVersion:"go1.22.7"}
```

---

## 2. Helm 3 핵심 개념 & 아키텍처 (Mental Model)

Helm의 작동 방식을 이해하기 위한 3대 핵심 객체와 파일 구조입니다.

```text
[Helm 3 아키텍처 멘탈 모델]
┌──────────────────┐               ┌──────────────────────────────────────────────┐
│  Helm Repository │               │            Kubernetes Cluster                │
│  (차트 저장소)    │               │                                              │
│  - ArtifactHub   │               │  ┌────────────────────────────────────────┐  │
│  - Bitnami Repo  │               │  │      Release: "my-nginx" (인스턴스)     │  │
└────────┬─────────┘               │  │  - Deployment (파드 3개)                │  │
         │ helm repo add           │  │  - Service (NodePort)                  │  │
         ▼                         │  │  - Ingress (도메인 라우팅)              │  │
┌──────────────────┐               │  └────────────────────────────────────────┘  │
│    Helm Chart    │ helm install  │                       ▲                      │
│ (도면 / 템플릿)   ├───────────────┼───────────────────────┘                      │
│  + values.yaml   │  --values     │  * Helm 3는 별도 Tiller 서버 없이             │
│ (사용자 설정값)   │               │    kubectl 권한과 Secret으로 상태 직접 보관! │
└──────────────────┘               └──────────────────────────────────────────────┘
```

### 🔑 3대 핵심 개념
1. **Chart (차트)**: 쿠버네티스 리소스를 생성하기 위한 파일들의 묶음(패키지 설계도).
2. **Repository (저장소)**: 빌드된 차트들을 전 세계 개발자들과 공유하고 내려받는 온라인 저장소 (예: Artifact Hub, Bitnami).
3. **Release (릴리스)**: 특정 차트가 `values.yaml` 설정값과 결합하여 **클러스터 위에 실제로 배포되어 실행 중인 구체적인 인스턴스**. (동일한 Nginx 차트로 `dev-nginx`, `prod-nginx` 등 여러 릴리스 생성 가능)

### 📁 표준 Helm Chart 디렉토리 구조
```text
my-chart/
├── Chart.yaml          # 차트의 이름, 버전, 설명 등 메타데이터 (필수)
├── values.yaml         # 템플릿에 주입될 기본 설정값 변수 정의 (필수)
├── charts/             # 이 차트가 의존하는 서브차트(Subcharts) 보관 폴더
├── templates/          # 실제 쿠버네티스 YAML 템플릿들이 위치하는 핵심 폴더
│   ├── deployment.yaml # Pod 배포 템플릿
│   ├── service.yaml    # 네트워크 서비스 템플릿
│   ├── _helpers.tpl    # 공통으로 재사용할 템플릿 헬퍼 함수 조각들
│   └── NOTES.txt       # helm install 완료 시 사용자 화면에 출력되는 안내문
└── .helmignore         # 패키징 시 제외할 파일 목록 (.gitignore와 유사)
```

---

## 3. [초보자 1단계] 공식 차트 설치 & 릴리스 라이프사이클

가장 검증된 Bitnami 저장소에서 Nginx 웹서버를 검색하고 설치, 조회, 삭제하는 전체 라이프사이클입니다.

```bash
# 1. 원격 차트 저장소(Repository) 추가
helm repo add bitnami https://charts.bitnami.com/bitnami

# 2. 저장소 최신 인덱스 업데이트
helm repo update

# 3. 원하는 차트 검색 (Search)
helm search repo nginx

# 4. 차트 기본 정보 및 수정 가능한 values 설정 확인
helm show values bitnami/nginx

# 5. 클러스터에 설치 (Release 이름: my-web-server)
helm install my-web-server bitnami/nginx

# 6. 현재 배포된 릴리스 목록 확인 (List)
helm list

# 7. 실제 쿠버네티스 파드 및 서비스 생성 상태 확인
kubectl get pods,svc -l app.kubernetes.io/instance=my-web-server

# 8. 릴리스 상태 상세 확인 (Status)
helm status my-web-server

# 9. 릴리스 삭제 (Uninstall - 연결된 Pod, Service 등이 일괄 정리됨)
helm uninstall my-web-server
```

---

## 4. [초보자 2단계] values.yaml을 통한 설정 커스터마이징

공식 차트의 기본 설정 대신, 내 환경에 맞게 레플리카 수나 포트를 변경하는 실무 방법입니다.

### 🛠️ 설정값을 변경하는 3가지 방법
1. **명령줄 플래그 (`--set`)**: 단일 변수 변경 시 유용
   ```bash
   helm install my-nginx bitnami/nginx --set replicaCount=3
   ```
2. **타입 강제 지정 (`--set-string`)**: 숫자 형태의 문자열 포트 지정 시
   ```bash
   helm install my-nginx bitnami/nginx --set-string service.port="8080"
   ```
3. **커스텀 파일 전달 (`-f` / `--values`)**: **실무 1순위 권장 방식**

### 📄 커스텀 설정 파일 작성: `my-values.yaml`
```yaml
# my-values.yaml
replicaCount: 2

service:
  type: NodePort
  nodePorts:
    http: "30080"

resources:
  limits:
    cpu: 250m
    memory: 256Mi
  requests:
    cpu: 100m
    memory: 128Mi
```

### 🚀 배포 및 무중단 업그레이드 (Upgrade)
```bash
# 1. 커스텀 values 파일로 설치
helm install my-nginx bitnami/nginx -f my-values.yaml

# 2. 설정 파일 수정 후 무중단 업그레이드 반영 (helm upgrade)
helm upgrade my-nginx bitnami/nginx -f my-values.yaml

# 팁: 없으면 설치하고 있으면 업그레이드하는 만능 명령어 (CI/CD 필수)
helm upgrade --install my-nginx bitnami/nginx -f my-values.yaml
```

---

## 5. [초보자 3단계] 나만의 첫 Helm Chart 만들기 (Scaffolding)

내 애플리케이션을 배포하기 위해 차트 보일러플레이트를 생성하고 검증하는 실전 단계입니다.

```bash
# 1. 새 차트 생성 스캐폴딩
helm create my-app
cd my-app
```

생성된 `my-app` 디렉토리의 핵심 파일들을 살펴봅니다:

### 📄 `Chart.yaml` (차트 메타데이터)
```yaml
apiVersion: v2
name: my-app
description: 나의 첫 번째 사내 마이크로서비스 Helm Chart
type: application
version: 0.1.0        # 🚀 헬름 차트 자체의 버전 (SemVer)
appVersion: "1.0.0"   # 🚀 배포할 실제 도커 컨테이너 이미지 태그 버전
```

### 📄 `values.yaml` (사용자 입력 기본값)
```yaml
replicaCount: 2

image:
  repository: nginx
  pullPolicy: IfNotPresent
  tag: "1.25-alpine"

service:
  type: ClusterIP
  port: 80
```

### 🧪 배포 전 문법 검증 & 렌더링 시뮬레이션
```bash
# 1. 린트 검사 (문법 및 구조적 오류 탐지)
helm lint ./

# 2. 템플릿 렌더링 미리보기 (클러스터 전송 없이 생성될 YAML 콘솔 출력)
helm template my-release ./

# 3. 드라이 런 (클러스터에 적용하지 않고 API 서버 유효성만 테스트)
helm install my-release ./ --dry-run
```

---

## 6. [초보자 4단계] 템플릿 제어문 & 필수 내장 함수

`templates/*.yaml` 파일 내에서 동적으로 YAML을 제어하는 Go 템플릿 + Sprig 함수 핵심 문법입니다.

### 🧩 1. 기본 값 치환 및 내장 객체
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  # 릴리스 이름과 차트 이름 자동 결합
  name: {{ .Release.Name }}-{{ .Chart.Name }}
  namespace: {{ .Release.Namespace }}
spec:
  replicas: {{ .Values.replicaCount }}
```

### ⚡ 2. 파이프(`|`)와 유용한 함수
- **default**: 값이 없을 때 기본값 할당
  ```yaml
  image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default "latest" }}"
  ```
- **quote**: 안전하게 따옴표로 감싸기
  ```yaml
  PORT: {{ .Values.service.port | quote }}
  ```
- **toYaml & nindent (가장 중요)**: 블록 전체를 들여쓰기하여 주입
  ```yaml
  resources:
    {{- toYaml .Values.resources | nindent 12 }}
  ```
  *(※ `-` 기호는 앞뒤 공백과 개행 문자를 제거해 줍니다)*

### 🔀 3. 조건문 (`if / else / end`)
```yaml
{{- if .Values.ingress.enabled }}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ .Release.Name }}-ingress
spec:
  rules:
    - host: {{ .Values.ingress.host | quote }}
{{- else }}
# Ingress가 비활성화되어 리소스가 생성되지 않습니다.
{{- end }}
```

### 🔁 4. 반복문 (`range`)
```yaml
env:
{{- range $key, $value := .Values.extraEnv }}
  - name: {{ $key }}
    value: {{ $value | quote }}
{{- end }}
```

---

## 7. 차트 의존성 관리 (Subcharts & Dependencies)

내 웹 앱에 Redis 캐시나 PostgreSQL DB 차트를 함께 묶어서 원클릭으로 배포하는 방법입니다.

### 📄 `Chart.yaml`에 의존성 선언
```yaml
apiVersion: v2
name: my-app
version: 0.1.0
appVersion: "1.0.0"

dependencies:
  - name: redis
    version: "19.6.4"
    repository: "https://charts.bitnami.com/bitnami"
    condition: redis.enabled # values.yaml에서 켜고 끌 수 있는 플래그
```

### 📦 의존성 빌드 및 동기화
```bash
# 선언된 서브차트들을 charts/ 폴더로 자동 다운로드
helm dependency update ./

# 빌드 확인
helm dependency build ./
```

---

## 8. 롤백 & 리비전 히스토리 관리 (Rollback)

잘못된 설정이나 이미지 버그로 배포에 실패했을 때, **1초 만에 이전 정상 상태로 되돌리는** Helm의 강력한 기능입니다.

```bash
# 1. 릴리스의 모든 과거 배포 이력(Revision) 조회
helm history my-app

# 출력 예시:
# REVISION  UPDATED                   STATUS          CHART           APP VERSION  DESCRIPTION
# 1         Tue Oct  6 21:00:00 2026  superseded      my-app-0.1.0    1.0.0        Install complete
# 2         Tue Oct  6 21:10:00 2026  deployed        my-app-0.2.0    2.0.0        Upgrade failed!

# 2. 특정 리비전(Revision 1)으로 즉시 롤백
helm rollback my-app 1

# 3. 롤백 완료 후 상태 확인 (새로운 Revision 3이 생성되면서 1번 설정으로 복원됨)
helm status my-app
```

---

## 9. OCI 레지스트리 (Docker Hub / Harbor) 패키징 & 배포

Helm 3.8+부터는 별도 ChartMuseum 없이 **기존 도커 컨테이너 레지스트리(OCI)**에 헬름 차트를 아티팩트로 직접 푸시하고 공유할 수 있습니다.

```bash
# 1. 차트 디렉토리를 .tgz 압축 파일로 패키징
helm package ./my-app
# 생성 파일: my-app-0.1.0.tgz

# 2. OCI 레지스트리 로그인 (Docker Hub, AWS ECR, Harbor 등)
helm registry login registry-1.docker.io -u <사용자명>

# 3. OCI 레지스트리로 차트 푸시
helm push my-app-0.1.0.tgz oci://registry-1.docker.io/<사용자명>

# 4. OCI 레지스트리에서 차트 직접 배포
helm install my-app oci://registry-1.docker.io/<사용자명>/my-app --version 0.1.0
```

---

## 10. CLI 필수 치트시트 테이블

| 명령 분류 | 명령어 | 설명 |
| :--- | :--- | :--- |
| **저장소** | `helm repo add <name> <url>` | 원격 차트 저장소 등록 |
| | `helm repo update` | 등록된 저장소의 차트 목록 최신화 |
| **검색** | `helm search repo <keyword>` | 로컬 저장소에서 차트 검색 |
| | `helm search hub <keyword>` | 공식 Artifact Hub 전체에서 차트 검색 |
| **설치 & 업그레이드** | `helm install <release> <chart>` | 새 릴리스 설치 |
| | `helm upgrade <release> <chart> -f values.yaml` | 설정 반영 무중단 업그레이드 |
| | `helm upgrade --install <release> <chart>` | 없으면 설치, 있으면 업그레이드 (CI/CD 추천) |
| **조회 & 상태** | `helm list -A` | 전체 네임스페이스 배포 릴리스 조회 |
| | `helm status <release>` | 릴리스 상세 정보 및 안내문(NOTES) 확인 |
| | `helm get values <release>` | 해당 릴리스에 적용된 실제 values 값 조회 |
| **복구 & 롤백** | `helm history <release>` | 배포 리비전 이력 확인 |
| | `helm rollback <release> <revision>` | 특정 리비전으로 즉시 원복 |
| **삭제** | `helm uninstall <release>` | 릴리스 및 관련 쿠버네티스 리소스 일괄 삭제 |

---

## 11. 실무 주의사항 & 프로덕션 체크리스트

| 점검 항목 | 권장 사항 | 이유 |
| :--- | :--- | :--- |
| **들여쓰기(Indent) 주의** | `nindent` 숫자 계산을 엄격하게 검증 (`helm template` 확인) | YAML 특성상 1칸만 어긋나도 문법 에러로 배포 차단 |
| **비밀번호 평문 방지** | DB 비밀번호는 `values.yaml`에 직접 적지 말고 `ExternalSecrets` 또는 `SealedSecrets` 사용 | Git 저장소에 비밀번호가 노출되는 보안 사고 방지 |
| **안전 배포 플래그** | CI/CD 배포 시 `--atomic --timeout 5m` 옵션 필수 부여 | Pod 기동 실패 시 배포가 멈추지 않고 자동으로 직전 버전 롤백 |
| **네임스페이스 격리** | `helm install <name> <chart> -n <namespace> --create-namespace` | default 네임스페이스 오염 방지 및 환경별(dev/prod) 분리 |
| **appVersion과 version 구분** | 컨테이너 이미지 태그는 `appVersion`, 차트 템플릿 변경은 `version` 올리기 | SemVer 규격을 준수해야 Helm 의존성 해석 충돌 예방 |
💬
Helm Chart 치트시트

의견 및 질문

댓글 수정

댓글 삭제
