김신건의 로그
📁 kubernetes

[Kubernetes] Kustomize

· 수정 · 📖 약 2분 · 635자/단어 #kubernetes #kustomize #config #gitops
Kustomize, kubectl kustomize, kustomization.yaml, kustomize base overlay, kustomize patch, 쿠버네티스 kustomize

정의

Kustomize 는 Kubernetes manifests 를 템플릿 없이 overlay 방식으로 커스터마이제이션하는 도구입니다. kubectl v1.14+ 에 내장 (kubectl apply -k). YAML 을 그대로 두고, base + overlay 로 환경별 (dev/stg/prod) 차이만 표현합니다.

왜 Kustomize 인가

Helm 과 대비

Helm 은 템플릿 엔진 (Go template). YAML 에 {{ .Values.replicas }} 같은 placeholder.

단점:

  • YAML 이 진짜 YAML 이 아님 (템플릿 언어 삽입)
  • 파싱 오류 디버깅 힘듦
  • Values.yaml 이 실질적으로 스키마 없는 dict

Kustomize 는 순수 YAML. Patch/overlay 로 조합.

단점:

  • 로직 (조건, 반복) 표현 어려움
  • 복잡한 시나리오에 부담
  • Helm 만큼 배포자 (user) 친화적이지 않음

결론:

  • 자체 앱, 환경별 배포 -> Kustomize 자연스러움
  • 외부 배포 대상 라이브러리 (Redis, Postgres, Prometheus) -> Helm 우세
  • 조합 가능 (Helm chart 를 Kustomize 로 후처리)

기본 구조

kustomize-project/
├── base/
│   ├── kustomization.yaml
│   ├── deployment.yaml
│   ├── service.yaml
│   └── configmap.yaml
└── overlays/
    ├── dev/
    │   ├── kustomization.yaml
    │   ├── replica-patch.yaml
    │   └── env-patch.yaml
    ├── staging/
    │   ├── kustomization.yaml
    │   └── replica-patch.yaml
    └── prod/
        ├── kustomization.yaml
        ├── replica-patch.yaml
        └── resources-patch.yaml

Base

Base 는 공통 리소스.

base/kustomization.yaml:

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

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

commonLabels:
  app: web
  managed-by: kustomize

commonAnnotations:
  team: platform

base/deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 1
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: web
          image: myapp:1.0
          ports:
            - containerPort: 8080
          env:
            - name: APP_ENV
              value: development
          resources:
            requests:
              cpu: 100m
              memory: 128Mi

Overlay

overlays/prod/kustomization.yaml:

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

namespace: prod                    # 모든 리소스가 prod namespace 에

resources:
  - ../../base                     # base 참조

commonLabels:
  environment: production

patches:
  - path: replica-patch.yaml
  - path: resources-patch.yaml
    target:
      kind: Deployment

images:
  - name: myapp
    newTag: 1.5.0                  # image tag 교체

configMapGenerator:
  - name: app-config
    behavior: merge
    literals:
      - APP_ENV=production
      - LOG_LEVEL=info

secretGenerator:
  - name: db-secret
    literals:
      - password=prod-secret-value

replicas:
  - name: web
    count: 5

Patch 종류

1. Strategic Merge Patch (기본)

YAML 조각을 base 위에 얹음. K8s API 지식 활용.

replica-patch.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 5

Deployment.spec.replicas 만 5 로 override.

2. JSON Patch (RFC 6902)

경로 기반 수정. 세밀 제어.

patches:
  - target:
      kind: Deployment
      name: web
    patch: |
      - op: replace
        path: /spec/replicas
        value: 5
      - op: add
        path: /spec/template/spec/containers/0/env/-
        value:
          name: FEATURE_FLAG
          value: "true"
      - op: remove
        path: /spec/template/spec/containers/0/env/0

3. Container 수준 patch

patches:
  - target:
      kind: Deployment
      name: web
    patch: |
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: web
      spec:
        template:
          spec:
            containers:
              - name: web
                resources:
                  requests:
                    cpu: 500m
                    memory: 512Mi
                  limits:
                    cpu: 2
                    memory: 2Gi

Generator

ConfigMap

configMapGenerator:
  - name: app-config
    literals:
      - APP_ENV=production
      - LOG_LEVEL=info
    files:
      - config.json
      - nginx.conf
    envs:
      - .env.prod

생성된 ConfigMap 이름에 hash suffix 자동 추가 (app-config-abc123). 값 변경 시 새 hash -> Pod 자동 재배포.

Secret

secretGenerator:
  - name: db-secret
    literals:
      - username=admin
      - password=secret
    type: Opaque

주의: literals 는 kustomization.yaml 안에 평문. Git 에 커밋 금지. Sealed Secrets, SOPS, external secrets 로 대체.

Image 변경

images:
  - name: myapp                  # base 의 이미지 이름
    newName: registry.example.com/myapp
    newTag: 1.5.0
  - name: nginx
    newName: nginx
    digest: sha256:abc...

컨테이너 spec 을 손대지 않고 tag/registry 만 override.

Namespace 지정

namespace: prod

Overlay 안 모든 namespaced 리소스가 이 namespace 로.

Name Prefix / Suffix

namePrefix: prod-
nameSuffix: -v2

web -> prod-web-v2.

Component (v3.7+)

재사용 가능한 조합. 라이브러리 성격.

components/monitoring/kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1alpha1
kind: Component

patches:
  - target:
      kind: Deployment
    patch: |
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: dummy
      spec:
        template:
          metadata:
            annotations:
              prometheus.io/scrape: "true"
              prometheus.io/port: "9090"

Overlay 에서 사용:

components:
  - ../../components/monitoring

여러 base

resources:
  - ../base/deployment
  - ../base/service
  - ../base/configmap

# 또는
bases:                       # deprecated in favor of resources
  - ../base

빌드 & 적용

# 렌더링만 (확인용)
kubectl kustomize overlays/prod/
kustomize build overlays/prod/

# 적용
kubectl apply -k overlays/prod/

# Diff
kubectl diff -k overlays/prod/

# 삭제
kubectl delete -k overlays/prod/

실전 워크플로

앱 배포

myapp/
├── base/
│   ├── kustomization.yaml
│   ├── deployment.yaml
│   ├── service.yaml
│   └── ingress.yaml
└── overlays/
    ├── dev/
    │   └── kustomization.yaml     # dev namespace, small resources
    ├── staging/
    │   └── kustomization.yaml     # stg namespace, prod-like
    └── prod/
        ├── kustomization.yaml
        ├── hpa.yaml                # prod 만 HPA
        └── pdb.yaml

Multi-cluster

myapp/
├── base/
└── overlays/
    ├── us-east-1/
    │   ├── prod/
    │   ├── staging/
    └── eu-west-1/
        ├── prod/
        └── staging/

Helm chart post-processing

Helm chart 를 base 로:

helmCharts:
  - name: nginx-ingress
    repo: https://kubernetes.github.io/ingress-nginx
    version: 4.11.0
    releaseName: ingress-nginx
    namespace: ingress-nginx
    valuesInline:
      controller:
        replicaCount: 3

patches:
  - patch: |
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: ingress-nginx-controller
      spec:
        template:
          spec:
            nodeSelector:
              node-role: ingress

Kustomize + GitOps

  • ArgoCD: Native Kustomize 지원. Application 리소스에 kustomize path 지정.
  • Flux: Kustomization CRD (Flux 의 K CRD 는 kustomize 를 wrap).

함정

WARNING

Secret literal 을 git 에 커밋 금지. Sealed Secrets, SOPS, ExternalSecrets 로.

CAUTION

Generator hash 는 값 기반. 같은 값 = 같은 hash = 같은 이름. Rolling update 유발하려면 값 실제 변경.

WARNING

overlay 에서 base 리소스 순서. 여러 base 상속 시 순서에 따라 patch 결과 달라짐.

IMPORTANT

kubectl kustomize 로 렌더링 후 확인. 예상과 다르면 patch 로직 재검토.

CAUTION

JSON Patch path 오타. /spec/template/spec/containers/0/name 등 인덱스 실수 흔함. 정확 지정.

관련 위키

이 글의 용어 (7개)
[GitOps] 패턴: 단일 vs 다중 repo, environment promotiondevops
정의 GitOps = Git 을 single source of truth 로 삼아 자동으로 인프라 + 앱 상태를 reconcile 하는 운영 방식. GitOps 4가지 원칙 (O…
[GitOps] ArgoCD: Kubernetes GitOpsdevops
정의 ArgoCD = Kubernetes 의 GitOps 컨트롤러. Git 리포지토리의 manifest 가 source of truth → cluster 가 자동 동기화. Git…
[K8s] ConfigMap & Secret: 설정과 비밀의 분리kubernetes
정의 ConfigMap 과 Secret 은 컨테이너 이미지에서 설정/비밀 값을 분리하기 위한 Kubernetes 리소스. | 항목 | ConfigMap | Secret | |:-…
[Kubernetes] Namespacekubernetes
정의 Namespace 는 같은 물리 클러스터 안에서 리소스 (Pod, Service, ConfigMap 등) 를 논리적으로 격리 하는 단위입니다. 이름 충돌 회피, RBAC 스…
[LLM Eval] HELM: Holistic Evaluation of Language Modelsai
정의 HELM (Holistic Evaluation of Language Models) 는 Stanford CRFM (Center for Research on Foundation…
kubectlkubernetes
정의 kubectl 은 Kubernetes API 를 명령줄에서 조작하는 공식 CLI 입니다. kube-apiserver 와 통신해 리소스를 조회, 생성, 수정, 삭제하고, 로그…
Kuberneteskubernetes
정의 Kubernetes (k8s) 는 컨테이너화된 애플리케이션의 배포, 스케일링, 관리 를 자동화하는 오픈소스 오케스트레이터입니다. Google 이 2014년 발표하고 2015…

이 개념을 다룬 위키 페이지 (3)

💬 댓글

사이트 검색 / 명령어

검색

스크롤 = 확대/축소 · 드래그 = 이동 · 0 = 원래 크기 · ESC = 닫기