Kustomize - Overlays

Kustomize의 핵심 유스케이스는 결국 하나입니다.

• 공통/기본 매니페스트는 base에 둔다
• 환경별로 달라지는 부분만 overlays에서 패치/변환으로 덮어쓴다
• 배포 시에는 kubectl apply -k overlays/<env> 한 줄로 끝낸다

이 구조가 “매니페스트 복붙 지옥”을 끝내기 위해 Kustomize가 만들어진 이유이기도 합니다.

---

1) 기본 폴더 구조

가장 흔한 형태는 아래처럼 base + overlays로 나뉩니다.

k8s/
  base/
    nginx-depl.yaml
    kustomization.yaml
  overlays/
    dev/
      kustomization.yaml
      (patch files...)
    staging/
      kustomization.yaml
      (patch files...)
    prod/
      kustomization.yaml
      (patch files...)

• base/: 모든 환경에 공통으로 들어갈 리소스(또는 기본값)
• overlays/<env>/: 해당 환경에만 적용되는 변경(패치, transformers, 추가 리소스)

---

2) base의 kustomization.yaml

base는 “그냥 리소스 목록”을 선언하는 게 기본입니다.

k8s/base/kustomization.yaml

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

resources:
  - nginx-depl.yaml

k8s/base/nginx-depl.yaml 예시(기본값)

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

---

3) overlay의 핵심: base를 가져오고(pull), 패치로 바꾼다

강의에서는 overlay의 kustomization.yaml에서 bases를 사용했습니다.
요즘은 resources로 base 디렉터리를 참조하는 형태가 더 일반적입니다(동작 개념은 동일).

dev overlay 예시(복제 없이 replicas만 변경)

k8s/overlays/dev/kustomization.yaml

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

resources:
  - ../../base

patchesStrategicMerge:
  - replicas.yaml

k8s/overlays/dev/replicas.yaml

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

prod overlay 예시(replicas를 3으로)

k8s/overlays/prod/kustomization.yaml

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

resources:
  - ../../base

patchesStrategicMerge:
  - replicas.yaml

k8s/overlays/prod/replicas.yaml

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

여기까지가 overlay의 본질입니다.

• base는 그대로 재사용
• 환경별로 달라지는 값만 patch로 오버라이드

---

4) 배포/삭제는 환경 디렉터리를 -k로 지정하면 끝

dev 적용

kubectl apply -k ./k8s/overlays/dev

prod 적용

kubectl apply -k ./k8s/overlays/prod

삭제도 동일

kubectl delete -k ./k8s/overlays/dev

---

5) overlays는 “패치만”이 아니라 “추가 리소스도” 가능

강의에서 강조한 포인트:
overlay는 base를 수정하는 것뿐 아니라 해당 환경에만 존재하는 리소스도 포함할 수 있습니다.

예를 들어 prod에서만 Grafana를 띄우고 싶다면:

k8s/overlays/prod/
  kustomization.yaml
  replicas.yaml
  grafana-depl.yaml

k8s/overlays/prod/kustomization.yaml

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

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

patchesStrategicMerge:
  - replicas.yaml

이렇게 하면:

• 모든 환경 공통 nginx는 base에서 가져오고
• prod에서만 grafana가 추가됩니다.

---

6) 디렉터리 구조는 강제되지 않는다(유연성)

반드시 base/에 모든 걸 “평면으로” 몰아넣을 필요가 없습니다.

예:

base/
  api/
  db/
  cache/
  kustomization.yaml

그리고 base의 kustomization.yaml에서 디렉터리 단위로 import하면 됩니다(각 디렉터리에 kustomization.yaml이 있다면 더 깔끔).

overlay도 마찬가지로:

• dev는 단순
• prod는 여러 컴포넌트 + 추가 리소스
  처럼 환경별로 구조가 달라도 됩니다.

중요한 건 “import 경로가 올바르게 연결되느냐”입니다.

---

정리

• Overlays = base 재사용 + 환경별 패치
• overlays/<env>/kustomization.yaml에서 ../../base를 참조하고, 패치를 붙인다
• overlay는 패치뿐 아니라 환경 전용 리소스도 추가할 수 있다
• 적용은 kubectl apply -k overlays/<env>로 한 줄

 

 

Access the lab here: https://learn.kodekloud.com/user/courses/udemy-labs-certified-kubernetes-administrator-with-practice-tests/module/f868dfbe-80b2-44cf-97e7-d00fc0d91307/lesson/a2d3ef06-b264-41a2-8e13-2ec409afabfe