Kustomize - Transformers

Kustomize의 진짜 가치가 드러나는 지점이 Transformers(변환기) 입니다.
YAML 파일이 몇 개 없을 때는 수동 수정도 가능하지만, 실무에서는 리소스가 수십~수백 개가 되기 때문에 “공통 변경”을 파일마다 손으로 넣는 방식은 금방 한계가 옵니다.

Kustomize는 이를 Transformers로 해결합니다.

• 여러 리소스에 공통 라벨/어노테이션을 붙이기
• 이름에 prefix/suffix를 붙여 환경(dev/stage/prod)을 구분하기
• 네임스페이스를 통일해서 적용하기
• 이미지 이름/태그를 한 번에 변경하기

---

1) 왜 “Common Transformations”가 필요한가?

상황을 단순화하면 이런 요구가 자주 생깁니다.

• 모든 리소스에 org=KodeKloud 라벨을 붙이고 싶다
• dev 환경에서는 리소스 이름 뒤에 -dev를 붙이고 싶다
• 모든 리소스를 dev 네임스페이스로 넣고 싶다
• 모든 리소스에 공통 어노테이션(예: 소유 팀, 릴리즈 정보)을 넣고 싶다

이걸 파일마다 수동으로 넣으면:

• 누락/오타가 반드시 발생하고
• YAML 수가 늘수록 작업량이 폭증하며
• 변경이 잦은 운영 환경에서는 유지보수가 불가능해집니다

그래서 Kustomize의 Common Transformations가 필요합니다.

---

2) Common Transformations 4종 세트

아래 변환들은 kustomization.yaml에 선언만 하면, 그 kustomization이 import하는 모든 리소스에 일괄 적용됩니다.

(1) commonLabels: 모든 리소스에 공통 라벨 추가

kustomization.yaml

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

resources:
  - deployment.yaml
  - service.yaml

commonLabels:
  org: KodeKloud
  app.kubernetes.io/managed-by: kustomize

결과:

• Deployment, Service 모두 metadata.labels에 동일 라벨이 추가됩니다.

---

(2) namePrefix / nameSuffix: 모든 리소스 이름에 접두/접미 추가

kustomization.yaml

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

resources:
  - deployment.yaml
  - service.yaml

nameSuffix: -dev
# 또는
# namePrefix: dev-

결과:

• metadata.name: api → metadata.name: api-dev
• Deployment와 Service가 같은 이름을 공유하는 경우(라벨/셀렉터 구조 등)도 Kustomize가 관계를 유지하도록 변경합니다.

실무 팁: suffix/prefix는 환경별 overlay에서 많이 사용합니다(예: prod는 접미어 없이, dev만 -dev).

---

(3) namespace: 모든 리소스를 특정 네임스페이스로

kustomization.yaml

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

resources:
  - deployment.yaml
  - service.yaml

namespace: dev

결과:

• namespace가 지정되지 않았던 리소스에도 metadata.namespace: dev가 적용됩니다.

주의: 네임스페이스 리소스(Namespace 오브젝트) 생성은 별개로 해줘야 하는 경우가 많습니다. (다음 예시 참고)

예:

resources:
  - namespace.yaml
  - deployment.yaml
  - service.yaml

namespace: dev

---

(4) commonAnnotations: 모든 리소스에 공통 어노테이션 추가

kustomization.yaml

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

resources:
  - deployment.yaml
  - service.yaml

commonAnnotations:
  owner: platform-team
  contact: "slack:#platform"

결과:

• Deployment, Service 모두 metadata.annotations에 공통 값이 추가됩니다.

---

3) Image Transformer: 이미지 이름/태그를 “파일 수정 없이” 교체

이제 공통 변환을 넘어, 실무에서 특히 자주 쓰는 것이 images 변환입니다.
환경별로 이미지 태그를 바꾸는 건 거의 필수니까요.

기본 Deployment 예시

deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 1
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: web
          image: nginx

---

3-1) 이미지 이름 자체를 바꾸기 (nginx → haproxy)

kustomization.yaml

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

resources:
  - deployment.yaml

images:
  - name: nginx
    newName: haproxy

동작:

• 모든 리소스를 스캔해서 image: nginx를 찾고
• image: haproxy로 치환합니다.

혼동 포인트(강의에서 강조)

• images[].name는 컨테이너 이름이 아니라 이미지 이름입니다.
• Deployment의 containers[].name: web 같은 값과 무관합니다.
• Kustomize는 image: nginx 문자열을 기준으로 매칭합니다.

---

3-2) 이미지 태그만 바꾸기 (nginx → nginx:2.4)

kustomization.yaml

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

resources:
  - deployment.yaml

images:
  - name: nginx
    newTag: "2.4"

결과:

• image: nginx → image: nginx:2.4

---

3-3) 이미지 이름 + 태그를 동시에 바꾸기 (nginx → haproxy:2.4)

kustomization.yaml

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

resources:
  - deployment.yaml

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

결과:

• image: nginx → image: haproxy:2.4

---

4) 실전 적용 패턴: base는 공통, overlay에서 transformer로 환경별 차이만

실무에서는 보통:

• base/에는 Deployment에 image: myapp까지만 둬서 공통 유지
• overlays/dev에서 images.newTag만 dev 태그로 변경
• overlays/prod에서 prod 태그로 변경

예:

overlays/prod/kustomization.yaml

resources:
  - ../../base

images:
  - name: myapp
    newTag: "1.0.7"

이렇게 하면 “YAML 원본은 건드리지 않고” 환경별 배포만 깔끔하게 분리됩니다.

---

정리

• Transformers는 Kustomize의 핵심: 여러 리소스에 공통 변경을 “한 번에” 적용한다.
• Common Transformations:
  • commonLabels: 공통 라벨
  • namePrefix/nameSuffix: 공통 이름 접두/접미
  • namespace: 공통 네임스페이스
  • commonAnnotations: 공통 어노테이션
• Image Transformer(images):
  • newName으로 이미지 자체 교체
  • newTag로 태그만 교체
  • 둘을 함께 써서 haproxy:2.4 같은 최종 이미지로 변경 가능
• images[].name는 컨테이너 name이 아니라 이미지 name을 기준으로 매칭한다.