Kustomize - 총 정리

쿠버네티스 매니페스트를 운영하다 보면 가장 먼저 부딪히는 문제가 있습니다.

• dev/staging/prod 환경마다 replicas, image tag, namespace, config가 조금씩 다르다
• 그런데 매니페스트를 환경별로 폴더 3개 만들어서 그대로 복사해두면
  파일 수가 늘어날수록 “복붙 지옥 + config drift(환경별 설정 불일치)”가 반드시 온다

Kustomize는 이 문제를 해결하기 위해 만들어진 도구입니다.

• Base(공통) 매니페스트는 한 번만 작성
• Overlay(환경별) 에서는 “차이만” patch/transform으로 덮어쓴다
• 결과는 여전히 표준 YAML(템플릿 언어 없음)이라 읽기/검증이 쉽다
• kubectl에 내장되어 있어 바로 사용할 수 있다(다만 내장 버전이 최신이 아닐 수 있음)

---

1. Kustomize의 핵심 개념: Base와 Overlays

1) Base

모든 환경에서 공통으로 쓰는 리소스(또는 기본값)를 둡니다.

• 공통 Deployment/Service
• 기본 replicas=1 같은 “디폴트”
• 공통 labels/annotations/namespace 정책(경우에 따라 base에 두거나 overlay로)

2) Overlays

환경별로 다른 부분만 모아둡니다.

• dev: replicas=1, nameSuffix=-dev, namespace=dev, image tag=latest
• prod: replicas=5, namespace=prod, image tag=1.2.3
• 그리고 특정 환경에서만 필요한 리소스(예: prod에만 grafana)도 overlay에 추가 가능

---

2. kustomization.yaml: Kustomize가 바라보는 “엔트리 포인트”

Kustomize는 폴더를 적용할 때 해당 폴더의 kustomization.yaml을 찾습니다.

kustomization.yaml에는 크게 두 가지가 들어갑니다.

1. resources: Kustomize가 관리할 리소스 목록(파일/디렉터리)
2. 변환/패치: 공통 변환(transformers), patches, images 등

팁: apiVersion과 kind는 technically optional이지만, 미래 호환성을 위해 명시하는 습관이 좋습니다.

예시:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - nginx-depl.yaml
  - nginx-svc.yaml

---

3. 적용/삭제 워크플로우: build는 “렌더링”, apply는 “배포”

1) 렌더링(결과 YAML 보기)

kustomize build ./k8s
# 또는
kubectl kustomize ./k8s

2) 배포(apply)

kustomize build ./k8s | kubectl apply -f -
# 또는(권장, 간단)
kubectl apply -k ./k8s

3) 삭제(delete)

kustomize build ./k8s | kubectl delete -f -
# 또는
kubectl delete -k ./k8s

---

4. 디렉터리 구조가 커질 때: “kustomization.yaml을 디렉터리마다 둔다”

매니페스트가 늘면 기능별로 디렉터리를 나누게 됩니다.

k8s/
  api/
  db/
  cache/

이때 루트에서 한 번에 배포하고 싶다면:

• 각 서브디렉터리에 kustomization.yaml을 만들고
• 루트 kustomization에서 “디렉터리”를 resources로 가져오면 됩니다.

루트 k8s/kustomization.yaml:

resources:
  - api
  - db
  - cache

서브 k8s/api/kustomization.yaml:

resources:
  - api-depl.yaml
  - api-svc.yaml

---

5. Transformers: “전체 공통 변경”을 한 번에

5.1 Common Transformations

commonLabels

모든 리소스에 공통 라벨 추가:

commonLabels:
  org: KodeKloud

namespace

모든 리소스를 특정 네임스페이스로:

namespace: dev

namePrefix / nameSuffix

모든 리소스 이름에 접두/접미:

nameSuffix: -dev

중요: nameSuffix는 metadata.name만 바꾸는 단순 치환이 아닙니다.
Kustomize가 알고 있는 name reference(참조 관계) 까지 함께 업데이트하려고 합니다.
예: secretKeyRef.name, configMapRef.name, serviceAccountName, ingress backend service name 등.

단, CRD 같은 Kustomize가 모르는 참조 필드나 단순 문자열로 박힌 값은 자동 변경이 안 될 수 있어 kubectl kustomize | less로 렌더링 결과 확인이 안전합니다.

commonAnnotations

모든 리소스에 공통 어노테이션:

commonAnnotations:
  owner: platform-team

---

5.2 Image Transformer: 이미지/태그를 파일 수정 없이 교체

images:
  - name: nginx
    newName: haproxy
    newTag: "2.4"

• images[].name은 컨테이너 이름이 아니라 이미지 이름 기준입니다.
• image: nginx를 찾아 haproxy:2.4로 바꿉니다.

---

6. Patches: “특정 리소스/필드만” 정밀 타격

Transformers가 “전체 공통”이라면, patches는 “선별 적용”입니다.
대표적으로 환경별 replicas 조정은 patches가 가장 자연스럽습니다.

패치에는 크게 두 계열이 있습니다.

6.1 JSON 6902 Patch (op/path/value)

• add, remove, replace
• YAML 트리 경로를 /spec/replicas 같은 형태로 지정
• 리스트는 인덱스(containers/0)를 씀

예: replicas 교체

patches:
  - target:
      kind: Deployment
      name: api-deployment
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 5

여기서 |-는 뭔가?

YAML의 멀티라인 문자열 표기입니다.

• | : 줄바꿈을 보존한 문자열
• - : 마지막 개행 제거

즉 patch: 아래에 여러 줄을 “문자열로” 넣는 문법입니다.

---

6.2 Strategic Merge Patch (가독성 좋은 방식)

원본 리소스 YAML처럼 작성하고 바뀔 부분만 남겨 merge합니다.

예: replicas 변경 패치 파일 replicas-patch.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-deployment
spec:
  replicas: 5

kustomization:

patchesStrategicMerge:
  - replicas-patch.yaml

map(dictionary) 조작: labels 추가/삭제/교체

• 교체/추가는 그냥 쓰면 merge
• 삭제는 null로 표현하는 패턴이 흔함

예: label 삭제

spec:
  template:
    metadata:
      labels:
        org: null

list(array) 조작: containers

• strategic merge는 보통 name을 키로 merge하는 동작을 기대할 수 있어 “image 변경” 같은 건 깔끔합니다.
• 하지만 컨테이너 name 자체를 rename하는 건 merge key라서 strategic merge로 깔끔하게 표현하기가 어렵습니다.
  • 이런 rename은 JSON 6902가 확실하지만, 인덱스 의존 위험이 있으므로 “정말 필요한지” 판단이 중요합니다.
  • 실무에서는 보통 컨테이너 name은 유지하고 image만 바꾸는 경우가 많습니다.

---

6.3 Inline vs Separate File

패치가 많아지면 kustomization.yaml이 지저분해지므로 파일로 분리하는 패턴이 좋습니다.

• JSON 6902: inline 또는 파일로 분리
• Strategic merge: 대개 파일 분리가 자연스럽고 가독성이 좋음

---

7. Overlays: Kustomize의 메인 유스케이스 “환경별 조립”

표준 구조:

k8s/
  base/
  overlays/
    dev/
    staging/
    prod/

base/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - nginx-depl.yaml
  - nginx-svc.yaml

overlays/dev/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../../base

nameSuffix: -dev
namespace: dev

patchesStrategicMerge:
  - replicas.yaml

images:
  - name: nginx
    newTag: "latest"

overlays/dev/replicas.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 1

overlays/prod는 prod 정책으로

• replicas=5, namespace=prod, tag=1.2.3 등

---

overlays는 “패치만”이 아니라 “환경 전용 리소스도 추가” 가능

예: prod에만 grafana

resources:
  - ../../base
  - grafana-depl.yaml

---

8. Components: “전체(base)”도 아니고 “특정 overlay 하나”도 아닌, 선택적 기능 재사용 블록

Components는 이런 상황을 해결합니다.

• 캐싱(redis)은 premium + self-hosted에만 필요
• 외부 DB(postgres)는 dev + premium에만 필요

이걸 overlay마다 복붙하면 drift가 생깁니다.
그래서 기능 단위(옵션 기능) 로 configs를 묶어 여러 overlay에서 선택적으로 include합니다.

폴더 예:

k8s/
  base/
  components/
    caching/
    database/
  overlays/
    dev/
    premium/
    standalone/

component의 kustomization.yaml은 apiVersion/kind가 다름

components/database/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1alpha1
kind: Component

resources:
  - postgres-depl.yaml
  - db-secret.yaml

patchesStrategicMerge:
  - api-db-env-patch.yaml

overlay에서 component 포함

overlays/dev/kustomization.yaml

resources:
  - ../../base

components:
  - ../../components/database

premium은 database + caching 둘 다 포함하면 됩니다.

---

9. 운영 베스트 프랙티스(실전 기준)

1. base는 최대한 “공통”만
   환경별 값은 overlays에서 처리(특히 replicas, image tag, resources limits)
2. 공통 일괄 변경은 transformers
   labels/annotations/namespace/nameSuffix 등
3. 선별 변경은 patches
   특정 deployment만 replicas, 특정 env만 env var 추가 등
4. 적용 전 항상 렌더링/디프

kubectl kustomize ./k8s/overlays/dev | less
kubectl diff -k ./k8s/overlays/dev

5. 컨테이너 rename(특히 strategic merge)은 신중
   이미지 교체는 images 또는 “name 기준 image 필드만 patch”로 안전하게 가는 편이 좋음

---

마무리: Kustomize를 한 문장으로

“Base를 한 번만 쓰고, 환경/옵션의 차이를 overlays/components로 조립해서, 복붙 없이 표준 YAML로 운영하는 도구”입니다.

원하면 위 내용을 기반으로, 예제 레포 수준으로 다음을 한 번에 묶어서 제공할 수 있습니다.

• base(nginx/api) + overlays(dev/staging/prod)
• transformers(nameSuffix/namespace/commonLabels)
• patches(replicas/resources/env)
• components(caching/database)
• kubectl apply -k로 각 환경 배포/삭제 시나리오까지 완성된 형태