Kustomize 설정 관리

Kubernetes 매니페스트의 선언적 커스터마이징 도구

Kubernetes 매니페스트의 선언적 커스터마이징 도구

목표: 환경별 설정을 템플릿 없이 관리할 수 있는 수준

🎯 Kustomize 개요

Helm vs Kustomize

특징	Helm	Kustomize
방식	템플릿 엔진	오버레이/패치
학습곡선	높음	낮음
유연성	높음	중간
패키징	Chart	Base + Overlay
템플릿	필요	불필요

기본 개념

graph TB
    subgraph "Kustomize 구조"
        BASE["📁 Base<br/>기본 매니페스트"] -->|"오버레이"| OVERLAY["📁 Overlay<br/>환경별 설정"]
        OVERLAY -->|"생성"| FINAL["📄 최종 매니페스트"]
    end

📁 디렉토리 구조

k8s/
├── base/
│   ├── kustomization.yaml
│   ├── deployment.yaml
│   ├── service.yaml
│   └── configmap.yaml
└── overlays/
    ├── production/
    │   ├── kustomization.yaml
    │   ├── replica-patch.yaml
    │   └── resource-patch.yaml
    └── staging/
        ├── kustomization.yaml
        └── replica-patch.yaml

🏗️ Base 작성

kustomization.yaml

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

resources:
  - deployment.yaml
  - service.yaml
  - configmap.yaml

commonLabels:
  app: myapp
  version: v1

commonAnnotations:
  team: platform
  owner: admin

namespace: default

리소스 파일

# base/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 1
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
      - name: app
        image: myapp:latest
        ports:
        - containerPort: 8080
        resources:
          requests:
            memory: "128Mi"
            cpu: "100m"

# base/service.yaml
apiVersion: v1
kind: Service
metadata:
  name: myapp
spec:
  selector:
    app: myapp
  ports:
  - port: 80
    targetPort: 8080

🎨 Overlay 작성

Production 오버레이

# overlays/production/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../../base

namePrefix: prod-
namespace: production

commonLabels:
  env: production

patchesStrategicMerge:
  - replica-patch.yaml
  - resource-patch.yaml

images:
  - name: myapp
    newTag: v1.2.3

replicas:
  - name: myapp
    count: 5

패치 파일

# overlays/production/replica-patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 5

# overlays/production/resource-patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    spec:
      containers:
      - name: app
        resources:
          requests:
            memory: "512Mi"
            cpu: "500m"
          limits:
            memory: "1Gi"
            cpu: "1000m"

Staging 오버레이

# overlays/staging/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../../base

namePrefix: staging-
namespace: staging

commonLabels:
  env: staging

images:
  - name: myapp
    newTag: latest

replicas:
  - name: myapp
    count: 2

🔧 고급 기능

JSON Patch

# kustomization.yaml
patchesJson6902:
- target:
    group: apps
    version: v1
    kind: Deployment
    name: myapp
  path: patch.json

// patch.json
[
  {
    "op": "replace",
    "path": "/spec/replicas",
    "value": 10
  },
  {
    "op": "add",
    "path": "/spec/template/spec/nodeSelector",
    "value": {
      "disktype": "ssd"
    }
  }
]

ConfigMap/Secret 생성

# kustomization.yaml
configMapGenerator:
- name: app-config
  literals:
  - LOG_LEVEL=info
  - MAX_CONNECTIONS=100
  files:
  - config.properties

secretGenerator:
- name: app-secret
  literals:
  - DB_PASSWORD=secret123
  files:
  - tls.crt
  - tls.key

컴포넌트

# components/database/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1alpha1
kind: Component

resources:
  - deployment.yaml
  - service.yaml

patchesStrategicMerge:
  - env-patch.yaml

# overlays/production/kustomization.yaml
components:
  - ../../components/database
  - ../../components/monitoring

🚀 사용법

kubectl 통합

# kubectl에 내장 (v1.14+)
kubectl apply -k overlays/production/

# 미리보기
kubectl kustomize overlays/production/

# 출력 확인
kubectl kustomize overlays/production/ | less

독립 실행

# Kustomize 설치
curl -s "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash

# 빌드
kustomize build overlays/production/

# 빌드 후 적용
kustomize build overlays/production/ | kubectl apply -f -

# 여러 오버레이 동시 빌드
kustomize build overlays/staging/ > staging.yaml
kustomize build overlays/production/ > production.yaml

📋 체크리스트

🔗 관련 노트

03-03-Helm-패키지-관리 — 템플릿 기반 패키지 관리
03-09-GitOps-ArgoCD — GitOps 배포
01-04-Deployment-관리 — 워크로드 배포

마지막 업데이트: 2026-06-01