Helm의 기본

Helm이란?

• Kubernetes용 패키지 관리자
• 복잡한 Application을 하나의 패키지(Chart)로 관리
• 환경에 따라 다른 설정은 values.yaml로 분리하여 관리

Chart란?

• Kubernetes Application을 정의하는 패키지 단위
• values.yaml을 기반으로 다양한 환경에 맞게 리소스를 생성하는 템플릿 구조

구성 요소

구성 요소	설명
Chart.yaml	차트의 메타데이터 (이름, 버전, 설명 등)
values.yaml	환경별 설정값을 정의하는 기본 파일
templates/	Kubernetes 리소스 템플릿 (YAML)
charts/	의존 서브 차트
README.md	(선택) 차트 설명 및 사용법 문서

my-chart/
├── Chart.yaml
├── values.yaml
├── templates/
│   ├── deployment.yaml
│   └── service.yaml
├── charts/
└── README.md

차트의 핵심 장점

장점	설명	예시
템플릿화	환경별 다른 설정 적용 동적 값 주입 가능	개발 1개, 운영 3개 레플리카
의존성 관리	복잡한 구성 요소 자동 해결 순차적 배포 보장	DB + 캐시 + 앱 순차 배포
버전 관리	쉬운 업그레이드와 롤백 리비전 히스토리 관리	문제 시 이전 버전 복구
릴리스 관리	동일 차트로 여러 환경 배포 독립적인 인스턴스 관리	동일 앱의 dev/staging 버전

Helm에서 Application이란?

• 하나의 차트를 기반으로 Kubernetes 클러스터 내에 생성되는 리소스 집합
  • ex) Deployment, Service, ConfigMap, Ingress, PVC 등 포함
• Helm은 이를 “릴리스” 단위로 설치/업그레이드/삭제하며, 사용자 지정 이름으로 관리됩니다.
  • ex) “my-app” 처럼 사용자가 지정한 이름으로 릴리스(=Application) 관리
• Helm은 이를 “릴리스” 단위로 설치/업그레이드/삭제하며, 사용자 지정 이름으로 관리됩니다.

Helm 설치 및 설정

클라이언트 설치

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

# 설치 확인
helm version

저장소 관리

작업	명령어
저장소 추가	helm repo add <repo-name> <url>
저장소 목록	helm repo list
저장소 업데이트	helm repo update
저장소 삭제	helm repo remove <repo-name>

# 주요 저장소 추가
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update

Chart 탐색 및 정보 확인

Chart 검색

검색 대상	방법	설명
저장소 내	helm search repo <keyword>	등록된 저장소에서 차트 검색
Artifact Hub	artifacthub.io	다양한 공개 차트 검색 가능 (웹 기반)

⚠️ Deprecated: helm search hub <keyword>는 현재 사용되지 않음. Artifact Hub 사용 권장.

Chart 상세 정보

정보	명령어	설명
차트 메타	helm show chart <chart>	버전, 설명, 유지관리자 확인
사용 가이드	helm show readme <chart>	사용법과 요구사항 안내
기본 설정값	helm show values <chart>	차트에 정의된 초기값 (릴리스 이전)
적용된 설정값	helm get values <release>	릴리스에 실제 적용된 설정값
전체 보기	helm show all <chart>	모든 정보 통합 확인

Application 배포

• 여기서 Application은 Helm 차트를 통해 배포되는 Kubernetes 리소스들의 집합을 의미

기본 배포 방법

# 기본 설정으로 배포
helm install my-app bitnami/nginx

# 네임스페이스 지정하여 배포
helm install my-app bitnami/nginx -n web --create-namespace

# 사용자 정의 설정으로 배포
helm install my-app bitnami/nginx \
  --set service.type=LoadBalancer \
  --set replicaCount=3

Values 파일을 활용한 배포

# 현재 설정값 추출
helm get values my-app > current-values.yaml

# 커스텀 Values 파일 생성
cat > custom-values.yaml <<EOF
replicaCount: 3
service:
  type: LoadBalancer
  port: 80
resources:
  requests:
    memory: 256Mi
    cpu: 250m
  limits:
    memory: 512Mi
    cpu: 500m
EOF

# Values 파일로 배포
helm install my-app bitnami/nginx -f custom-values.yaml

릴리스 관리

릴리스 상태 확인

작업	명령어	설명
릴리스 목록 조회	helm list	설치된 릴리스 목록 확인
릴리스 상태 확인	helm status <release>	릴리스 상태 및 접근 정보
릴리스 이력 조회	helm history <release>	리비전별 변경 내역 확인
적용 설정 확인	helm get values <release>	현재 적용된 설정값 확인

업그레이드 및 롤백

작업	명령어	설명
업그레이드	helm upgrade <release> <chart> --reuse-values	기존 설정을 유지한 채로 차트를 최신 버전으로 업그레이드
설정 변경	helm upgrade <release> <chart> --set key=value 또는 -f 옵션 사용	새로운 설정 값을 적용하여 업그레이드
롤백	helm rollback <release>	직전 릴리스로 되돌림
특정 리비전 롤백	helm rollback <release> <revision>	지정한 리비전으로 복원

# 업그레이드 예시
helm upgrade my-app bitnami/nginx \
  --set replicaCount=5 \
  --reuse-values

# 롤백 예시
helm rollback my-app

환경별 설정 관리

개발/운영 환경 분리

환경	설정 특징	Values 예시
개발	최소 리소스 빠른 배포	replicaCount: 1, memory: 512Mi
스테이징	중간 리소스 운영 유사	replicaCount: 2, memory: 1Gi
운영	고가용성 최적 성능	replicaCount: 3, memory: 2Gi

# 환경별 Values 파일
cat > dev-values.yaml <<EOF
replicaCount: 1
resources:
  requests:
    memory: 512Mi
persistence:
  size: 5Gi
EOF

cat > prod-values.yaml <<EOF
replicaCount: 3
resources:
  requests:
    memory: 2Gi
persistence:
  size: 100Gi
service:
  type: LoadBalancer
EOF

# 환경별 배포
helm install dev-app chart-name -f dev-values.yaml -n dev
helm install prod-app chart-name -f prod-values.yaml -n production

배포 전 검증과 디버깅

검증 방법

검증 방법	명령어	용도
Dry Run	helm install <release> <chart> --dry-run --debug	실제 배포 없이 시뮬레이션 오류 사전 발견
템플릿 렌더링	helm template <repo-name> <chart>	생성될 YAML 미리 확인 템플릿 변수 검증
차트 검증	helm lint <chart-path>	차트 문법 오류 확인 베스트 프랙티스 검사

문제 해결과 트러블슈팅

문제 진단

문제 상황	진단 명령어	설명
배포 실패	helm status <release> kubectl describe pod <pod>	릴리스 상태 및 관련 Pod 이벤트 확인
설정 오류	helm get values <release> helm show values <chart>	현재 적용된 설정과 기본 설정 비교
업그레이드 실패	helm history <release> helm rollback <release>	변경 이력 확인 및 롤백을 통한 복구 시도

릴리스 정리

정리 대상	명령어	설명
릴리스	helm uninstall <release>	릴리스만 제거됨 PVC 등 데이터는 유지됨
PVC	kubectl delete pvc --all	모든 PVC 삭제 (다른 리소스에는 영향 없음)
네임스페이스	kubectl delete namespace <namespace>	네임스페이스와 모든 리소스가 함께 삭제됨

안전한 정리 스크립트

#!/bin/bash

# 1. 릴리스 삭제
helm uninstall my-app

# 2. PVC 별도 확인 후 삭제
kubectl get pvc  # 남아있는 PVC 확인
kubectl delete pvc --all

# 3. 네임스페이스 삭제
kubectl delete namespace test

고급 활용

차트 개발 기초

작업	명령어	설명
차트 생성	helm create <chart-name>	기본 템플릿 구조 생성
차트 검사	helm lint <chart-path>	문법 오류 및 권장사항 확인
패키지 생성	helm package <chart-path>	배포 가능한 .tgz 생성

저장소 관리

작업	명령어	설명
인덱스 생성	helm repo index ./charts/	로컬 저장소 인덱스 생성
인증 저장소 추가	helm repo add myrepo <url> --username <user>	인증 기반 저장소 등록

보안 고려사항

• 공식 차트 혹은 신뢰할 수 있는 저장소만 사용
• 민감 정보는 values.yaml에 직접 작성하지 않고, Kubernetes Secret으로 분리 관리
• Helm은 Secret을 자체적으로 암호화하지 않으므로, 외부 도구와 함께 사용하는 것이 바람직함
  • ex) SealedSecrets, KES 등
• Helm 명령어에 대한 RBAC 권한을 최소화하여 보안 유지

RBAC (Role-Based Access Control)?

• 사용자가 Kubernetes 리소스에 대해 어떤 작업을 어디서 할 수 있는지를 제어하는 권한 관리 시스템
  • Helm은 Kubernetes 리소스를 생성하는 도구
  • 그러므로 Helm 명령어를 실행하는 사용자 또는 서비스 계정에 적절한 권한을 부여해야 한다.
  • Kubernetes에서는 이를 RBAC(Role-Based Access Control) 정책으로 관리한다.

주요 구성 요소

구성 요소	설명
Role	특정 네임스페이스에 대한 권한 정의
ClusterRole	클러스터 전체에 적용되는 권한 정의
RoleBinding	사용자/서비스 계정을 Role에 연결
ClusterRoleBinding	사용자/서비스 계정을 ClusterRole에 연결

예시: 네임스페이스 내 Pod 읽기 권한 부여

# Role
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: dev
  name: pod-reader
rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "list", "watch"]

# RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: read-pods
  namespace: dev
subjects:
- kind: User
  name: dev-user
roleRef:
  kind: Role
  name: pod-reader
  apiGroup: rbac.authorization.k8s.io

Helm과 RBAC 보안 팁

• Helm 작업에 사용하는 사용자 또는 서비스 계정에는 필요 최소 권한만 부여
• 자동 배포에 사용할 경우, 전용 서비스 계정 생성 후 Role/ClusterRole로 제한
• Helm 릴리스 시 --service-account 옵션을 사용하여 명시적인 권한 제어 가능

helm install my-app ./my-chart --service-account deployer-sa