📗 프로비저닝 - Helm

🏳️‍🌈 [궁금한점]

• Helm 개요, 아키텍처

---

🔗[목차]

• Helm 설치
  • Helm 일반 설치 ( v3.17.1 )
  • Helm 버전 지정 설치 ( v3.8.0 )
  • Helm 차트 직접 내려받기
• Helm 릴리즈 관리
  • Helm 릴리스 저장 방식
  • Helm 업그레이드/롤백 흐름
• Helm 템플릿 렌더링 구조
  • Helm 템플릿 구조
  • Helm 템플릿 렌더링 흐름
  • Helm 템플릿 문법 예시
• Helm 사용법
  • Helm 릴리스 정보 확인 명령어
  • Kubernetes 내 저장 구조 (Secret 또는 ConfigMap)
  • Helm 템플릿 디버깅 및 검증
  • Helm 활용 팁 및 고급 기능
• Helm 아키텍처 구성 요소
  • Helm CLI (helm)
  • Chart
  • Release
  • Helm Repository
  • Kubernetes API Server

Helm 설치

Helm 일반 설치 ( v3.17.1 )

curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
chmod 700 get_helm.sh
./get_helm.sh

vagrant@slave1:~$ helm version
version.BuildInfo{Version:"v3.17.1", GitCommit:"980d8ac1939e39138101364400756af2bdee1da5", GitTreeState:"clean", GoVersion:"go1.23.5"}

Helm 버전 지정 설치 ( v3.8.0 )

export HELM_VERSION="v3.8.0"
wget https://get.helm.sh/helm-$HELM_VERSION-linux-amd64.tar.gz
tar -xzf helm-$HELM_VERSION-linux-amd64.tar.gz
sudo mv linux-amd64/helm /usr/local/bin/helm

vagrant@slave4:~$ helm version
version.BuildInfo{Version:"v3.8.0", GitCommit:"d14138609b01886f544b2025f5000351c9eb092e", GitTreeState:"clean", GoVersion:"go1.17.5"}

Helm 차트 직접 내려받기

helm repo add trino https://trinodb.github.io/charts/
helm pull trino/trino --version 1.39.0 --untar
cd trino

Helm 릴리즈 관리

Helm은 Chart + values.yaml 조합으로 Kubernetes 리소스를 생성하고 이를 "릴리스(Release)"라는 단위로 관리한다.
릴리스(Release)란 Chart를 클러스터에 설치한 인스턴스로 Chart 이름과 사용자 값(values)의 조합으로 생성된다.

helm install myapp ./mychart -f prod-values.yaml

→ 이때 myapp이 릴리스 이름이 됨

Helm 릴리스 저장 방식

• Helm은 릴리스 정보를 Kubernetes 내부에 저장함
• 기본적으로 Secret 또는 ConfigMap 리소스를 사용
• Namespace에 따라 저장 위치가 다름
• 릴리스에는 설치된 Chart 버전, 적용된 values, 렌더링된 리소스, 릴리스 버전 (v1, v2, … 업그레이드마다 증가)이 포함됨

Helm 업그레이드/롤백 흐름

• helm upgrade → 새로운 values 적용 후 변경된 리소스만 diff 후 업데이트
• helm rollback → 이전 릴리스 버전으로 되돌림
• Helm이 3-way merge를 이용해 리소스 변경점을 계산함

Helm 템플릿 렌더링 구조

Helm의 Chart는 단순한 YAML이 아니라 Go 템플릿 엔진을 기반으로 동작한다.

Helm 템플릿 구조

mychart/
├── Chart.yaml          # Chart 메타 정보
├── values.yaml         # 기본 값 설정
└── templates/
    ├── deployment.yaml # Go 템플릿
    ├── service.yaml
    └── _helpers.tpl    # 공통 템플릿 조각

Helm 템플릿 렌더링 흐름

• helm install 또는 helm template 명령 실행
• CLI가 templates/*.yaml 파일에서 Go 템플릿 구문({{ }})을 찾아 파싱
• values.yaml, CLI로 넘긴 -f 파일, --set 값들을 머지
• 템플릿 안에 .Values. 또는 .Chart, .Release 등 context 변수를 바인딩
• 실제 Kubernetes YAML 생성
• helm install 시 API 서버에 apply, helm template 시 출력만

Helm 템플릿 문법 예시

apiVersion: v1
kind: Service
metadata:
  name: {{ include "mychart.fullname" . }}
spec:
  type: {{ .Values.service.type }}
  ports:
    - port: {{ .Values.service.port }}

템플릿에서 .Values는 values.yaml의 key에 접근하는 구문이다.

Helm 사용법

Helm 릴리스 정보 확인 명령어

helm list
helm status <RELEASE_NAME>
helm get all <RELEASE_NAME>
helm get manifest <RELEASE_NAME>
helm get values <RELEASE_NAME>
helm history <RELEASE_NAME>

helm get manifest myapp

→ Helm이 렌더링하여 Kubernetes에 적용한 리소스들을 그대로 보여준다.

Kubernetes 내 저장 구조 (Secret 또는 ConfigMap)

Helm은 릴리스 정보를 다음과 같은 형태로 저장한다

kubectl get secret -n <namespace> -l "owner=helm"

이렇게 저장된 Secret에는 다음 정보가 base64로 인코딩되어 들어 있다

• release name
• version
• chart 정보
• values.yaml
• 렌더링된 리소스

Secret 내용을 확인하는 방법으로 아래처럼 사용이 가능하다.

kubectl get secret sh.helm.release.v1.myapp.v1 -n default -o json | jq '.data.release' | base64 -d | base64 -d | less

• base64 -d를 두 번 사용하는 이유는 Helm이 이중으로 인코딩하기 때문입니다.

Helm 템플릿 디버깅 및 검증

명령어	목적	설명	클러스터 영향 여부
helm lint ./mychart	정적 검증	Chart 구조 및 템플릿 문법 오류 체크	아니오
helm template ./mychart -f values.yaml	렌더링 확인	Helm 템플릿을 실제 Kubernetes YAML로 변환하여 출력	아니오
helm install RELEASE ./mychart --dry-run --debug -f values.yaml	시뮬레이션	실제 설치 없이 렌더링, 병합된 values, 릴리스 메타 확인	아니오
helm get manifest RELEASE	적용 결과 확인	설치된 Helm 릴리스가 생성한 리소스 목록을 출력	예 (설치 후 사용)
helm get values RELEASE --all	적용된 값 확인	릴리스에 사용된 모든 values 확인 (기본값 + override 포함)	예
helm get all RELEASE	전체 정보 확인	values, manifest, notes 등 전체 릴리스 정보 출력	예

Helm 활용 팁 및 고급 기능

기능	명령어 / 템플릿	설명
다중 values 파일 병합	-f base.yaml -f dev.yaml	여러 values.yaml 파일을 계층적으로 적용 (뒤에 있는 것이 우선순위 높음)
CLI 값 오버라이드	--set image.tag=1.2.3	빠르게 특정 파라미터만 덮어쓸 수 있음
조건부 리소스 생성	{{- if .Values.enabled }} ... {{- end }}	특정 값이 true일 때만 리소스 생성됨
템플릿 재사용 (_helpers.tpl)	{{ include "mychart.fullname" . }}	공통 네이밍, 라벨 등을 정의하여 반복 제거 및 유지보수 용이
파일 포함 (.Files.Get)	{{ .Files.Get "config/config.json" }}	외부 설정 파일을 ConfigMap 등에 삽입 가능
Hooks (사전/사후 작업)	annotations: "helm.sh/hook": pre-install	Job 등을 사용해 DB 마이그레이션, 초기화 등을 설치 전/후에 실행 가능
릴리스별 값 확인	helm get values <RELEASE>	실제 배포에 사용된 모든 values 확인 가능
템플릿 디버깅	--dry-run --debug, helm template	클러스터에 반영되지 않고 렌더링 결과 확인 가능
릴리스 기록 확인	helm history <RELEASE>	이전 배포 버전 히스토리 확인, 롤백 기반 정보 확보 가능
롤백	helm rollback <RELEASE> <REVISION>	이전 버전으로 되돌리기, 장애 대응에 유용

Helm 아키텍처 구성 요소

Helm CLI (helm)

사용자가 직접 사용하는 명령줄 도구이다.

• Chart 설치 (helm install)
• 릴리스 업그레이드 (helm upgrade)
• 릴리스 상태 조회 (helm status)
• 릴리스 삭제 (helm uninstall)
• Chart를 렌더링하여 Kubernetes에 적용할 수 있는 실제 매니페스트(예: Deployment, Service) 생성
• Kubernetes API 서버와 직접 통신하여 릴리스를 설치 및 관리

Chart

• Helm에서 사용하는 패키지 단위로, Kubernetes 리소스 템플릿과 메타데이터가 포함된 디렉토리 구조

mychart/
├── Chart.yaml       # Chart 이름, 버전, 설명 등의 메타 정보
├── values.yaml      # 사용자 정의 설정의 기본값
├── templates/       # Go 템플릿 엔진 기반의 Kubernetes 리소스 파일들
└── charts/          # 의존하는 다른 Chart들

• Chart는 GitHub, Helm repository 등에서 내려받아 사용할 수 있음

Release

• 특정 시점에 특정 Chart가 특정 값을 가지고 설치된 결과
• Helm은 Chart + values.yaml 조합을 기반으로 Kubernetes 리소스를 생성하고 관리
• 동일한 Chart를 여러 번 설치하면 각각 별개의 Release가 됨

Helm Repository

• Chart를 저장하고 배포하는 HTTP 기반 저장소
• index.yaml 파일을 통해 어떤 Chart가 어떤 버전으로 제공되는지 정의
• 사용자가 helm repo add, helm repo update 명령어를 통해 저장소 추가 및 동기화 가능

Kubernetes API Server

• Helm CLI는 직접 Kubernetes API Server에 연결하여 Chart로부터 생성된 리소스를 배포/관리함