Kubernetes를 처음 공부할 때는 Deployment, Service, ConfigMap, Secret, PVC 등의 YAML 파일을 하나씩 작성해서 애플리케이션을 배포합니다.
처음에는 크게 어렵지 않습니다.
하지만 실제 운영 환경에서 애플리케이션이 많아지면 상황이 달라집니다.
예를 들어 하나의 서비스에 다음과 같은 Kubernetes 리소스가 필요하다고 가정해 보겠습니다.
Deployment
Service
ConfigMap
Secret
Ingress
PVC
ServiceAccount
Role
RoleBinding
여기에 개발, 테스트, 운영 환경까지 나누면 YAML 파일의 개수가 급격하게 증가합니다.
k8s/
├── deployment.yaml
├── service.yaml
├── configmap.yaml
├── secret.yaml
├── ingress.yaml
├── pvc.yaml
└── ...
이러한 Kubernetes 리소스를 하나의 패키지로 관리할 수 있도록 도와주는 도구가 Helm입니다.
Helm은 Kubernetes의 패키지 관리자라고 생각하면 이해하기 쉽습니다.
이번 글에서는 Helm이 무엇인지부터 Chart, Repository, Values, Template, Release, Upgrade, Rollback까지 시스템 엔지니어가 실제 Kubernetes 운영에서 알아야 할 내용을 단계적으로 알아보겠습니다.
Helm은 Kubernetes 애플리케이션을 쉽게 설치하고 관리하기 위한 패키지 관리 도구입니다.
Linux에서 패키지 관리자를 사용하는 것과 비슷한 개념입니다.
예를 들어 Linux에서는 패키지를 다음과 같이 설치합니다.
dnf install nginx
Ubuntu에서는 다음과 같이 사용할 수 있습니다.
apt install nginx
Helm에서는 Kubernetes 애플리케이션을 Chart라는 패키지로 관리합니다.
Helm
│
└── Chart
├── Deployment
├── Service
├── ConfigMap
├── Secret
├── Ingress
└── PVC
즉, Helm은 여러 Kubernetes YAML 리소스를 하나의 관리 가능한 패키지로 묶어주는 역할을 합니다.
Kubernetes YAML을 직접 관리하는 방식도 충분히 사용할 수 있습니다.
하지만 시스템 규모가 커지면 다음과 같은 문제가 발생합니다.
서비스 하나만 운영해도 여러 개의 YAML이 필요할 수 있습니다.
deployment.yaml
service.yaml
configmap.yaml
secret.yaml
ingress.yaml
pvc.yaml
서비스가 10개라면 관리해야 할 파일이 더욱 많아집니다.
예를 들어 개발 환경과 운영 환경의 설정이 다를 수 있습니다.
개발
replicas: 1
image: myapp:dev
운영
replicas: 3
image: myapp:1.0
YAML 파일을 환경별로 복사해서 관리하면 변경 사항을 추적하기 어려워집니다.
예를 들어 같은 FastAPI 애플리케이션을 다음과 같이 설치할 수 있습니다.
개발 환경
tax-api-dev
테스트 환경
tax-api-test
운영 환경
tax-api-prod
Helm을 사용하면 하나의 Chart를 기반으로 서로 다른 설정을 적용하여 여러 환경에 설치할 수 있습니다.
Helm을 공부할 때 가장 먼저 알아야 하는 개념은 다음과 같습니다.
Chart
Repository
Release
Values
Template
각각의 의미는 다음과 같습니다.
| 개념 | 설명 |
|---|---|
| Chart | Kubernetes 애플리케이션 패키지 |
| Repository | Chart를 저장하고 배포하는 저장소 |
| Release | Chart를 실제 Kubernetes에 설치한 인스턴스 |
| Values | 애플리케이션 설정값 |
| Template | Kubernetes YAML을 동적으로 생성하는 템플릿 |
이 다섯 가지를 이해하면 Helm의 기본 구조를 대부분 이해한 것입니다.
Helm Chart는 Kubernetes 애플리케이션을 구성하는 파일들의 묶음입니다.
예를 들어 다음과 같은 구조를 가질 수 있습니다.
myapp/
├── Chart.yaml
├── values.yaml
├── templates/
│ ├── deployment.yaml
│ ├── service.yaml
│ ├── ingress.yaml
│ └── configmap.yaml
└── charts/
각 파일의 역할이 중요합니다.
Chart의 기본 정보를 저장합니다.
apiVersion: v2
name: myapp
description: My Kubernetes Application
type: application
version: 0.1.0
appVersion: "1.0.0"
여기에는 Chart 이름과 버전 등의 정보가 들어갑니다.
Helm에서 매우 중요한 파일입니다.
애플리케이션의 기본 설정값을 저장합니다.
예를 들어 다음과 같이 작성할 수 있습니다.
replicaCount: 2
image:
repository: nginx
tag: "1.27"
service:
type: ClusterIP
port: 80
Template에서는 이 값을 가져와 Kubernetes YAML을 생성합니다.
예를 들어 다음과 같이 사용할 수 있습니다.
replicas: {{ .Values.replicaCount }}
그러면 Helm이 다음과 같은 Kubernetes YAML을 생성합니다.
replicas: 2
즉,
values.yaml
│
▼
Template
│
▼
Kubernetes YAML
이라는 구조입니다.
Template은 Kubernetes YAML을 동적으로 생성하기 위한 파일입니다.
일반적인 Kubernetes YAML은 다음과 같습니다.
apiVersion: apps/v1
kind: Deployment
metadata:
name: myapp
spec:
replicas: 2
Helm에서는 다음처럼 작성할 수 있습니다.
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "myapp.fullname" . }}
spec:
replicas: {{ .Values.replicaCount }}
여기서
{{ ... }}
형태의 문법이 Helm Template 문법입니다.
이를 이용하면 하나의 YAML을 다양한 환경에서 재사용할 수 있습니다.
Helm이 설치되어 있다면 다음 명령으로 새로운 Chart를 생성할 수 있습니다.
helm create myapp
그러면 기본적인 Chart 구조가 생성됩니다.
myapp/
├── Chart.yaml
├── values.yaml
├── charts/
├── templates/
│ ├── deployment.yaml
│ ├── service.yaml
│ ├── ingress.yaml
│ ├── serviceaccount.yaml
│ ├── _helpers.tpl
│ └── tests/
└── .helmignore
처음에는 파일이 많아 보이지만 핵심은 다음 세 가지입니다.
Chart.yaml
values.yaml
templates/
Chart를 실제 Kubernetes에 설치하기 전에 문법과 구조를 확인하는 것이 중요합니다.
다음 명령을 사용할 수 있습니다.
helm lint myapp
문제가 없다면 Chart에 문제가 없는지 확인할 수 있습니다.
Template이 실제로 어떤 YAML을 생성하는지 확인하려면 다음 명령을 사용할 수 있습니다.
helm template myapp ./myapp
이 명령은 Kubernetes에 실제로 설치하지 않고 생성될 YAML을 출력합니다.
운영 환경에서는 매우 유용한 명령입니다.
Chart를 Kubernetes에 설치하는 가장 기본적인 명령은 다음과 같습니다.
helm install myapp ./myapp
여기서 myapp은 Release 이름입니다.
Release Name
│
▼
myapp
│
▼
Chart
│
▼
Kubernetes Resources
설치가 완료되면 다음 명령으로 확인할 수 있습니다.
helm list
또는 특정 Namespace를 지정할 수 있습니다.
helm list -n production
Release는 Helm Chart를 Kubernetes에 실제로 설치한 결과입니다.
같은 Chart라도 여러 개의 Release를 만들 수 있습니다.
예를 들어 하나의 Chart가 있다고 가정합니다.
myapp Chart
이를 다음과 같이 설치할 수 있습니다.
myapp-dev
myapp-test
myapp-prod
즉,
myapp Chart
/ | \
/ | \
▼ ▼ ▼
dev Release test prod
같은 애플리케이션을 서로 다른 설정으로 여러 번 운영할 수 있습니다.
Helm은 Namespace와 함께 사용하는 경우가 많습니다.
예를 들어 운영 환경을 다음과 같이 구성할 수 있습니다.
development
└── myapp-dev
staging
└── myapp-staging
production
└── myapp-prod
Namespace를 먼저 생성할 수 있습니다.
kubectl create namespace production
그리고 Helm을 이용하여 설치합니다.
helm install myapp-prod ./myapp \
-n production
운영 환경을 분리하는 데 매우 유용합니다.
Helm의 가장 큰 장점 중 하나가 환경별 설정을 쉽게 관리할 수 있다는 것입니다.
예를 들어 기본 values.yaml은 다음과 같이 작성합니다.
replicaCount: 2
image:
repository: myapp
tag: "1.0"
service:
type: ClusterIP
port: 8000
개발 환경에서는 다음과 같은 파일을 사용할 수 있습니다.
values-dev.yaml
replicaCount: 1
image:
tag: "dev"
운영 환경에서는 다음과 같이 사용할 수 있습니다.
values-prod.yaml
replicaCount: 3
image:
tag: "1.0"
설치할 때 다음과 같이 지정합니다.
helm install myapp-dev ./myapp \
-f values-dev.yaml
운영 환경:
helm install myapp-prod ./myapp \
-f values-prod.yaml
이렇게 하면 하나의 Chart를 개발과 운영 환경에서 재사용할 수 있습니다.
애플리케이션 버전을 변경하거나 설정을 변경할 때는 helm upgrade를 사용할 수 있습니다.
예를 들어 Image 버전을 변경한다고 가정하겠습니다.
image:
repository: myapp
tag: "1.1"
다음 명령으로 변경할 수 있습니다.
helm upgrade myapp-prod ./myapp \
-f values-prod.yaml
Kubernetes 리소스가 변경되고 새로운 설정에 따라 애플리케이션이 업데이트됩니다.
운영 환경에서 배포한 버전에 문제가 발생할 수 있습니다.
예를 들어 다음과 같은 상황입니다.
Version 1.0
│
▼
정상 운영
│
▼
Version 1.1 배포
│
▼
장애 발생
이때 Helm의 Rollback 기능을 사용할 수 있습니다.
먼저 Release의 Revision을 확인합니다.
helm history myapp-prod
예를 들어 다음과 같이 나올 수 있습니다.
REVISION STATUS
1 superseded
2 deployed
이전 버전으로 되돌립니다.
helm rollback myapp-prod 1
그러면 이전 Revision의 상태로 돌아갈 수 있습니다.
이 기능은 운영 환경에서 매우 중요합니다.
배포 이력을 확인하려면 다음 명령을 사용합니다.
helm history myapp-prod
이를 통해 다음과 같은 정보를 확인할 수 있습니다.
Revision
Updated
Status
Chart
Description
따라서 Helm은 단순히 YAML 파일을 쉽게 생성하는 도구가 아니라 애플리케이션 배포 이력을 관리하는 도구로도 사용할 수 있습니다.
애플리케이션을 제거하려면 다음 명령을 사용할 수 있습니다.
helm uninstall myapp-prod
그러면 해당 Release가 관리하는 Kubernetes 리소스가 제거됩니다.
단, PersistentVolume이나 PVC와 같은 저장장치는 리소스 종류와 설정에 따라 동작이 다를 수 있으므로 운영 환경에서는 삭제 전에 반드시 확인해야 합니다.
특히 데이터베이스를 Helm으로 관리하는 경우 무심코 helm uninstall을 실행하는 것은 위험할 수 있습니다.
Helm Chart를 직접 만들 수도 있지만 다른 사람이 만들어 놓은 Chart를 사용할 수도 있습니다.
이를 위해 Helm Repository를 사용합니다.
예를 들어 Repository를 추가하는 형태는 다음과 같습니다.
helm repo add <repository-name> <repository-url>
Repository 정보를 업데이트합니다.
helm repo update
Chart를 검색합니다.
helm search repo <keyword>
이러한 방식으로 이미 만들어진 Kubernetes 애플리케이션 패키지를 찾아 사용할 수 있습니다.
실무에서는 공개 Chart를 그대로 사용하기보다는 Chart의 기본 설정과 Template을 반드시 검토한 후 사용하는 습관이 중요합니다.
앞서 배운 ConfigMap과 Secret도 Helm Chart에서 관리할 수 있습니다.
예를 들어 Template에 ConfigMap을 만들 수 있습니다.
apiVersion: v1
kind: ConfigMap
metadata:
name: {{ include "myapp.fullname" . }}-config
data:
LOG_LEVEL: {{ .Values.logLevel | quote }}
그리고 values.yaml에서는 다음과 같이 관리합니다.
logLevel: INFO
이렇게 하면 환경에 따라 설정을 변경할 수 있습니다.
values-dev.yaml
logLevel: DEBUG
values-prod.yaml
logLevel: INFO
하지만 Secret의 실제 비밀번호나 API Key를 일반적인 values 파일에 평문으로 저장하는 것은 피해야 합니다.
Git 저장소에 Chart를 저장하는 경우 특히 주의해야 합니다.
Helm은 Git과 함께 사용하면 더욱 강력합니다.
예를 들어 다음과 같은 구조를 만들 수 있습니다.
Git Repository
│
├── Chart.yaml
├── values.yaml
├── values-dev.yaml
├── values-prod.yaml
└── templates/
├── deployment.yaml
├── service.yaml
├── ingress.yaml
└── configmap.yaml
개발자가 변경 사항을 Git에 Commit합니다.
Git
│
▼
Helm Chart
│
▼
CI/CD
│
▼
Kubernetes
이 구조는 이후 학습할 DevOps와 GitOps의 기반이 됩니다.
Helm은 CI/CD 환경에서도 많이 사용됩니다.
예를 들어 GitHub Actions에서 다음과 같은 흐름을 만들 수 있습니다.
개발자
│
▼
Git Push
│
▼
GitHub Actions
│
├── Docker Image Build
│
├── Image Push
│
└── Helm Upgrade
│
▼
Kubernetes
예를 들어 다음과 같은 배포 명령을 실행할 수 있습니다.
helm upgrade --install myapp ./chart \
-n production \
-f values-prod.yaml
--install을 사용하면 Release가 없을 경우 설치하고, 이미 존재하면 Upgrade하는 방식으로 활용할 수 있습니다.
Helm을 실무에서 사용하려면 기본적인 Template 문법을 알아야 합니다.
값을 출력합니다.
{{ .Values.image.repository }}
조건문을 사용할 수 있습니다.
{{- if .Values.ingress.enabled }}
반복문도 사용할 수 있습니다.
{{- range .Values.environments }}
기본값을 지정할 수도 있습니다.
{{ .Values.service.port | default 80 }}
문자열 처리나 다양한 함수도 사용할 수 있습니다.
처음부터 모든 Helm Template 문법을 외울 필요는 없습니다.
중요한 것은 values.yaml의 값을 Template에 전달하는 구조를 이해하는 것입니다.
Helm 배포가 실패했다고 해서 바로 Kubernetes 전체의 문제라고 판단해서는 안 됩니다.
먼저 Template이 정상적으로 생성되는지 확인합니다.
helm template myapp ./myapp
또는 다음과 같이 설치 과정에서 생성되는 내용을 확인할 수 있습니다.
helm install myapp ./myapp \
--dry-run \
--debug
설치 이후에는 Helm 상태를 확인합니다.
helm status myapp
Kubernetes 리소스도 확인합니다.
kubectl get pods
kubectl get service
kubectl get ingress
Pod에 문제가 있다면 다음과 같이 확인합니다.
kubectl describe pod <pod-name>
로그를 확인합니다.
kubectl logs <pod-name>
즉 Helm 문제와 Kubernetes 리소스 문제를 분리해서 분석해야 합니다.
실무에서 Helm을 사용할 때는 다음 구조를 이해하면 좋습니다.
Git Repository
│
▼
Helm Chart
│
┌─────────┴─────────┐
▼ ▼
values-dev.yaml values-prod.yaml
│ │
▼ ▼
Development Production
│ │
▼ ▼
Kubernetes Kubernetes
그리고 CI/CD를 연결하면 다음과 같은 구조가 됩니다.
Developer
│
▼
Git Push
│
▼
CI/CD Pipeline
│
▼
Docker Image
│
▼
Container Registry
│
▼
Helm
│
▼
Kubernetes
이 구조는 이후 Kubernetes 운영과 DevOps를 연결하는 중요한 기반이 됩니다.
Helm을 사용한다고 해서 모든 문제가 해결되는 것은 아닙니다.
가장 중요한 것은 Chart의 복잡성을 관리하는 것입니다.
너무 많은 조건문과 Template을 하나의 Chart에 넣으면 오히려 유지보수가 어려워질 수 있습니다.
또한 다음 사항을 주의해야 합니다.
Chart 버전 관리
Application 버전 관리
환경별 Values 관리
Secret 관리
Rollback 정책
Storage 삭제 정책
RBAC 권한
특히 운영 환경에서는 다음과 같은 실수를 피해야 합니다.
무조건 helm uninstall 실행
데이터베이스가 포함된 환경이라면 PVC와 실제 데이터가 어떻게 관리되는지 먼저 확인해야 합니다.
또한 Secret을 Git Repository에 평문으로 저장하지 않는 것이 중요합니다.
Helm을 단순히 "Kubernetes YAML을 쉽게 설치하는 명령어"라고 생각하면 안 됩니다.
시스템 엔지니어 관점에서는 다음과 같이 이해하는 것이 좋습니다.
Kubernetes
│
├── Deployment
├── Service
├── ConfigMap
├── Secret
├── Ingress
└── PVC
│
▼
Helm
│
┌───────┼────────┐
▼ ▼ ▼
Chart Values Release
Helm은 이러한 Kubernetes 리소스를 패키징하고, 설정하고, 배포하고, 버전을 관리하고, 필요하면 이전 버전으로 되돌리는 역할을 합니다.
Kubernetes를 처음 배울 때는 각각의 YAML 파일을 직접 작성하는 것이 매우 중요합니다.
Deployment가 무엇인지, Service가 무엇인지, ConfigMap과 Secret은 어떤 역할을 하는지, PVC가 어떻게 Storage와 연결되는지를 직접 경험해야 하기 때문입니다.
하지만 Kubernetes 환경이 커지면 YAML 파일을 개별적으로 관리하는 것만으로는 한계가 있습니다.
이때 Helm을 사용하면 다음과 같은 구조로 관리할 수 있습니다.
Helm Chart
│
┌─────────────┼─────────────┐
│ │ │
Deployment Service Ingress
│ │ │
├─────────────┼─────────────┤
│ │ │
ConfigMap Secret PVC
│
▼
Kubernetes
핵심 개념을 정리하면 다음과 같습니다.
Chart
→ Kubernetes 애플리케이션 패키지
values.yaml
→ 설정값 관리
Template
→ Kubernetes YAML 생성
Release
→ 실제 Kubernetes에 설치된 Chart
Repository
→ Chart 저장소
helm install
→ 애플리케이션 설치
helm upgrade
→ 애플리케이션 업데이트
helm history
→ 배포 이력 확인
helm rollback
→ 이전 버전 복구
helm uninstall
→ Release 제거
특히 지금까지 학습한 Deployment → Service → ConfigMap → Secret → PVC → Ingress를 Helm으로 하나의 Chart로 묶어보는 실습을 해보면 Kubernetes 관리 능력이 한 단계 올라갑니다..
:::