Certified Kubernetes Administrator (CKA) #21 Helm과 Kustomize: 매니페스트 관리

#20 Networking 3에서 CoreDNS와 NetworkPolicy까지 다루며 네트워킹 도메인을 마무리했습니다. 이번 글은 트러블슈팅으로 넘어가기 전에, 한 묶음의 매니페스트를 반복 가능하고 환경별로 변형 가능하게 관리하는 두 도구를 정리하겠습니다. Helm과 Kustomize입니다.

CKA에서 이 두 도구의 비중은 크지 않습니다. 그러나 둘 다 실무에서 매니페스트를 다루는 표준 도구이고, 시험에서도 “주어진 chart를 install하라”, “kustomization으로 image tag를 바꿔라” 같은 짧은 작업으로 나올 수 있습니다. 핵심 명령과 디렉터리 구조만 손에 익히면 충분합니다.

왜 매니페스트 관리 도구가 필요한가 #

지금까지는 매니페스트를 손으로 쓰고 kubectl apply -f로 적용했습니다. 그러나 실무에서는 같은 앱을 dev,staging,prod 환경에 조금씩 다르게 배포해야 합니다. replica 수, image tag, 리소스 한도, 환경 변수가 환경마다 다릅니다. 이때 환경 수만큼 매니페스트를 복사하면 중복이 쌓이고 변경 누락이 생깁니다.

이 문제를 푸는 접근이 둘로 갈립니다.

• Helm: 매니페스트를 템플릿으로 만들고, 값(values)을 주입해 렌더링합니다. chart 단위로 패키징하고 버전을 관리하며 install,upgrade,rollback을 명령으로 다룹니다.
• Kustomize: 원본 매니페스트(base)는 그대로 두고, 환경별 차이만 오버레이로 덧입혀 합성합니다. 템플릿 문법 없이 순수 YAML로 작동하며 kubectl에 내장되어 있습니다.

두 도구의 철학은 다르지만 목적은 같습니다. 하나의 정의에서 여러 환경의 매니페스트를 만들어 내는 것입니다.

Helm #

Helm은 쿠버네티스의 패키지 매니저입니다. apt나 brew가 패키지를 다루듯, Helm은 chart라는 단위로 쿠버네티스 앱을 설치하고 업그레이드합니다. chart는 템플릿화된 매니페스트와 기본값(values.yaml)을 담은 디렉터리입니다.

chart 저장소 등록 #

공개 chart를 쓰려면 먼저 저장소를 등록하고 인덱스를 갱신합니다.

# 저장소 추가
helm repo add bitnami https://charts.bitnami.com/bitnami

# 인덱스 갱신 (등록된 모든 repo의 최신 chart 목록)
helm repo update

# 등록된 저장소 확인
helm repo list

# chart 검색
helm search repo nginx

chart 설치 #

helm install은 chart를 클러스터에 설치하고 그 결과를 release라는 이름으로 추적합니다. 같은 chart를 이름만 달리해 여러 번 설치할 수 있습니다.

# <release 이름> <chart> 순서
helm install my-nginx bitnami/nginx

# 설치된 release 목록
helm list

# 특정 네임스페이스에 설치
helm install my-nginx bitnami/nginx -n web --create-namespace

값 주입: –set과 -f #

chart의 기본값을 그대로 쓰지 않고 일부를 바꾸려면 값을 주입합니다. 한두 개는 --set으로, 여러 개는 값 파일(-f)로 넘깁니다.

# 인라인으로 한두 값 덮어쓰기
helm install my-nginx bitnami/nginx --set replicaCount=3

# 값 파일로 한꺼번에 덮어쓰기
helm install my-nginx bitnami/nginx -f my-values.yaml

# 두 방법은 함께 쓸 수 있고, --set이 우선순위가 높음
helm install my-nginx bitnami/nginx -f my-values.yaml --set image.tag=1.25

my-values.yaml은 chart의 values.yaml 구조 중 바꿀 부분만 적으면 됩니다.

replicaCount: 3
image:
  tag: "1.25"
service:
  type: NodePort

설치 없이 렌더링만: helm template #

chart가 실제로 어떤 매니페스트를 만들어 내는지 확인하고 싶을 때 helm template을 씁니다. 클러스터에 적용하지 않고 렌더링 결과만 표준 출력으로 내보냅니다. 시험에서 “이 chart가 만드는 Deployment의 replica 수를 확인하라” 같은 작업에 유용합니다.

# 렌더링 결과를 화면으로
helm template my-nginx bitnami/nginx --set replicaCount=3

# 파일로 저장해 검토
helm template my-nginx bitnami/nginx > rendered.yaml

업그레이드와 롤백 #

설치한 release의 값이나 chart 버전을 바꿀 때 helm upgrade를 씁니다. 각 변경은 revision 번호로 기록되며, 문제가 생기면 이전 revision으로 되돌립니다.

# 값을 바꿔 업그레이드 (revision 증가)
helm upgrade my-nginx bitnami/nginx --set replicaCount=5

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

# revision이력 확인
helm history my-nginx

# 직전 revision으로 롤백
helm rollback my-nginx

# 특정 revision으로 롤백
helm rollback my-nginx 2

상태 확인과 삭제 #

# release 상세 상태
helm status my-nginx

# release가 적용한 실제 매니페스트
helm get manifest my-nginx

# release 삭제 (관련 리소스 모두 제거)
helm uninstall my-nginx

helm uninstall은 그 release가 만든 모든 쿠버네티스 리소스를 한 번에 제거합니다. kubectl delete로 일일이 지우는 것보다 깔끔합니다.

Kustomize #

Kustomize는 템플릿 문법 없이 순수 YAML 합성으로 매니페스트를 변형합니다. 원본은 base에 두고, 환경별 차이를 overlay에 두어 둘을 겹칩니다. Kustomize는 kubectl에 내장되어 있어 별도 설치 없이 kubectl apply -k로 바로 적용합니다.

kustomization.yaml #

모든 Kustomize 디렉터리에는 kustomization.yaml이 있습니다. 이 파일이 어떤 매니페스트(resources)를 묶고 어떤 변형을 가할지 선언합니다.

# base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml

base/deployment.yaml과 base/service.yaml은 평범한 매니페스트입니다. 손으로 쓰던 그대로이며 특별한 문법이 없습니다.

base와 overlays 구조 #

환경별 차이를 overlay 디렉터리로 분리합니다. overlay의 kustomization.yaml은 base를 참조하고, 그 위에 변형만 더합니다.

myapp/
├── base/
│   ├── kustomization.yaml
│   ├── deployment.yaml
│   └── service.yaml
└── overlays/
    ├── dev/
    │   └── kustomization.yaml
    └── prod/
        └── kustomization.yaml

prod overlay는 base를 가져와 prod에 필요한 변경만 선언합니다.

# overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
namePrefix: prod-
commonLabels:
  env: prod
images:
  - name: nginx
    newTag: "1.25.3"
replicas:
  - name: web
    count: 5

이 overlay는 base의 Deployment 이름에 prod- 접두사를 붙이고, 모든 리소스에 env: prod 라벨을 더하며, image tag를 1.25.3으로, replica를 5로 바꿉니다. base는 전혀 손대지 않습니다.

patchesStrategicMerge #

images나 replicas 같은 내장 변형으로 표현하기 어려운 변경은 patch로 처리합니다. patchesStrategicMerge는 바꿀 필드만 적은 부분 매니페스트를 base에 병합합니다.

# overlays/prod/kustomization.yaml 일부
patchesStrategicMerge:
  - resources-patch.yaml

# overlays/prod/resources-patch.yaml (바꿀 필드만)
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  template:
    spec:
      containers:
        - name: web
          resources:
            requests: { cpu: "250m", memory: "256Mi" }
            limits: { cpu: "500m", memory: "512Mi" }

patch에는 식별에 필요한 키(kind,name,container name)와 바꿀 필드만 적으면 됩니다. Kustomize가 base와 같은 위치를 찾아 병합합니다.

configMapGenerator #

ConfigMap을 직접 작성하지 않고 파일이나 리터럴에서 생성할 수 있습니다. configMapGenerator로 만든 ConfigMap은 내용 해시가 이름에 붙어, 내용이 바뀌면 이름도 바뀝니다. 이를 참조하는 Pod가 자동으로 롤링 업데이트되는 장점이 있습니다.

configMapGenerator:
  - name: app-config
    literals:
      - LOG_LEVEL=info
      - TIMEOUT=30
  - name: app-files
    files:
      - config.properties

적용과 렌더링: kubectl -k #

Kustomize는 kubectl에 내장되어 있어 별도 바이너리 없이 쓸 수 있습니다.

# 합성 결과를 화면으로 확인 (적용 안 함)
kubectl kustomize overlays/prod

# 합성 결과를 바로 적용
kubectl apply -k overlays/prod

# 합성 결과를 삭제
kubectl delete -k overlays/prod

kubectl kustomize로 먼저 결과를 확인한 뒤 kubectl apply -k로 적용하는 흐름이 안전합니다. alias를 쓴다면 k apply -k overlays/prod 그리고 k kustomize overlays/prod처럼 짧게 칠 수 있습니다.

Helm과 Kustomize 비교 #

두 도구는 같은 문제를 다른 방식으로 풉니다.

실무에서는 둘을 함께 쓰기도 합니다. 외부 앱은 Helm chart로 설치하고, 자체 앱은 Kustomize로 환경별 변형을 관리하는 식입니다. 정답은 없고 팀의 표준을 따르면 됩니다.

CKA 시험 포인트 #

• Helm과 Kustomize는 CKA 비중이 작습니다. 그러나 짧은 작업으로 나올 수 있으므로 핵심 명령은 외워 두는 것이 안전합니다.
• Helm은 helm install, helm upgrade --install, helm list, helm rollback, 그리고 값을 확인하는 helm template을 손에 익히겠습니다. 설치 전에 무엇이 만들어지는지 helm template으로 검증하는 습관이 오답을 줄입니다.
• Kustomize는 kubectl apply -k와 kubectl kustomize만 확실히 기억하면 됩니다. 적용 전에 kubectl kustomize로 합성 결과를 먼저 확인하겠습니다.
• “image tag를 바꿔라” 같은 작업은 Kustomize라면 overlay의 images.newTag를, Helm이라면 --set image.tag를 떠올리면 빠릅니다.
• 시험 환경에 Helm 바이너리가 있는지, 어떤 chart가 미리 등록되어 있는지는 문제가 알려 줍니다. 지시문을 먼저 정확히 읽겠습니다.

매니페스트 관리 도구를 직접 손으로 익히려면 쿠버네티스 실전 연습 2의 시나리오로 base/overlay를 만들어 보고 chart를 install,upgrade,rollback해 보는 것이 가장 빠릅니다.

정리 #

이번 글에서 잡은 것:

• 매니페스트 관리 도구는 하나의 정의에서 여러 환경의 매니페스트를 만들어 낸다. Helm은 템플릿 방식, Kustomize는 오버레이 방식으로 각각 접근합니다
• Helm. repo add/repo update로 저장소 등록, install/upgrade/rollback으로 release 관리, --set과 -f로 값 주입, helm template으로 적용 전 렌더링 확인, helm list/history/uninstall
• Kustomize. kustomization.yaml로 base와 overlays 구성, patchesStrategicMerge로 부분 병합, configMapGenerator로 ConfigMap 생성, kubectl apply -k로 적용, kubectl kustomize로 합성 확인
• 둘의 차이. 템플릿 대 오버레이, 별도 설치 대 kubectl 내장, release 추적 유무. 외부 앱은 Helm, 자체 앱 변형은 Kustomize가 흔한 선택
• 시험 포인트. 비중은 작지만 핵심 명령은 외워 두기. 적용 전 helm template,kubectl kustomize로 검증

다음: Troubleshooting 1 #

매니페스트 관리까지 정리하며 도구를 다루는 도메인을 마쳤습니다. 이제 CKA에서 가장 비중이 큰 트러블슈팅(30%)으로 들어갑니다.

#22 Troubleshooting 1: Pod와 앱에서는 가장 자주 마주치는 앱 레벨 장애를 다루겠습니다. Pending(스케줄 불가), CrashLoopBackOff(컨테이너 반복 종료), ImagePullBackOff(이미지 가져오기 실패), OOMKilled(메모리 한도 초과)의 증상을 구별하고, kubectl describe,kubectl logs,이벤트로 원인을 추적해 고치는 절차를 손에 익히겠습니다.