1. 릴리스 저장 구조

1.1 Secret에 저장되는 릴리스 데이터

Helm은 릴리스의 모든 리비전을 Kubernetes Secret으로 관리합니다.

릴리스 Secret 목록 조회

kubectl get secrets -l owner=helm,name=my-release -n default

출력 예시:

sh.helm.release.v1.my-release.v1 helm.sh/release.v1 1 30m

sh.helm.release.v1.my-release.v2 helm.sh/release.v1 1 15m

sh.helm.release.v1.my-release.v3 helm.sh/release.v1 1 5m

각 Secret에 저장되는 데이터 구조:

{

"name": "my-release",

"info": {

"first_deployed": "2026-03-20T10:00:00Z",

"last_deployed": "2026-03-20T10:30:00Z",

"deleted": "",

"description": "Upgrade complete",

"status": "deployed",

"notes": "Release notes..."

},

"chart": { "metadata": {}, "templates": [], "values": {} },

"config": { "replicaCount": 3 },

"manifest": "---\napiVersion: apps/v1\nkind: Deployment...",

"version": 3,

"namespace": "default"

}

1.2 릴리스 히스토리

릴리스 히스토리 조회

helm history my-release

REVISION UPDATED STATUS CHART APP VERSION DESCRIPTION

1 Mon Mar 20 10:00:00 2026 superseded my-app-1.0.0 1.0.0 Install complete

2 Mon Mar 20 10:15:00 2026 superseded my-app-1.1.0 1.1.0 Upgrade complete

3 Mon Mar 20 10:30:00 2026 deployed my-app-1.2.0 1.2.0 Upgrade complete

최대 히스토리 수 제한 (기본 10)

helm upgrade my-release ./my-chart --history-max 5

2. Install 플로우

2.1 helm install 내부 동작

1. 차트 로드 및 의존성 해결

↓

2. values 병합 (기본값 + 사용자 값)

↓

3. 템플릿 렌더링 (Go template 실행)

↓

4. YAML 유효성 검증

↓

5. CRD 설치 (crds/ 디렉터리)

↓

6. pre-install 훅 실행

↓

7. Kubernetes API로 리소스 생성 (kubectl apply 유사)

↓

8. 릴리스 Secret 저장 (status: deployed)

↓

9. post-install 훅 실행

↓

10. NOTES.txt 출력

2.2 주요 플래그

기본 설치

helm install my-release ./my-chart

네임스페이스 지정 (없으면 생성)

helm install my-release ./my-chart -n production --create-namespace

values 오버라이드

helm install my-release ./my-chart \

-f production-values.yaml \

--set image.tag=v2.0.0 \

--set-string annotations."app\.version"="2.0"

드라이런 (실제 설치하지 않음)

helm install my-release ./my-chart --dry-run

서버 사이드 드라이런 (API 서버 검증 포함)

helm install my-release ./my-chart --dry-run=server

Atomic: 실패 시 자동 롤백

helm install my-release ./my-chart --atomic --timeout 5m

Wait: 모든 리소스가 Ready 상태가 될 때까지 대기

helm install my-release ./my-chart --wait --timeout 10m

3. Upgrade 플로우

3.1 helm upgrade 내부 동작

1. 이전 릴리스 리비전 로드

↓

2. 새 차트/values로 템플릿 렌더링

↓

3. Three-way Strategic Merge Patch 계산

↓

4. pre-upgrade 훅 실행

↓

5. 변경된 리소스만 API 서버에 적용

↓

6. 새 릴리스 리비전 Secret 저장

↓

7. 이전 리비전 상태를 superseded로 업데이트

↓

8. post-upgrade 훅 실행

3.2 Three-way Strategic Merge Patch

Helm 3의 핵심 개선 사항입니다. 세 가지 상태를 비교합니다:

이전 릴리스 매니페스트 (Old Chart)

↕ 비교

현재 라이브 상태 (Live State)

↕ 비교

새 릴리스 매니페스트 (New Chart)

이 방식의 장점:

- kubectl로 직접 수정한 변경사항을 인식

- 불필요한 리소스 재생성을 방지

- 사용자의 수동 변경을 안전하게 병합

업그레이드

helm upgrade my-release ./my-chart -f new-values.yaml

설치되어 있지 않으면 설치, 있으면 업그레이드

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

이전 values를 유지하면서 일부만 변경

helm upgrade my-release ./my-chart --reuse-values --set image.tag=v2.1.0

values를 완전히 초기화하고 새로 지정

helm upgrade my-release ./my-chart --reset-values -f new-values.yaml

변경사항 미리보기 (helm-diff 플러그인)

helm diff upgrade my-release ./my-chart -f new-values.yaml

4. Rollback 플로우

4.1 helm rollback 내부 동작

1. 대상 리비전의 릴리스 데이터 로드

↓

2. 해당 리비전의 매니페스트를 "새 매니페스트"로 사용

↓

3. Three-way merge로 변경사항 계산

↓

4. pre-rollback 훅 실행

↓

5. 리소스 적용

↓

6. 새 리비전 번호로 릴리스 저장

↓

7. post-rollback 훅 실행

직전 리비전으로 롤백

helm rollback my-release

특정 리비전으로 롤백

helm rollback my-release 2

롤백 대상 확인

helm history my-release

helm get manifest my-release --revision 2

helm get values my-release --revision 2

**중요**: 롤백은 이전 매니페스트를 복원하는 것이 아니라, 이전 리비전의 차트와 values를 기반으로 새 리비전을 생성합니다.

5. Hook 시스템

5.1 Hook 종류

| Hook | 실행 시점 |

| ------------- | ---------------------------------- |

| pre-install | 템플릿 렌더링 후, 리소스 생성 전 |

| post-install | 모든 리소스가 클러스터에 로드된 후 |

| pre-delete | 삭제 요청 시, 리소스 삭제 전 |

| post-delete | 모든 리소스 삭제 후 |

| pre-upgrade | 업그레이드 시, 리소스 업데이트 전 |

| post-upgrade | 리소스 업데이트 후 |

| pre-rollback | 롤백 시, 리소스 롤백 전 |

| post-rollback | 리소스 롤백 후 |

| test | helm test 실행 시 |

5.2 Hook 정의 예시

apiVersion: batch/v1

kind: Job

metadata:

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

annotations:

"helm.sh/hook": pre-upgrade,pre-install

"helm.sh/hook-weight": "-5"

"helm.sh/hook-delete-policy": before-hook-creation

spec:

template:

spec:

restartPolicy: Never

containers:

- name: migrate

image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"

command: ["./migrate", "--up"]

5.3 Hook 가중치(Weight)

Hook은 가중치에 따라 정렬되어 순차 실행됩니다:

먼저 실행 (가중치 -5)

"helm.sh/hook-weight": "-5"

나중에 실행 (가중치 5)

"helm.sh/hook-weight": "5"

5.4 Hook 삭제 정책

| 정책 | 설명 |

| -------------------- | --------------------------------------- |

| before-hook-creation | 새 Hook 실행 전에 이전 Hook 리소스 삭제 |

| hook-succeeded | Hook 성공 시 삭제 |

| hook-failed | Hook 실패 시 삭제 |

6. Uninstall 플로우

릴리스 삭제

helm uninstall my-release

히스토리 유지하며 삭제

helm uninstall my-release --keep-history

드라이런

helm uninstall my-release --dry-run

삭제 타임아웃

helm uninstall my-release --timeout 5m

Uninstall 동작:

1. pre-delete 훅 실행

2. 릴리스의 모든 Kubernetes 리소스 삭제

3. post-delete 훅 실행

4. 릴리스 Secret 삭제 (--keep-history가 없는 경우)

**주의**: CRD는 uninstall로 삭제되지 않습니다. 수동 삭제가 필요합니다.

7. Atomic Install과 Wait

7.1 --wait 플래그

helm install my-release ./my-chart --wait --timeout 10m

--wait는 다음 조건이 충족될 때까지 대기합니다:

- Deployment/StatefulSet: 모든 Pod가 Ready

- Service: LoadBalancer 타입의 경우 IP/호스트네임 할당

- Pod: Running 상태

- Job: Complete 상태

- PVC: Bound 상태

7.2 --atomic 플래그

helm install my-release ./my-chart --atomic --timeout 5m

--atomic은 --wait를 포함하며, 추가로:

- 설치 실패 시 자동으로 uninstall 수행

- 업그레이드 실패 시 자동으로 이전 리비전으로 rollback

7.3 --wait-for-jobs

helm install my-release ./my-chart --wait --wait-for-jobs --timeout 10m

Job과 Hook Job이 완료될 때까지 추가로 대기합니다.

8. 릴리스 정보 조회

릴리스 목록

helm list -n default

helm list --all-namespaces

릴리스 상세 정보

helm status my-release

릴리스에 사용된 values

helm get values my-release

helm get values my-release --all # 기본값 포함

helm get values my-release --revision 2 # 특정 리비전

릴리스의 렌더링된 매니페스트

helm get manifest my-release

릴리스 노트

helm get notes my-release

모든 정보

helm get all my-release

9. 정리

Helm 릴리스 생명주기의 핵심:

1. **Secret 기반 리비전 관리**: 모든 릴리스 히스토리를 Kubernetes Secret으로 관리

2. **Three-way Merge**: 이전 매니페스트, 라이브 상태, 새 매니페스트를 비교하여 안전한 업그레이드

3. **Hook 시스템**: 릴리스 생명주기의 각 단계에 사용자 정의 로직 삽입

4. **Atomic 배포**: 실패 시 자동 롤백으로 안정성 보장

5. **히스토리 기반 롤백**: 이전 리비전의 차트/values를 기반으로 새 리비전 생성

다음 글에서는 Helm 플러그인 시스템과 테스트 전략을 다룹니다.