Kubernetes에서 Kustomize를 쓰는 이유

Kubernetes를 운영하다 보면 dev / cbt / prod처럼 환경이 여러 개로 나뉘고, 리소스 형태는 같은데 값만 다른 상황이 흔하다.
예를 들면 Deployment/Service/Ingress는 동일한 구조를 유지하면서도 환경마다 image tag, replicas, resources, Ingress host, annotation 같은 값은 달라진다.

이때 선택지는 보통 두 가지다.

• 환경별로 YAML을 복사해서(dev.yaml, prod.yaml...) 각각 관리한다.
• 공통은 하나로 두고, 환경별 차이만 관리한다. (Kustomize 방식)

이 글에서는 두 번째 방식인 Kustomize를 왜 쓰는지, 특히 base는 동일하고 환경별로 다른 내용만 있을 때 어떤 이득이 있는지 정리한다.

 

문제: 환경별 YAML 복붙은 시간이 지날수록 깨진다

처음엔 간단하다. dev/prod YAML을 복사해서 값만 조금 바꾸면 된다.

하지만 시간이 지나면 이런 문제가 쌓인다.

• dev에서만 수정하고 prod 반영을 놓친다.
• Service selector / port / annotation이 환경마다 미세하게 달라져서 장애가 난다.
• "원래 어떤 게 공통이었지?"가 불명확해진다.
• 파일이 3배로 늘어나면서 리뷰 포인트도 3배가 된다.

결국 환경별 YAML은 드리프트(drift)가 발생하기 쉬운 구조다.
여기서 drift는 “Git에 있는 선언 상태”와 “클러스터에 적용된 실제 상태”, 그리고 “환경 간 상태”가 시간이 지나면서 어긋나는 현상을 말한다.

 

Kustomize의 핵심 개념: base + overlay

Kustomize는 기본 YAML을 “템플릿”으로 바꾸지 않는다.
대신 공통은 base, 환경별 차이는 overlay에서 패치(patch)로 덧대서 최종 결과물을 만든다.

• base: 공통 리소스 정의 (Deployment/Service/Ingress의 기본 형태)
• overlay: dev/cbt/prod에서 다른 값만 patch로 관리

즉, overlay는 “환경별 차이만 얹는 레이어”다.

디렉토리 구조 예시

k8s/
|-- base/
|---- deployment.yaml
|---- service.yaml
|---- ingress.yaml
|---- kustomization.yaml
|-- overlays/
|---- dev/
|------ kustomization.yaml
|------ patch-deployment.yaml
|------ patch-ingress.yaml
|---- cbt/
|------ kustomization.yaml
|------ patch-deployment.yaml
|------ patch-ingress.yaml
|---- prod/
|------ kustomization.yaml
|------ patch-deployment.yaml
|------ patch-ingress.yaml

• base/는 “공통 구조”
• overlays/<env>/는 “환경별 값 변경”

 

Kustomize를 쓰는 이유 (base 동일 + env 차이 존재)

1. 복붙 YAML 3세트를 없애고 “차이만” 관리한다

공통은 base에서 한 번만 정의하고,
환경별로 다른 값만 overlays에 남긴다.

환경이 늘어도 “공통 1개 + 차이 N개” 구조가 되기 때문에 관리 난이도가 올라가지 않는다.

2. 환경 간 불일치(드리프트/누락)를 줄인다

복붙 구조는 공통이어야 할 설정이 환경마다 달라지기 쉽다.

base + overlay로 운영하면 공통 영역은 항상 동일하게 유지되고,
차이는 의도적으로 overlay에만 존재한다.

이 방식은 특히 아래 같은 사고를 줄여준다.

• Service selector와 Deployment label 불일치
• port/targetPort 불일치
• ingress annotation이 한 환경에만 적용되어 동작이 다름

3. 이미지/설정 변경 반영이 더 안정적이다

Kustomize는 이미지 태그만 교체하거나, ConfigMap/Secret을 생성하는 흐름도 잘 지원한다.

• images:로 환경별 태그 교체
• configMapGenerator/secretGenerator로 내용 변경 시 롤링 트리거(해시 기반) 유도

“배포했는데 설정 변경이 Pod에 안 먹었다” 같은 상황을 줄이는 데 도움이 된다.

 

결론

Kustomize는 “필수”는 아니다. Deployment만 배포해도 서비스는 돌아간다.
하지만 base는 같고 환경별로 다른 값이 늘어나는 순간, 복붙 YAML은 유지보수 비용과 장애 위험을 빠르게 키운다.

정리하면 Kustomize를 쓰는 이유는 간단하다.

• 공통은 한 번만 유지
• 환경별 차이는 명확하게 분리
• 배포/리뷰/운영 실수를 줄이기 위해

dev/cbt/prod처럼 환경이 3개 이상이라면 환경별 차이를 안전하게 관리하기 위한 선택으로 

Kustomize는 “나중에 필요해질 것”이 아니라 지금도 충분히 투자 가치가 있는 운영 도구가 될 가능성이 높다.