Kustomize - 여러 디렉토리 관리

Kustomize를 조금만 알아도 바로 체감되는 강력한 기능 중 하나가 “여러 디렉터리에 흩어진 매니페스트를 한 번에 빌드/적용”하는 방식입니다.
리소스가 늘어날수록 YAML 파일이 많아지고, 결국 디렉터리 정리가 필요해지는데, 이때 Kustomize가 CI/CD와 운영 흐름을 깔끔하게 만들어 줍니다.

---

1) 문제 상황: YAML이 많아져서 서브디렉터리로 정리했다

처음에는 k8s/ 아래에 YAML이 4개 정도라면, 그냥 한 번에 적용하면 됩니다.

k8s/
  api-deployment.yaml
  api-service.yaml
  db-deployment.yaml
  db-service.yaml

kubectl apply -f ./k8s

그런데 시간이 지나면서 20~50개가 되면 디렉터리가 지저분해집니다. 그래서 보통 컴포넌트 기준으로 나눕니다.

k8s/
  api/
    deployment.yaml
    service.yaml
  database/
    deployment.yaml
    service.yaml

이 순간부터 문제가 생깁니다.

• 이제 kubectl apply -f ./k8s를 하면 서브디렉터리를 자동으로 타고 들어가서 적용하지 않습니다.
• 결국 각 디렉터리를 따로따로 적용해야 합니다.

kubectl apply -f ./k8s/api
kubectl apply -f ./k8s/database

디렉터리가 4개, 6개, 10개로 늘어나면?

• 매번 여러 번 명령을 실행해야 하고
• 삭제도 여러 번 해야 하고
• CI/CD 파이프라인도 디렉터리마다 반복 작업이 생기면서 지저분해집니다.

---

2) 해결 1: 루트(k8s/)에 kustomization.yaml 하나 두고 “모든 파일을 나열”한다

k8s/kustomization.yaml을 만들고, 서브디렉터리 안의 파일들을 상대경로로 전부 적는 방식입니다.

k8s/
  kustomization.yaml
  api/
    deployment.yaml
    service.yaml
  database/
    deployment.yaml
    service.yaml

k8s/kustomization.yaml

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

resources:
  - api/deployment.yaml
  - api/service.yaml
  - database/deployment.yaml
  - database/service.yaml

이제 적용은 한 줄입니다.

적용

kubectl apply -k ./k8s

또는 build + apply 파이프:

kustomize build ./k8s | kubectl apply -f -

삭제도 동일하게 한 줄로 처리됩니다.

kubectl delete -k ./k8s

이 방식만으로도 “서브디렉터리마다 들어가서 apply”하던 문제는 해결됩니다.

---

3) 그런데… 루트 resources가 너무 길어진다(디렉터리가 늘어나면 지옥)

컴포넌트가 늘면 아래처럼 됩니다.

• api/
• database/
• cache/
• kafka/
• … 기타 등등

이때 루트 kustomization.yaml에서 파일을 하나하나 나열하면:

• resources: 목록이 수십~수백 줄로 늘고
• 유지보수도 힘들어지고
• 파일 추가/이동 시 루트 파일 수정이 잦아집니다.

그래서 Kustomize의 더 좋은 구조가 나옵니다.

---

4) 해결 2(권장): “서브디렉터리마다 kustomization.yaml”을 두고 루트는 디렉터리만 참조한다

구조

k8s/
  kustomization.yaml
  api/
    kustomization.yaml
    deployment.yaml
    service.yaml
  database/
    kustomization.yaml
    deployment.yaml
    service.yaml
  cache/
    kustomization.yaml
    deployment.yaml
    service.yaml
  kafka/
    kustomization.yaml
    deployment.yaml
    service.yaml

각 서브디렉터리 kustomization.yaml 예시

k8s/api/kustomization.yaml

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

resources:
  - deployment.yaml
  - service.yaml

k8s/database/kustomization.yaml

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

resources:
  - deployment.yaml
  - service.yaml

(나머지 cache/kafka도 동일)

루트 kustomization.yaml은 “디렉터리만” 참조

k8s/kustomization.yaml

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

resources:
  - api
  - database
  - cache
  - kafka

여기서 중요한 동작:

• 루트에서 resources: - api를 쓰면
• Kustomize는 k8s/api/로 들어가서
• 그 안의 kustomization.yaml을 찾고
• 거기서 정의한 resources를 통째로 가져옵니다.

즉, 루트는 깔끔하게 유지되고, 컴포넌트별로 독립적인 구성이 됩니다.

---

5) 적용/삭제는 여전히 한 줄(운영/CI가 깔끔해짐)

적용

kubectl apply -k ./k8s

삭제

kubectl delete -k ./k8s

또는 build 결과를 보고 싶다면:

kubectl kustomize ./k8s | less

---

6) 실무에서 이 구조가 특히 좋은 이유

• 컴포넌트 단위로 분리되어 팀/모듈별 소유권이 명확해짐 (api 팀은 api 폴더만)
• 루트 kustomization.yaml이 항상 짧고 안정적
• CI/CD도 “한 디렉터리 기준으로 apply -k”만 하면 끝
• 특정 컴포넌트만 따로 적용/삭제하고 싶으면 그 컴포넌트 디렉터리에 대해 실행 가능

예:

kubectl apply -k ./k8s/api
kubectl delete -k ./k8s/kafka

---

정리

• YAML이 서브디렉터리로 분산되면 kubectl apply -f ./k8s만으로는 한 번에 적용하기가 어려워진다.
• Kustomize는 루트 kustomization.yaml을 통해 여러 디렉터리의 리소스를 한 번에 빌드/적용할 수 있다.
• 디렉터리가 많아질수록 베스트 프랙티스는:
  • 서브디렉터리마다 kustomization.yaml
  • 루트는 디렉터리만 resources로 참조
• 적용/삭제는 항상 한 줄:
  • kubectl apply -k ./k8s
  • kubectl delete -k ./k8s