Helm

개요

Helm은 Kubernetes의 패키지 매니저입니다.

Linux의 apt나 yum, macOS의 Homebrew처럼, Kubernetes 애플리케이션을 패키지 형태로 관리하기 위해 사용한다고 합니다.

처음 쿠버네티스를 보고 어렵게 느껴진 점은, 배포를 위해 상당히 많은 yaml 파일이 필요한 것이었습니다. 쿠버네티스에서 애플리케이션을 배포하려면 여러 개의 YAML 파일(Deployment, Service, ConfigMap 등)을 작성하고 관리해야 합니다.

이 모든 과정을 수동으로 하나씩 관리하고, 환경별로 다른 설정을 관리하기 어렵겠다는 생각이 들었습니다.

Helm은 이러한 문제를 해결하기 위해 사용합니다:

여러 Kubernetes 리소스를 Chart라는 패키지로 묶습니다
**템플릿 변수 Values**를 통해 환경별로 다른 값을 주입할 수 있습니다
버전 관리와 롤백 기능을 제공합니다
재사용 가능한 패키지를 만들 수 있습니다

Helm의 개념부터 각 구성 요소를 간략한 스크립트와 함께 파악해보겠습니다.

Helm의 핵심 개념

Chart

Chart는 Kubernetes 애플리케이션을 정의하는 파일들의 묶음입니다.
하나의 Chart에는 애플리케이션 배포에 필요한 모든 리소스 정의가 포함됩니다.

my-chart/
├── Chart.yaml          # Chart 메타데이터
├── values.yaml         # 기본 설정 값
├── templates/          # Kubernetes 리소스 템플릿
│   ├── deployment.yaml
│   ├── service.yaml
│   └── configmap.yaml
└── charts/             # 의존성 Chart (선택사항)

`Values.yaml`

values.yaml은 Chart의 설정을 중앙에서 관리하는 파일입니다.
템플릿 파일에서 {{ .Values.xxx }}로 참조하여 동적으로 값을 주입할 수 있습니다.
일반적인 .env.dev, .env.prod 같은 env 파일을 특정한 포맷의 yaml 파일로 관리한다-고 일단 이해했습니다.

ex: Github Actions에서 {{secrets.DEPLOY_TOKEN}} 같은 환경 변수 주입을 관리하는 파일

장점:

환경별로 다른 values 파일 사용 (values-dev.yaml, values-prod.yaml)
배포 시 --set 옵션으로 특정 값만 변경 가능
코드 중복 없이 여러 환경 관리

`Release`

Release는 Chart를 Kubernetes 클러스터에 설치한 인스턴스라고 합니다.
같은 Chart를 여러 번 설치하면 각각 다른 Release가 생성됩니다.

예: my-app-dev, my-app-staging, my-app-prod

`Repository`

Chart를 저장하고 공유하는 저장소입니다.
공개 저장소(Artifact Hub)나 프라이빗 저장소를 사용할 수 있습니다.

Kubernetes 환경 구성

Helm을 사용하기 전에 먼저 Kubernetes 클러스터가 필요합니다.
로컬 개발 환경에서는 K3s(Linux) 또는 k3d(macOS/Docker)를 사용하는 것이 권장됩니다.

환경 선택 가이드

k3s, k3d는 클러스터를 생성하기 위해 사용하는 도구-로 이해했습니다.

환경	도구	특징
Linux 서버	K3s	네이티브 설치, 리소스 효율적
macOS	k3d	Docker 기반, 쉬운 설치/삭제
Windows	k3d	Docker Desktop 필요
학습/테스트	minikube	다양한 드라이버 지원

VM 환경에서 보통 리눅스를 사용하고, 제 호스트는 맥OS이니 k3s, k3d 모두 알아보도록 하겠습니다.

Linux: K3s 설치

k3s는 경량 Kubernetes 배포판이라고 합니다.
(단일 바이너리로 설치되며 메모리 사용량이 절반 이하-라고 하는데, 정확히 이해되지는 않습니다.)

K3s.io의 설치 가이드가 잘 정리되어있습니다.

# K3s 설치
curl -sfL https://get.k3s.io | sh - 
# Check for Ready node, takes ~30 seconds 
sudo k3s kubectl get node 

# kubeconfig 설정
mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $USER:$USER ~/.kube/config

k3s-init

옵션 설명:

--write-kubeconfig-mode 644: kubeconfig 파일을 일반 사용자가 읽을 수 있게 설정
--disable traefik: 기본 Ingress Controller 비활성화 (커스텀 구성을 위해)
--disable servicelb: 기본 LoadBalancer 비활성화

확인:

kubectl get nodes
# NAME     STATUS   ROLES                  AGE   VERSION
# server   Ready    control-plane,master   10s   v1.28.4+k3s1

macOS/Windows: k3d 설치

k3d는 Docker 컨테이너 안에서 K3s를 실행합니다. 따라서 클러스터 생성/삭제가 매우 빠릅니다.

# k3d 설치 (macOS)
curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash

# 또는 Homebrew 사용
brew install k3d

# 클러스터 생성
k3d cluster create test-cluster \
  --api-port 6443 \
  --port "80:80@server:0" \
  --port "443:443@server:0" \
  --agents 2 \
  --wait

# kubeconfig 자동 설정
k3d kubeconfig merge test-cluster --kubeconfig-switch-context

k3d-1

옵션 설명:

--api-port 6443: Kubernetes API 서버 포트
--port "80:80@server:0": 호스트의 80번 포트를 클러스터로 포워딩
--agents 2: Worker 노드 2개 생성
--wait: 클러스터가 Ready 상태가 될 때까지 대기

확인:

kubectl get nodes

k3d-2

클러스터 관리 명령어:

# 클러스터 목록
k3d cluster list

# 클러스터 중지
k3d cluster stop test-cluster

# 클러스터 시작
k3d cluster start test-cluster

# 클러스터 삭제
k3d cluster delete test-cluster

k3d-4

Helm 설치

Kubernetes 클러스터를 생성하였으니, 이제 Helm을 설치하고 사용해보겠습니다. Helm Chart 개발 가이드를 참조하였고,
앞서 k3d로 생성한 테스트 클러스터와 helm을 연동합니다.
이번 글에서는 Helm 기본 템플릿을 사용하고, 기본적인 cli 조작법과 플로우를 실습으로 간략히 알아보았습니다.

Linux/macOS

# 공식 설치 스크립트 사용
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

macOS (Homebrew)

brew install helm

설치 확인

helm version
# version.BuildInfo{Version:"v3.13.0", GitCommit:"...", GitTreeState:"clean", GoVersion:"go1.21.3"}

# Kubernetes 클러스터 연결 확인
kubectl cluster-info

Helm 사용 단계

1. Chart 생성

새로운 애플리케이션을 위한 Chart를 생성했습니다.

helm create helm-tutorial

생성된 구조:

helm-tutorial/
├── .helmignore         # Helm이 무시할 파일
├── Chart.yaml          # Chart 메타데이터
├── values.yaml         # 기본 설정
├── charts/             # 의존성 Chart
└── templates/          # Kubernetes 리소스 템플릿
    ├── deployment.yaml
    ├── service.yaml
    ├── ingress.yaml
    ├── _helpers.tpl    # 템플릿 헬퍼
    └── NOTES.txt       # 배포 후 안내 메시지

3-helm-1

많은 파일들이 생성된 것을 알 수 있습니다.

2. Chart 커스터마이징

이제 앞서 학습한 내용을 바탕으로 간단한 수정을 해보며 파일 내부를 직접 살펴보겠습니다.

Chart.yaml 수정:

apiVersion: v2
name: helm-tutorial
description: 튜토리얼 용 헬름 차트
type: application
version: 0.1.0
appVersion: "1.0.0"

values.yaml 수정:

replicaCount: 2

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

service:
  type: ClusterIP
  port: 80

resources:
  requests:
    memory: "128Mi"
    cpu: "100m"
  limits:
    memory: "256Mi"
    cpu: "200m"

templates/deployment.yaml에서 값 참조:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}
spec:
  replicas: {{ .Values.replicaCount }}
  template:
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          resources:
            {{- toYaml .Values.resources | nindent 12 }}

3. Chart 검증

배포하기 전에 Chart가 올바르게 작성되었는지 검증합니다.
위에서 수정한 yaml 파일이 제대로 구성되었는지 확인하고,
--dry-run 옵션을 통해 시뮬레이션한다고 합니다.

# 템플릿 렌더링 결과 확인 (실제 배포는 하지 않음)
helm template helm-tutorial ./helm-tutorial

3-helm-2

# 문법 검사
helm lint ./helm-tutorial

3-helm-3

# 드라이런 (시뮬레이션)
helm install helm-tutorial ./helm-tutorial --dry-run --debug

3-helm-4

4. Chart 설치 (배포)

마지막으로 Chart를 Kubernetes 클러스터에 배포합니다.

# 기본 설치
helm install my-release ./helm-tutorial

# 네임스페이스 지정
helm install my-release ./helm-tutorial \
  --namespace my-namespace \
  --create-namespace

# 값 오버라이드
helm install my-release ./helm-tutorial \
  --set replicaCount=3 \
  --set image.tag=1.26

# values 파일 지정
helm install my-release ./helm-tutorial \
  -f values-production.yaml

# 모든 리소스가 Ready 상태가 될 때까지 대기
helm install my-release ./helm-tutorial --wait --timeout 5m

3-helm-5 3-helm-6

배포 후 확인:

# Release 목록
helm list

# Release 상태 확인
helm status my-release

# 배포된 리소스 확인
kubectl get all -l app.kubernetes.io/instance=my-release

3-helm-7

5. Chart 업그레이드

설정을 변경하거나 새 버전을 배포할 때 사용합니다.

# values 변경하여 업그레이드
helm upgrade my-release ./helm-tutorial \
  --set replicaCount=5

# 기존 values 유지하면서 특정 값만 변경
helm upgrade my-release ./helm-tutorial \
  --reuse-values \
  --set image.tag=1.27

# 없으면 설치, 있으면 업그레이드
helm upgrade --install my-release ./helm-tutorial

6. 롤백

문제가 발생했을 때 이전 버전으로 되돌립니다.

일반적인 CI/CD 환경과 같이, Helm 역시 롤백 기능을 제공합니다. 간략히 cli를 알아보면 다음과 같습니다.

# 릴리스 히스토리 확인
helm history my-release

# 이전 버전으로 롤백
helm rollback my-release 1

# 바로 이전 버전으로 롤백
helm rollback my-release

7. Chart 삭제

# Release 삭제 (Kubernetes 리소스 제거)
helm uninstall my-release

# 네임스페이스 지정
helm uninstall my-release -n my-namespace

다음 글에선 현재 진행 중인 프로젝트 c2z에 클러스터와 Helm Chart 구성 등을 살펴보도록 하겠습니다.

개요​

Helm의 핵심 개념​

Chart​

Values.yaml​

Release​

Repository​

Kubernetes 환경 구성​

환경 선택 가이드​

Linux: K3s 설치​

macOS/Windows: k3d 설치​

Helm 설치​

Linux/macOS​

macOS (Homebrew)​

설치 확인​

Helm 사용 단계​

1. Chart 생성​

2. Chart 커스터마이징​

3. Chart 검증​

4. Chart 설치 (배포)​

5. Chart 업그레이드​

6. 롤백​

7. Chart 삭제​

참고 자료​

개요