Kustomize components, 모르는 분 많더라

Kustomize components, 모르는 분 많더라

오늘 동료 PR 리뷰하다가 발견한 건데, base/overlay만 쓰고 components를 안 쓰는 분이 의외로 많다. Kustomize 공식 문서에도 들어있고 1.21 이후로는 stable인데 잘 안 알려진 듯. 짧게 정리해둔다.

어떤 상황에서 쓰면 좋냐

흔한 패턴 — base 하나에 overlay가 dev / staging / prod 이렇게 있다고 치자. 어느 날 누가 "prod랑 staging에는 sidecar 하나 붙여줘"라고 한다. 그러면 보통은 두 overlay에 같은 patch를 복붙한다. 며칠 뒤 또 다른 feature가 prod/staging 공통으로 들어오면? 또 복붙.

이게 쌓이다 보면 overlay 디렉터리가 patch 파일 모음이 되고, dev에는 들어가면 안 되는 옵션이 실수로 들어가는 사고가 가끔 난다. 우리 팀에서도 한 번 그런 적 있었다.

components는 이 "공통으로 켜고 끄는 feature"를 별도 디렉터리로 떼어내는 기능이다. overlay에서 components: [../../components/sidecar] 한 줄로 켜고, 안 쓰는 overlay에서는 그냥 빼면 끝.

디렉터리 구조 예시

base/
  deployment.yaml
  kustomization.yaml
components/
  sidecar/
    kustomization.yaml   # kind: Component
    patch.yaml
  istio-injection/
    kustomization.yaml
overlays/
  dev/
    kustomization.yaml         # components 없음
  staging/
    kustomization.yaml         # sidecar, istio 켬
  prod/
    kustomization.yaml         # sidecar, istio 켬

component 쪽 kustomization.yaml 은 일반 kustomization 과 살짝 다르다:

apiVersion: kustomize.config.k8s.io/v1alpha1
kind: Component
patches:
  - path: patch.yaml
    target:
      kind: Deployment

kind가 Kustomization이 아니라 Component다. 이거 빼먹으면 그냥 일반 base로 인식해서 묘하게 안 먹힌다. 처음에 이거 때문에 30분 날렸다.

resources vs components, 뭐가 다른가

base는 한 번만 적용되지만, component는 적용 순서대로 누적된다.

resources로 다른 kustomization을 가져오면 거기 있는 patch가 base에 한 번 합쳐지고 끝이다. 반면 components는 overlay에서 선언한 순서대로 차례차례 적용된다. 그래서 component 두 개가 같은 필드를 건드리면 뒤에 선언한 게 이긴다. 이 동작이 의외로 유용한 게, "기본은 A, prod에서는 A 다음에 B로 덮어쓰기" 같은 패턴을 자연스럽게 표현할 수 있다.

안 쓰면 손해 보는 케이스

• 같은 patch를 여러 overlay에 복붙 중일 때
• feature flag처럼 켜고 끄고 싶은 설정이 있을 때 (debug용 sidecar, mTLS strict 모드 등)
• 멀티 테넌트 매니페스트에서 일부 테넌트만 추가 기능을 받을 때

ArgoCD/Flux 둘 다 components를 그대로 인식한다. ArgoCD는 2.x 이후 별다른 설정 없이 동작하고 Flux도 마찬가지.

끝으로

생각보다 알려져 있지 않은 듯해서 정리했다. 혹시 이미 쓰고 계신 분 있으면 어떤 식으로 디렉터리 자르는지 댓글로 공유 부탁드린다. 우리 팀도 component 단위를 어디까지 잘게 쪼개야 할지 아직 고민 중이다.