kustomize - kustomization.yaml

Kustomize를 설치했다면, 이제 실제로 “Kustomize가 무엇을 기준으로 동작하는지”부터 잡아야 합니다. 그 중심에 있는 파일이 kustomization.yaml 입니다.

핵심 요약부터 말하면:

• Kustomize는 폴더 안의 YAML 파일을 자동으로 다 읽지 않습니다.
• 대신 반드시 kustomization.yaml(정확히 이 이름) 파일을 찾고,
• 그 안에 적힌 resources 목록과 변환(transformations)을 기준으로 최종 매니페스트를 만들어 냅니다.

---

1) 왜 kustomization.yaml가 필요한가?

예를 들어 k8s/ 디렉터리에 아래 두 파일이 있다고 합시다.

• nginx-deployment.yaml
• nginx-service.yaml

여기서 “Kustomize야, 이 폴더에 있는 걸 다 써”라고 하지 않습니다.
Kustomize는 어떤 파일을 포함할지(관리 대상) 명시적으로 선언해야 하고, 그 선언이 kustomization.yaml에 들어갑니다.

즉, kustomization.yaml은:

• “이 디렉터리는 Kustomize 프로젝트다”
• “이 YAML들을 대상으로”
• “이런 변환을 적용해서”
• “최종 YAML을 생성해라”

를 정의하는 엔트리포인트입니다.

---

2) kustomization.yaml의 구성: 크게 2가지

강의에서 말한 구조는 아주 단순합니다.

(1) resources: Kustomize가 관리할 리소스 목록

“어떤 YAML 파일들을 묶어서 관리할 것인가?”

(2) transformations: 공통 라벨 같은 변환/커스터마이징

“그 리소스들에 어떤 변경을 일괄로 적용할 것인가?”

---

3) 실습 예제: nginx Deployment + Service에 공통 라벨 추가

디렉터리 구조

k8s/
  nginx-deployment.yaml
  nginx-service.yaml
  kustomization.yaml

kustomization.yaml 예시

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

resources:
  - nginx-deployment.yaml
  - nginx-service.yaml

commonLabels:
  company: KodeKloud

여기서 포인트:

• resources에 두 YAML 파일을 명시
• commonLabels로 company=KodeKloud 라벨을 모든 리소스에 공통 적용

commonLabels는 “가장 쉬운 변환 예시”이고, 실제로는 이미지 교체, prefix/suffix, configMapGenerator 등 다양한 변환이 가능합니다.

---

4) kustomize build: “적용(apply)”이 아니라 “최종 결과 출력(render)”

이제 이 폴더를 대상으로 빌드하면:

kustomize build ./k8s

Kustomize는 다음을 수행합니다.

1. ./k8s/kustomization.yaml을 찾는다
2. resources에 적힌 YAML을 읽는다
3. commonLabels 같은 변환을 적용한다
4. 최종 매니페스트 YAML을 stdout(터미널)에 출력한다

출력에는 보통:

• nginx Service 리소스
• nginx Deployment 리소스
• 그리고 두 리소스 모두에 company: KodeKloud 라벨이 추가된 모습

이 포함됩니다.

중요한 점

kustomize build는 클러스터에 아무것도 배포하지 않습니다.
그냥 “최종 YAML이 이렇게 생긴다”를 보여주는 단계입니다.

---

5) kubectl에 적용하려면: build 결과를 apply로 넘겨야 한다

강의에서 다음 영상에서 다룬다고 했던 부분은 이 흐름입니다.

kustomize build ./k8s | kubectl apply -f -

• 왼쪽: 최종 YAML 생성
• 오른쪽: 그 YAML을 stdin으로 받아서 클러스터에 적용

또는 kubectl 내장 kustomize를 쓴다면(실무에서 많이 씀):

kubectl apply -k ./k8s

이건 내부적으로 “kustomize build + kubectl apply”를 한 번에 해주는 형태입니다.

---

6) 실무에서 같이 쓰는 검증/확인 명령(추천)

(1) 결과 YAML만 먼저 확인

kustomize build ./k8s | less

(2) 라벨이 실제로 붙었는지 확인

kubectl get deploy,svc -l company=KodeKloud

(3) diff로 변경점 확인(가능한 환경에서)

kubectl diff -k ./k8s

---

7) kustomizaion.yaml에서 apiVersion/kind는 생략 가능하지만 명시하는걸 권장

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

resources:
  - nginx-deployment.yaml
  - nginx-service.yaml

commonLabels:
  company: KodeKloud

일부 환경/버전에서는 kustomization.yaml에 apiVersion, kind가 없더라도 Kustomize가 관례적으로 이를 “Kustomization 파일”로 간주하고 기본값으로 처리해 동작할 수 있습니다.
하지만 이 동작은 버전/배포 방식(kubectl 내장 vs standalone)에 따라 달라질 여지가 있어서, 강의의 권장처럼 명시하는 편이 안전합니다.

 

 

정리

• Kustomize는 폴더의 YAML을 자동으로 다 읽지 않고, kustomization.yaml을 엔트리포인트로 삼는다.
• kustomization.yaml에는 크게 두 가지가 들어간다.
  • resources: 관리할 매니페스트 목록
  • transformations: 공통 라벨 같은 변환 규칙
• kustomize build는 배포가 아니라 최종 YAML을 출력하는 명령이다.
• 실제 적용은 kustomize build ... | kubectl apply -f - 또는 kubectl apply -k ...로 한다.