Kustomize : Kustomize를 사용한 Kubernetes 리소스 배포

🧩  개요

Kustomize는 template를 쓰지 않고 plain YAML 파일들에 오직 ‘customization(재정의)’만 적용해 Kubernetes 리소스를 관리하는 도구입니다.
Kustomize는 kubectl에 통합되어 있으며, 기본(base) 리소스와 환경별 overlay를 조합해 최종 YAML을 생성합니다.
Kustomize를 쓰면 원본 YAML 파일은 그대로 두고(비침습적) 변경점만 별도로 관리할 수 있어 실수로 인한 손상을 줄입니다.
"템플릿 없이 plain YAML을 재사용하고, 변경점만 분리해 관리하는 것이 Kustomize의 핵심입니다."

---

⚙️ 4.1 Using Kustomize to Deploy Kubernetes Resources

• Kustomize 프로젝트는 보통 base 디렉터리(변경이 적은 표준 리소스들)와 환경별 overlay(staging, prod 등)로 구성됩니다.
  "base와 overlay 구조로 환경별 차이를 깔끔하게 분리합니다."
• 기본 구성: kustomization.yaml에 resources 목록(예: Namespace, Deployment, Service)을 선언합니다."kustomization.yaml에 리소스 목록을 적으면 kustomize가 병합된 최종 YAML을 생성합니다."
• apiVersion: kustomize.config.k8s.io/v1beta1 kind: Kustomization resources: - ./namespace.yaml - ./deployment.yaml - ./service.yaml
• 실행 방법(검증용 dry-run 포함):"-k 옵션과 kustomize build로 최종 YAML을 확인/적용합니다."
• kubectl apply --dry-run=client -o yaml -k . kustomize build . | kubectl apply -f -
• resources에는 로컬 파일뿐 아니라 다른 kustomize 프로젝트(base 디렉터리)나 Git/URL 참조도 가능합니다.
  "외부 repo나 base 디렉터리를 재사용해 구성을 계층화할 수 있습니다."

(⎈|kind-myk8s:N/A) ssoon@DESKTOP-72C919S:~/pacman$ cat <<EOF > namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: pacman
EOF

(⎈|kind-myk8s:N/A) ssoon@DESKTOP-72C919S:~/pacman$ cat <<EOF > deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: pacman-kikd
  namespace: pacman
  labels:
    app.kubernetes.io/name: pacman-kikd
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: pacman-kikd
  template:
    metadata:
      labels:
        app.kubernetes.io/name: pacman-kikd
    spec:
      containers:
      - image: lordofthejars/pacman-kikd:1.0.0
        imagePullPolicy: Always
        name: pacman-kikd
        ports:
        - containerPort: 8080
          name: http
          protocol: TCP
EOF

(⎈|kind-myk8s:N/A) ssoon@DESKTOP-72C919S:~/pacman$ cat <<EOF > service.yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    app.kubernetes.io/name: pacman-kikd
  name: pacman-kikd
  namespace: pacman
spec:
  ports:
  - name: http
    port: 8080
    targetPort: 8080
  selector:
    app.kubernetes.io/name: pacman-kikd
EOF

 

 

(⎈|kind-myk8s:N/A) ssoon@DESKTOP-72C919S:~/pacman$ cat <<EOF > kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ./namespace.yaml
  - ./deployment.yaml
  - ./service.yaml
EOF

• apiVersion: kustomize.config.k8s.io/v1beta1
  • 이 kustomization.yaml 파일이 Kustomize 설정 API의 v1beta1 버전을 사용한다는 것을 Kubernetes에 알려줍니다.
• kind: Kustomization
  • 이 파일이 Kustomize 설정을 정의하는 파일임을 명시합니다.
• resources:
  • Kustomize가 관리할 Kubernetes 리소스 파일들의 목록입니다. Kustomize는 이 목록에 있는 파일들을 순서대로 읽어들여 하나의 큰 YAML 파일로 통합합니다.
    • ./namespace.yaml
    • ./deployment.yaml
    • ./service.yaml

"kustomization.yaml 파일은 애플리케이션에 속한 모든 리소스 파일들을 resources 필드 아래에 나열하여 Kustomize가 이를 처리하도록 지시합니다."

• Kustomize가 생성할 최종 YAML을 클러스터에 적용하지 않고 화면에 출력

(⎈|kind-myk8s:N/A) ssoon@DESKTOP-72C919S:~/pacman$ kubectl apply --dry-run=client -o yaml -k ./
apiVersion: v1
items:
- apiVersion: v1
  kind: Namespace
  metadata:
    annotations:
      kubectl.kubernetes.io/last-applied-configuration: |
        {"apiVersion":"v1","kind":"Namespace","metadata":{"annotations":{},"name":"pacmancat"}}
    name: pacmancat
- apiVersion: v1
  kind: Service
  metadata:
    annotations:
      kubectl.kubernetes.io/last-applied-configuration: |
        {"apiVersion":"v1","kind":"Service","metadata":{"annotations":{},"labels":{"app.kubernetes.io/name":"pacman-kikd"},"name":"pacman-kikd","namespace":"pacman"},"spec":{"ports":[{"name":"http","port":8080,"targetPort":8080}],"selector":{"app.kubernetes.io/name":"pacman-kikd"}}}
    labels:
      app.kubernetes.io/name: pacman-kikd
    name: pacman-kikd
    namespace: pacman
  spec:
    ports:
    - name: http
      port: 8080
      targetPort: 8080
    selector:
      app.kubernetes.io/name: pacman-kikd
- apiVersion: apps/v1
  kind: Deployment
  metadata:
    annotations:
      kubectl.kubernetes.io/last-applied-configuration: |
        {"apiVersion":"apps/v1","kind":"Deployment","metadata":{"annotations":{},"labels":{"app.kubernetes.io/name":"pacman-kikd"},"name":"pacman-kikd","namespace":"pacman"},"spec":{"replicas":1,"selector":{"matchLabels":{"app.kubernetes.io/name":"pacman-kikd"}},"template":{"metadata":{"labels":{"app.kubernetes.io/name":"pacman-kikd"}},"spec":{"containers":[{"image":"lordofthejars/pacman-kikd:1.0.0","imagePullPolicy":"Always","name":"pacman-kikd","ports":[{"containerPort":8080,"name":"http","protocol":"TCP"}]}]}}}}
    labels:
      app.kubernetes.io/name: pacman-kikd
    name: pacman-kikd
    namespace: pacman
  spec:
    replicas: 1
    selector:
      matchLabels:
        app.kubernetes.io/name: pacman-kikd
    template:
      metadata:
        labels:
          app.kubernetes.io/name: pacman-kikd
      spec:
        containers:
        - image: lordofthejars/pacman-kikd:1.0.0
          imagePullPolicy: Always
          name: pacman-kikd
          ports:
          - containerPort: 8080
            name: http
            protocol: TCP
kind: List
metadata: {}

🚀 Kustomize 심화: Base, 원격 저장소 및 CLI 활용하기

Kustomize의 resources 섹션은 단순히 개별 YAML 파일을 나열하는 것 외에도 강력하고 유연한 입력 방식들을 지원합니다.

---

📂 Kustomize Base를 활용한 계층적 구성

resources 섹션은 다른 Kustomize 디렉터리(일반적으로 base라고 함)를 참조하여 구성을 계층적으로 관리할 수 있습니다.

애플리케이션이 다음과 같은 디렉터리 구조를 가졌다고 가정해 봅시다.

.
├── base
│   ├── kustomization.yaml
│   └── deployment.yaml
├── kustomization.yaml
├── configmap.yaml

base 디렉터리 내부의 kustomization.yaml 파일은 자신이 관리할 리소스를 정의합니다.

# base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ./deployment.yaml

이때, 루트(root) 디렉터리의 kustomization.yaml 파일은 base 디렉터리 자체와 추가적인 configmap.yaml 파일을 resources로 포함할 수 있습니다.

# ./kustomization.yaml (루트 파일)
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ./base
  - ./configmap.yaml

루트 kustomization.yaml 파일을 적용하면, Kustomize는 base 디렉터리의 kustomization.yaml에 정의된 리소스(deployment.yaml)를 자동으로 병합하여 configmap.yaml과 함께 처리합니다.

"상위 kustomization.yaml 파일의 resources에 base 디렉터리를 포함시키면, 하위 리소스들이 자동으로 병합되어 적용됩니다."

---

🌐 원격 저장소(Git) 리소스 참조하기

resources 필드는 HashiCorp URL 형식을 따르는 외부 URL의 에셋(asset)을 참조할 수 있습니다.

예를 들어, 다음과 같이 GitHub 저장소 URL을 직접 설정하여 해당 저장소에 있는 Kustomize 설정을 가져올 수 있습니다.

resources:
  # 저장소 루트에 kustomization.yaml 파일이 있는 경우
  - github.com/lordofthejars/mysql
  
  # 'test' 브랜치의 kustomization.yaml 파일을 참조하는 경우
  - github.com/lordofthejars/mysql?ref=test

"Kustomize는 로컬 파일뿐만 아니라, github.com과 같은 원격 Git 저장소에 있는 kustomization 설정을 직접 참조할 수 있습니다."

💻 독립형 kustomize CLI 도구 사용하기

지금까지 kubectl에 내장된 Kustomize 기능을 사용했지만, Kustomize는 Kustomize 리소스와 상호작용하기 위한 자체 CLI(Command Line Interface) 도구도 제공합니다.

kubectl 대신 독립형 kustomize CLI를 사용하여 리소스를 빌드(build)하는 명령어는 다음과 같습니다

이 명령어의 출력 결과는 kubectl kustomize ./ (또는 kubectl apply -k ./ --dry-run=client -o yaml)의 결과와 동일하며, 모든 리소스가 병합된 표준 YAML 스트림(stream)을 출력합니다.

(⎈|kind-myk8s:N/A) ssoon@DESKTOP-72C919S:~/pacman$ sudo snap install kustomize
[sudo] password for ssoon:
2025-10-18T19:11:42+09:00 INFO Waiting for automatic snapd restart...
kustomize 5.3.0 from abskmj installed
(⎈|kind-myk8s:N/A) ssoon@DESKTOP-72C919S:~/pacman$ kustomize build
apiVersion: v1
kind: Namespace
metadata:
  name: pacmancat
---
apiVersion: v1
kind: Service
metadata:
  labels:
    app.kubernetes.io/name: pacman-kikd
  name: pacman-kikd
  namespace: pacman
spec:
  ports:
  - name: http
    port: 8080
    targetPort: 8080
  selector:
    app.kubernetes.io/name: pacman-kikd
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app.kubernetes.io/name: pacman-kikd
  name: pacman-kikd
  namespace: pacman
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: pacman-kikd
  template:
    metadata:
      labels:
        app.kubernetes.io/name: pacman-kikd
    spec:
      containers:
      - image: lordofthejars/pacman-kikd:1.0.0
        imagePullPolicy: Always
        name: pacman-kikd
        ports:
        - containerPort: 8080
          name: http
          protocol: TCP

•  kustomize로 생성된 출력을 클러스터에 적용

(⎈|kind-myk8s:N/A) ssoon@DESKTOP-72C919S:~/pacman$ kustomize build . | kubectl apply -f -
namespace/pacman created
service/pacman-kikd created
deployment.apps/pacman-kikd created