Kubernetes

Kustomize 소개

Kustomize 소개와 사용 가이드입니다. base/overlay 구조, kustomization.yaml, patches, images, configMapGenerator, kubectl apply -k 흐름을 정리했습니다.

devmes

• 조회 216

Kustomize는 Kubernetes manifest를 템플릿 언어 없이 조합하고 환경별로 변형하는 도구입니다. 같은 Deployment YAML을 dev, stage, prod 환경에서 재사용하되 replica 수, image tag, label, ConfigMap, patch만 다르게 적용할 때 유용합니다.

Kustomize는 Kubernetes 1.14부터 kubectl에 통합되어 kubectl kustomize, kubectl apply -k 형태로 사용할 수 있습니다. 별도 바이너리를 쓰는 방식도 가능하지만, 먼저 kubectl 내장 기능으로 흐름을 이해하는 편이 좋습니다.

기본 디렉터리 구조

app/
 base/
 deployment.yaml
 service.yaml
 kustomization.yaml
 overlays/
 dev/
 kustomization.yaml
 patch-replicas.yaml
 prod/
 kustomization.yaml
 patch-replicas.yaml

base에는 공통 리소스를 두고, overlays에는 환경별 차이를 둡니다. 이렇게 나누면 같은 앱을 여러 환경에 배포하면서 복붙을 줄일 수 있습니다.

base kustomization.yaml

resources:
 - deployment.yaml
 - service.yaml

commonLabels:
 app.kubernetes.io/name: sample-web

overlay kustomization.yaml

resources:
 -../../base

namePrefix: dev-

images:
 - name: nginx
 newTag: "1.27"

patches:
 - path: patch-replicas.yaml
 target:
 kind: Deployment
 name: web

patch 예시

apiVersion: apps/v1
kind: Deployment
metadata:
 name: web
spec:
 replicas: 2

patch 대상의 name은 Kustomize 변환 전 기준 이름을 기준으로 잡는 경우가 많습니다. patch가 적용되지 않으면 kubectl kustomize 출력 YAML을 먼저 확인합니다.

빌드와 적용

kubectl kustomize overlays/dev
kubectl diff -k overlays/dev
kubectl apply -k overlays/dev
kubectl get deployment,svc

운영 반영 전에는 kubectl diff -k로 실제 변경될 리소스를 확인합니다. 특히 selector, Service port, PVC 같은 변경은 영향이 크므로 주의합니다.

ConfigMap 생성

configMapGenerator:
 - name: app-config
 literals:
 - APP_MODE=dev
 - LOG_LEVEL=debug

ConfigMap은 설정값에 적합합니다. password, token, private key 같은 민감정보는 Kustomize 예제에 직접 넣지 말고 별도 secret 관리 체계를 사용합니다.

이미지 태그 변경

images:
 - name: registry.example.com/app/web
 newName: registry.example.com/app/web
 newTag: "2026.06.23"

환경별 image tag를 overlay에서 관리하면 base manifest를 건드리지 않고 배포 버전을 바꿀 수 있습니다. 운영에서는 tag뿐 아니라 digest pinning도 고려합니다.

Kustomize가 맞는 경우

  • YAML 구조를 유지하면서 환경별 작은 차이만 관리하고 싶을 때
  • Helm chart까지는 과하고, Kubernetes native manifest 중심으로 관리하고 싶을 때
  • GitOps 도구가 kustomization.yaml을 직접 읽는 구조일 때

주의할 점

  • patch가 많아지면 최종 YAML을 읽기 어려워집니다. 복잡도가 커지면 구조를 다시 나눕니다.
  • Secret generator에 민감값을 직접 커밋하지 않습니다.
  • base가 환경 의존 값을 포함하면 overlay 분리 효과가 줄어듭니다.
  • kubectl kustomize 버전과 standalone kustomize 버전 차이로 출력이 달라질 수 있으니 CI에서 버전을 고정합니다.

공식 문서

BGM EVER