1. Kustomize란?

Container Orchestration/Kubernetes

1. Kustomize란?

Somaz 2023. 10. 12. 21:06

728x90

Overview

오늘은 Kubernetes 환경에서 매니페스트를 보다 구조적이고 유연하게 관리할 수 있는 도구인 Kustomize에 대해 알아겠다.

기존에는 여러 환경(dev, qa, prod 등)에 맞춰 매니페스트를 복사하거나 수작업으로 관리하는 경우가 많았지만,
Kustomize는 중복을 줄이고, 환경별 패치만 분리하여 구성할 수 있게 해주는 강력한 솔루션이다.

특히 base와 overlay 개념을 활용해 공통 설정은 재사용하고, 변경이 필요한 값만 덮어쓸 수 있어
팀 단위의 운영환경 관리나 GitOps 환경 구성 시 매우 유용하다.

오늘 실습에서는 nginx 예제를 중심으로 Kustomize의 기본 구조, kustomization.yaml의 역할,
환경별 빌드 및 배포 방식 등을 직접 다뤄보며 핵심 흐름을 익혀봤다.

Kustomize란?

Kustomize는 쿠버네티스 매니페스트를 커스터마이징하는 도구이다. 기본 매니페스트에 수정 및 변형을 적용하는데 초점을 맞춘다.

Kustomize 설치

다른 설치 방법은 해당 링크에서 확인하면 된다.

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

sudo mv kustomize /usr/local/bin/

Kustomize 기본요소

1. 베이스(base) 및 오버레이(overlay)

Kustomize는 기본적으로 베이스와 오버레이라는 아이디어를 기반으로 작동한다. 베이스에는 기본 리소스에 대해서 정의하고 오버레이는 해당 리소스를 바탕으로 환경별로 적용할 패치 내용을 적용한다.

├── base
│   ├── kustomization.yaml
│   ├── nginx-deployment.yaml
│   ├── nginx-ingress.yaml
│   └── nginx-service.yaml
└── overlays
    ├── dev
    │   ├── ingress.yaml
    │   ├── kustomization.yaml
    │   └── replica-count.yaml
    ├── prod
    │   ├── ingress.yaml
    │   ├── kustomization.yaml
    │   └── replica-count.yaml
    └── qa
        ├── ingress.yaml
        ├── kustomization.yaml
        └── replica-count.yaml

2. `kustomization.yaml`

Kustomize가 어떤 수정 사항을 적용할지에 대해서 정의하는 파일이다. 해당 파일에는 리소스, 적용할 패치 및 기타 구성에 대한 정보가 포함 될 수 있다.

`base/kustomization.yaml`

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - nginx-deployment.yaml
  - nginx-service.yaml
  - nginx-ingress.yaml

`overlays/dev/kustomization.yaml`

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
patches:
  - path: replica-count.yaml
    target:
      kind: Deployment
      name: nginx-deployment
  - path: ingress.yaml 
    target:
      kind: Ingress
      name: nginx-ingress
namePrefix: dev-
namespace: dev-nginx

patchesStrategicMerge vs patchesJson6902 비교

Kustomize에서는 리소스를 수정할 때 patches 키 아래에 패치를 정의하는데, 이때 사용하는 방식에는 크게 두 가지가 있다:
patchesStrategicMerge와 patchesJson6902다.

1. patchesStrategicMerge

기존 리소스 YAML 일부를 덮어쓰는 방식
사람이 읽고 쓰기 쉬운 일반 YAML 형식
리소스의 kind, name 등을 기준으로 병합
가장 일반적인 패치 방식이며, Deployment, Service, Ingress 등에서 주로 사용됨

patchesStrategicMerge:
  - replica-count.yaml

`replica-count.yaml` 예시

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

2. patchesJson6902

RFC 6902 표준 JSON Patch 포맷 사용
복잡한 구조(예: 배열 항목 수정)에서 유용
target을 명시해 리소스를 정확히 지정해야 함

patchesJson6902:
  - target:
      group: apps
      version: v1
      kind: Deployment
      name: nginx-deployment
    path: patch-replicas.json

`patch-replicas.json` 예시

[
  {
    "op": "replace",
    "path": "/spec/replicas",
    "value": 2
  }
]

Kustomize 실습

자세한 내용은 아래의 Github를 참조하면 된다. `basic-nginx-deployment`를 실습해볼 예정이다.

https://github.com/somaz94/kustomize-study

GitHub - somaz94/kustomize-study: kustomize-study

kustomize-study. Contribute to somaz94/kustomize-study development by creating an account on GitHub.

github.com

basic-nignx-deployment

간단하게 kustomize를 사용해 nginx를 배포할 것이다. 환경은 `dev, qa, prod`이다.

디렉토리 구조

`base` : 기본 리소스가 정의된 디렉터리이다.
`overlays` : 특정 환경에 맞게 조정된 리소스 구성이 포함된 디렉터리이다. 각 환경`(dev, qa, prod)` 에 대한 리소스 변형을 정의한다.
`mainfests` : `overlays`에 `kustomize build` 명령을 적용한 결과인 쿠버네티스 매니페스트 파일이다. 해당 파일은 Kustomize 처리없이 바로 쿠버네티스 클러스터에 직접 적용될 수 있다.

.
├── README.md
├── base
│   ├── kustomization.yaml
│   ├── nginx-deployment.yaml
│   ├── nginx-ingress.yaml
│   └── nginx-service.yaml
├── manifests
│   ├── dev-nginx.yaml
│   ├── prod-nginx.yaml
│   └── qa-nginx.yaml
└── overlays
    ├── dev
    │   ├── ingress.yaml
    │   ├── kustomization.yaml
    │   └── replica-count.yaml
    ├── prod
    │   ├── ingress.yaml
    │   ├── kustomization.yaml
    │   └── replica-count.yaml
    └── qa
        ├── ingress.yaml
        ├── kustomization.yaml
        └── replica-count.yaml

6 directories, 17 files

Kustomize 리소스 빌드

# Generate manifests for the dev environment
kustomize build overlays/dev

# Generate manifests for the qa environment
kustomize build overlays/qa

# Generate manifests for the prod environment
kustomize build overlays/prod

Kustomize 매니페스트 저장 방법

kustomize build overlays/dev > manifests/dev-nginx.yaml
kustomize build overlays/qa > manifests/qa-nginx.yaml
kustomize build overlays/prod > manifests/prod-nginx.yaml

Kustomize 빌드 후 배포

kustomize build overlays/dev | kubectl apply -f - --namespace=dev-nginx
kustomize build overlays/qa | kubectl apply -f - --namespace=qa-nginx
kustomize build overlays/prod | kubectl apply -f - --namespace=prod-nginx

or

kubectl apply -k overlays/dev/
kubectl apply -k overlays/qa/
kubectl apply -k overlays/prod/

배포 후 리소스 확인 및 테스트

간단하게 `dev` 환경에 대해서만 배포 후 확인해본다.

kubectl get po,svc,ingress -n dev-nginx
NAME                                       READY   STATUS    RESTARTS   AGE
pod/dev-nginx-deployment-8d545c96d-48rqx   1/1     Running   0          2m37s

NAME                        TYPE        CLUSTER-IP    EXTERNAL-IP   PORT(S)   AGE
service/dev-nginx-service   ClusterIP   10.233.6.66   <none>        80/TCP    2m37s

NAME                                          CLASS    HOSTS                        ADDRESS        PORTS   AGE
ingress.networking.k8s.io/dev-nginx-ingress   <none>   dev-nginx.somaz.link   10.10.100.22   80      2m37s

`Curl` 명령어를 사용해서 요청을 보낼 수 있다.

curl 10.233.6.66

or

curl dev-nginx.somaz.link

<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
<style>
html { color-scheme: light dark; }
body { width: 35em; margin: 0 auto;
font-family: Tahoma, Verdana, Arial, sans-serif; }
...

테스트 후 리소스를 정리한다.

kubectl delete -k overlays/dev

kustomize edit 명령어

Kustomize는 수동으로 `kustomization.yaml` 파일을 수정할 수도 있지만, CLI로 자동화할 수 있는 명령어들도 제공한다.

예를 들어 아래와 같이 사용할 수 있다.

kustomize edit add resource deployment.yaml
kustomize edit add patch --path=patch.yaml --target-name=nginx-deployment
kustomize edit set nameprefix dev-

이 명령어들은 현재 디렉토리에 있는 `kustomization.yaml` 을 자동으로 수정하며, CI 파이프라인에서 동적으로 관리하거나,
초기 세팅을 빠르게 할 때 매우 유용하다.

ConfigMapGenerator / SecretGenerator 실습

Kustomize는 kustomization.yaml 안에서 ConfigMap과 Secret을 동적으로 생성할 수 있는 기능도 제공한다.

이는 환경별 구성 파일이나 API 키 등을 코드로 관리할 때 매우 유용하다.

1. ConfigMapGenerator 예시

configMapGenerator:
  - name: app-config
    literals:
      - ENV=dev
      - DEBUG=true

`kubectl apply -k` 혹은 `kustomize build` 를 실행하면 `app-config` 라는 이름의 ConfigMap이 생성된다.

2. SecretGenerator 예시

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

⚠️ 주의: Kustomize는 Secret도 plain-text로 생성하므로 Git에 올릴 때는 주의가 필요하다.
보안을 강화하고 싶다면 Sealed Secrets 또는 SOPS와 병행하는 방식도 고려할 수 있다.

Helm과 Kustomize, 언제 어떤 걸 써야 할까?

항목	Helm	Kustomize
목적	패키징 및 배포 자동화	YAML 리소스의 구조적 커스터마이징
배포 단위	Chart (릴리스 중심)	디렉토리 기반 리소스 구성
템플릿 문법	Go 템플릿	순수 YAML + patch 전략
값 주입 방식	values.yaml	overlay + patch
GitOps 연동	ArgoCD, FluxCD 등에서 잘 지원	동일하게 지원, 별도 values 관리 필요
사용 난이도	초반 진입장벽 낮음	구조 이해까지는 다소 시간 필요

결론

Helm: 여러 팀이 사용하는 오픈소스 차트를 쉽게 재활용하거나, Chart Repository를 통해 배포할 때
Kustomize: 조직 내 YAML 스타일과 환경 관리가 중요하고 GitOps를 철저히 적용할 때

실제로는 Helm 차트를 Kustomize로 감싸서 사용하는 하이브리드 방식도 자주 활용된다.

ArgoCD와 Kustomize 통합

ArgoCD는 GitOps 방식으로 쿠버네티스 애플리케이션을 관리하는 도구로, Kustomize와의 통합을 공식적으로 지원한다.

예를 들어, 아래와 같은 Application CRD에서 source.kustomize 블록을 통해 Kustomize 옵션을 지정할 수 있다:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: nginx-app
spec:
  source:
    repoURL: https://github.com/somaz94/kustomize-study.git
    path: overlays/dev
    targetRevision: HEAD
    kustomize:
      namePrefix: dev-
  destination:
    server: https://kubernetes.default.svc
    namespace: dev-nginx
  project: default

이처럼 Git 저장소에 있는 Kustomize overlay 디렉토리를 기준으로 ArgoCD가 매니페스트를 자동으로 관리할 수 있다.
GitOps 기반 워크플로우에선 Helm이나 Kustomize 중 팀의 운영 방식에 따라 선택하면 된다.

마무리: "매니페스트 재사용성과 유지보수성을 높이는 Kustomize"

Kustomize는 단순한 설정 템플릿 도구를 넘어, Kubernetes 매니페스트 관리 방식 자체를 구조화하는 접근을 제공한다.
환경별 YAML 파일을 일일이 복사하지 않고, 공통 리소스(base)에 필요한 설정만 overlay로 덧붙이는 방식은
지속 가능한 인프라 운영의 첫걸음이다.

또한 `kubectl apply -k` 와 같은 명령어를 통해 Kustomize는 쿠버네티스 기본 도구들과도 자연스럽게 통합되며,
GitOps 도구(ArgoCD, FluxCD)와 함께 사용할 때도 뛰어난 확장성과 호환성을 제공한다.

단순하게 nginx 실습으로 시작했지만, 실제 실무에서는 수십 개 이상의 매니페스트를 다루기 때문에
Kustomize의 구조적인 접근 방식은 장기적으로 배포 효율성과 가독성, 유지보수성까지 크게 향상시켜준다.

Reference

Kustomize 공식 사이트: https://kustomize.io
Kubernetes 공식 문서 - Kustomize 소개: https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/
Kustomize GitHub 저장소 (소스 코드 및 업데이트 참고): https://github.com/kubernetes-sigs/kustomize
JSON Patch (RFC 6902) 명세: https://datatracker.ietf.org/doc/html/rfc6902
ConfigMapGenerator & SecretGenerator 공식 문서: https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/configmapgenerator/
ArgoCD에서 Kustomize 사용하는 법 (공식 문서): https://argo-cd.readthedocs.io/en/stable/user-guide/kustomize/
Kustomize vs Helm 비교 블로그: https://blog.argoproj.io/kustomize-vs-helm-what-you-need-to-know-2d5d4c7bda31
GitHub 실습 코드 저장소: https://github.com/somaz94/kustomize-study

728x90

'Container Orchestration > Kubernetes' 카테고리의 다른 글

Flux란? / Flux + Kustomize (2)	2023.10.16
2. Kustomize + ArgoCD ApplicationSet (2)	2023.10.14
CertManager로 Let's Encrypt 인증서 발급 (2)	2023.10.03
Kubernetes Autoscaling & Karpenter (0)	2023.05.24
Helm Chart 작성방법 (0)	2023.05.18

현재글1. Kustomize란?

Somaz의 IT 공부 일지

1. Kustomize란?

Overview

Kustomize란?

Kustomize 설치

Kustomize 기본요소

1. 베이스(base) 및 오버레이(overlay)

2. `kustomization.yaml`

patchesStrategicMerge vs patchesJson6902 비교

1. patchesStrategicMerge

2. patchesJson6902

Kustomize 실습

basic-nignx-deployment

디렉토리 구조

kustomize edit 명령어

ConfigMapGenerator / SecretGenerator 실습

1. ConfigMapGenerator 예시

2. SecretGenerator 예시

Helm과 Kustomize, 언제 어떤 걸 써야 할까?

결론

ArgoCD와 Kustomize 통합

마무리: "매니페스트 재사용성과 유지보수성을 높이는 Kustomize"

Reference

'Container Orchestration > Kubernetes' 카테고리의 다른 글

'Container Orchestration/Kubernetes'의 다른글

티스토리툴바

1. Kustomize란?

Overview

Kustomize란?

Kustomize 설치

Kustomize 기본요소

1. 베이스(base) 및 오버레이(overlay)

2. `kustomization.yaml`

patchesStrategicMerge vs patchesJson6902 비교

1. patchesStrategicMerge

2. patchesJson6902

Kustomize 실습

basic-nignx-deployment

디렉토리 구조

kustomize edit 명령어

ConfigMapGenerator / SecretGenerator 실습

1. ConfigMapGenerator 예시

2. SecretGenerator 예시

Helm과 Kustomize, 언제 어떤 걸 써야 할까?

결론

ArgoCD와 Kustomize 통합

마무리: "매니페스트 재사용성과 유지보수성을 높이는 Kustomize"

Reference

'Container Orchestration > Kubernetes' 카테고리의 다른 글

'Container Orchestration/Kubernetes'의 다른글

관련글

티스토리툴바