Kustomize를 활용한 쿠버네티스 애플리케이션 설정 관리 가이드

쿠버네티스 환경에서 애플리케이션을 배포할 때, 개발(Dev), 스테이징(Staging), 운영(Production) 환경에 따라 설정이 달라지는 것은 일반적입니다. 과거에는 YAML 파일을 복사하여 관리하거나 복잡한 Helm 템플릿을 사용해야 했습니다. Kustomize는 이러한 불편함을 해결하기 위해 등장한 '템플릿 없는' 설정 관리 도구입니다. 🛠️

 

 

---

1. Kustomize란 무엇인가?

Kustomize는 쿠버네티스 오브젝트 구성을 사용자 정의(Customize)하는 도구입니다. 2019년 쿠버네티스 1.14 버전부터 kubectl에 기본 내장되어 별도의 설치 없이 kubectl apply -k 명령어로 바로 사용할 수 있습니다.

Kustomize의 가장 큰 특징은 오버레이(Overlay) 방식입니다. 원본 YAML 파일(Base)은 그대로 두고, 환경마다 변경할 부분만 별도의 파일로 정의하여 덮어씌우는 구조를 가집니다.

---

2. 핵심 개념: Base와 Overlays

Kustomize를 이해하기 위해서는 Base와 Overlays의 관계를 파악하는 것이 중요합니다. 🏗️

• Base (기본): 모든 환경에서 공통적으로 사용하는 표준 매니페스트 세트입니다. 기본적인 Deployment, Service, ConfigMap 등이 포함됩니다.
• Overlays (오버레이): 특정 환경에 맞춰 Base를 재정의하는 레이어입니다. 예를 들어 운영 환경에서는 복제본(Replicas) 개수를 늘리거나 리소스 제한을 강화하는 설정을 추가합니다.

---

3. 표준 디렉토리 구조

Kustomize를 사용할 때는 다음과 같은 디렉토리 계층 구조를 권장합니다. 📂

.
└── deploy/
    ├── base/
    │   ├── deployment.yaml
    │   ├── service.yaml
    │   └── kustomization.yaml
    └── overlays/
        ├── dev/
        │   ├── kustomization.yaml
        │   └── patch-repl-count.yaml
        └── prod/
            ├── kustomization.yaml
            └── resource-limits.yaml

---

4. 주요 기능 및 코드 예시 💻

4.1 kustomization.yaml 구성요소

이 파일은 Kustomize의 엔진 역할을 합니다. 어떤 리소스를 포함할지, 어떤 설정을 변경할지 정의합니다.

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

resources:
  - deployment.yaml
  - service.yaml

4.2 patches (패치 적용)

특정 필드만 수정하고 싶을 때 사용합니다. 예를 들어 운영 환경에서만 replicas 수를 5개로 늘리는 경우입니다.

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

resources:
  - ../../base

patches:
  - target:
      kind: Deployment
      name: my-app
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 5

4.3 Generators (생성기)

파일이나 환경 변수 목록으로부터 ConfigMap과 Secret을 자동으로 생성합니다. 파일 내용이 변경되면 해시값이 자동으로 업데이트되어 파드의 롤링 업데이트를 유도합니다. 🔄

# kustomization.yaml
configMapGenerator:
  - name: app-config
    files:
      - config.properties
secretGenerator:
  - name: db-secret
    envs:
      - .env.db

4.4 Transformers (변환기)

모든 리소스에 공통적인 속성을 일괄 적용합니다.

• namePrefix / nameSuffix: 리소스 이름 앞뒤에 문자열 추가
• commonLabels: 모든 리소스에 레이블 부여
• commonAnnotations: 모든 리소스에 주석 부여
• namespace: 모든 리소스의 네임스페이스 지정

---

5. Kustomize의 장단점 📊

구분	장점	단점
가독성	순수 YAML 형식을 유지하여 읽기 쉬움	복잡한 조건문(if-else) 처리가 불가능함
학습 곡선	템플릿 문법(Go template) 학습 불필요	디렉토리 구조가 복잡해지면 추적이 어려움
통합성	kubectl에 내장되어 별도 도구 불필요	환경 간 차이가 극심할 경우 중복 코드 발생 가능
운영	GitOps(ArgoCD 등)와 호환성이 탁월함	단순 값 치환 외에 동적인 로직 구현이 어려움

---

6. 실행 방법

설정이 완료되었다면 다음 명령어를 통해 최종적으로 렌더링된 YAML을 확인하거나 바로 배포할 수 있습니다.

# 렌더링 결과 확인 (Dry-run)
kubectl kustomize ./overlays/prod

# 실제 클러스터에 배포
kubectl apply -k ./overlays/prod

 

Kustomize는 설정의 재사용성을 높이고 환경별 차이를 명확하게 관리할 수 있게 해주는 강력한 도구입니다. 특히 템플릿의 복잡성 없이 인프라를 코드로 관리(IaC)하고자 하는 팀에게 최적의 선택지입니다. 🚀