Kustomize 완벽 이해

1. Kustomize란 무엇인가? (오버레이 방식, Declarative Configuration Management)#

쿠버네티스 애플리케이션 관리를 위한 또 다른 핵심 도구인 Kustomize는 쿠버네티스 리소스 설정을 오버레이(Overlay) 방식으로 관리하는 Declarative Configuration Management 도구입니다. Kustomize를 사용하면 기존의 쿠버네티스 매니페스트 파일을 수정하지 않고도 환경에 따라 설정을 커스터마이징할 수 있습니다.

1.1 Kustomize: Declarative Configuration Management#

Kustomize는 선언적(Declarative) 방식으로 쿠버네티스 리소스 설정을 관리합니다. 즉, 사용자는 원하는 최종 상태(desired state)를 선언하고, Kustomize는 이를 자동으로 구성합니다. Kustomize는 다음과 같은 특징을 가집니다.

  • 매니페스트 파일 수정 최소화: Kustomize는 기존의 쿠버네티스 매니페스트 파일을 직접 수정하지 않고 설정을 커스터마이징할 수 있습니다. 이는 애플리케이션 코드를 변경하지 않고 설정을 변경할 수 있음을 의미합니다.
  • 환경별 설정 관리 용이: Kustomize는 오버레이(Overlay) 방식을 사용하여 개발, 스테이징, 프로덕션 등 여러 환경에 대한 설정을 쉽게 관리할 수 있도록 돕습니다.
  • 쿠버네티스 내장: Kustomize는 kubectl에 내장되어 있어 별도의 설치 없이 사용할 수 있습니다(kubectl apply -k .).
  • Kustomization 파일: Kustomize는 kustomization.yaml 또는 kustomization.yml 파일을 사용하여 설정을 관리합니다. 이 파일에는 커스터마이징할 리소스 파일, 적용할 변경 사항 등이 정의됩니다.

1.2 오버레이 (Overlay) 방식#

Kustomize는 오버레이(Overlay) 방식을 사용하여 설정을 커스터마이징합니다. 오버레이 방식은 기본 설정 파일(Base) 위에 변경 사항(Overlay)을 덮어씌워 최종 설정 파일을 생성하는 방식입니다.

  • Base: 기본 매니페스트 파일들의 집합입니다. Base는 환경에 관계없이 공통적으로 적용되는 설정을 정의합니다.
  • Overlay: Base 매니페스트 파일들을 변경하는 설정 파일입니다. Overlay는 환경에 따라 달라지는 설정을 정의합니다.
  • Kustomization: Base와 Overlay를 결합하여 최종 매니페스트 파일을 생성하는 설정 파일입니다. kustomization.yaml 파일은 Kustomize의 핵심 구성 요소이며, Base와 Overlay를 지정하고, 적용할 변경 사항을 정의합니다.

오버레이 방식 예시:

+-----------------+     +-----------------+     +-----------------+
|      Base       |  +  |     Overlay     |  =  |   Final Result  |
| (common settings)|  +  | (env-specific)  |  =  | (customized)    |
+-----------------+     +-----------------+     +-----------------+

오버레이 방식 장점:

  • 코드 재사용성: Base 매니페스트 파일을 재사용하여 코드 중복을 줄일 수 있습니다.
  • 설정 관리 용이성: Overlay를 사용하여 환경별 설정을 분리하여 관리할 수 있습니다.
  • 유지보수성 향상: Base 매니페스트 파일을 수정하지 않고 Overlay를 통해 설정을 변경하므로, 유지보수가 용이합니다.

1.3 Kustomization 파일 (kustomization.yaml)#

kustomization.yaml 파일은 Kustomize의 핵심 구성 요소이며, 다음과 같은 정보를 포함합니다.

  • resources: Base 매니페스트 파일 목록을 지정합니다.
  • patches: Base 매니페스트 파일에 적용할 변경 사항을 정의합니다.
    • patchesStrategicMerge: 기존 리소스의 설정을 병합하는 방식
    • patchesJson6902: JSON Patch 형식을 사용하여 설정을 변경하는 방식
  • namePrefix/nameSuffix: 리소스 이름에 접두사/접미사를 추가합니다.
  • namespace: 리소스의 네임스페이스를 변경합니다.
  • commonLabels: 모든 리소스에 공통 레이블을 추가합니다.
  • images: 컨테이너 이미지 태그를 변경합니다.
  • vars: 변수를 정의하고, 템플릿에서 사용할 수 있도록 합니다.
  • configurations: Kustomize 설정을 위한 파일 목록을 지정합니다.

kustomization.yaml 예시:

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

resources:
  - deployment.yaml  # Base Deployment
  - service.yaml     # Base Service

patchesStrategicMerge:
  - deployment-patch.yaml  # Deployment에 적용할 변경 사항

namePrefix: dev-  # 리소스 이름에 접두사 추가

namespace: development  # 네임스페이스 변경

commonLabels:
  environment: development  # 공통 레이블 추가

images:
  - name: my-app  # 이미지 이름
    newName: my-app  # 새로운 이미지 이름
    newTag: 1.0.1  # 새로운 이미지 태그

1.4 Kustomize 워크플로우#

  • Base 매니페스트 파일 준비: 공통 설정을 정의하는 Base 매니페스트 파일을 준비합니다.
  • Overlay 디렉토리 생성: 각 환경에 대한 Overlay 디렉토리를 생성합니다(예: overlays/dev, overlays/prod).
  • kustomization.yaml 파일 작성: 각 Overlay 디렉토리에 kustomization.yaml 파일을 작성하여 Base 매니페스트 파일과 적용할 변경 사항을 정의합니다.

Kustomize 빌드: kubectl apply -k 명령어를 실행하여 최종 매니페스트 파일을 생성하고 쿠버네티스에 적용합니다.

2. Kustomize 설치 및 사용법 (kubectl apply -k)#

Kustomize는 별도의 설치 과정 없이 kubectl에 내장되어 있어 매우 편리하게 사용할 수 있습니다. 이 섹션에서는 Kustomize를 사용하는 데 필요한 요구 사항과 기본적인 사용법, 그리고 핵심 명령어인 kubectl apply -k에 대해 자세히 알아보겠습니다.

2.1 Kustomize 요구 사항#

Kustomize는 kubectl 1.14 버전 이상부터 내장되어 있습니다. 따라서 Kustomize를 사용하려면 다음 요구 사항을 충족해야 합니다.

  • kubectl 버전 확인: kubectl version 명령어를 실행하여 kubectl 버전을 확인합니다.
kubectl version --client

클라이언트 버전이 1.14 이상인지 확인합니다.

  • 최신 kubectl 설치: kubectl 버전이 1.14 미만인 경우, 최신 버전의 kubectl을 설치합니다. kubectl 설치 방법은 쿠버네티스 공식 웹사이트(https://kubernetes.io/docs/tasks/tools/)에서 확인할 수 있습니다.

2.2 Kustomize 기본 사용법#

Kustomize는 kustomization.yaml 파일을 사용하여 설정을 관리합니다. Kustomize를 사용하는 기본적인 단계는 다음과 같습니다.

  • Base 매니페스트 파일 준비: 공통 설정을 정의하는 Base 매니페스트 파일을 준비합니다.
  • Overlay 디렉토리 생성: 각 환경에 대한 Overlay 디렉토리를 생성합니다 (예: overlays/dev, overlays/prod).
  • kustomization.yaml 파일 작성: 각 Overlay 디렉토리에 kustomization.yaml 파일을 작성하여 Base 매니페스트 파일과 적용할 변경 사항을 정의합니다.

Kustomize 빌드 및 적용: kubectl apply -k 명령어를 실행하여 최종 매니페스트 파일을 생성하고 쿠버네티스에 적용합니다.

예시:

다음과 같은 디렉토리 구조를 가진다고 가정합니다.

my-app/
├── base/
│   ├── deployment.yaml  # Base Deployment
│   └── service.yaml     # Base Service
└── overlays/
    └── dev/
        └── kustomization.yaml  # 개발 환경 Overlay

base/deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: my-app-container
        image: my-app:latest
        ports:
        - containerPort: 80

base/service.yaml:

apiVersion: v1
kind: Service
metadata:
  name: my-app-service
spec:
  selector:
    app: my-app
  ports:
  - protocol: TCP
    port: 80
    targetPort: 80
  type: ClusterIP

overlays/dev/kustomization.yaml:

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

resources:
  - ../../base

namespace: development  # 네임스페이스 변경

namePrefix: dev-  # 리소스 이름에 접두사 추가

images:
  - name: my-app
    newName: my-app
    newTag: 1.0.0  # 이미지 태그 변경

위 설정은 Base 매니페스트 파일(base/deployment.yaml, base/service.yaml)을 사용하여 개발 환경(overlays/dev)에 애플리케이션을 배포하고, 다음과 같은 변경 사항을 적용합니다.

  • 네임스페이스: development
  • 리소스 이름 접두사: dev-
  • 이미지 태그: 1.0.0

2.3 kubectl apply -k 명령어#

kubectl apply -k 명령어는 Kustomize를 사용하여 최종 매니페스트 파일을 생성하고 쿠버네티스에 적용합니다.

: kustomization.yaml 파일이 있는 디렉토리를 지정합니다.

예시:

kubectl apply -k overlays/dev  # 개발 환경에 배포

kubectl apply -k 명령어는 다음과 같은 작업을 수행합니다.

  • 지정된 디렉토리에서 kustomization.yaml 파일을 찾습니다.
  • kustomization.yaml 파일에 정의된 Base 매니페스트 파일과 Overlay 설정을 병합합니다.
  • 최종 매니페스트 파일을 생성합니다.
  • 쿠버네티스 API 서버와 통신하여 리소스를 생성하거나 업데이트합니다.

2.4 Kustomize 명령어 활용#

  • kubectl kustomize: Kustomize 빌드 결과를 미리 확인합니다. 실제로 클러스터에 적용하지 않고, 최종 매니페스트 파일을 출력합니다.
kubectl kustomize overlays/dev
  • kubectl create kustomization: 현재 디렉토리에 기본적인 kustomization.yaml 파일을 생성합니다.
kubectl create kustomization

2.5 Kustomize 장점#

  • 기존 매니페스트 파일 수정 최소화: Kustomize는 기존 매니페스트 파일을 직접 수정하지 않고 설정을 커스터마이징할 수 있습니다.
  • 환경별 설정 관리 용이: Kustomize는 오버레이(Overlay) 방식을 사용하여 개발, 스테이징, 프로덕션 등 여러 환경에 대한 설정을 쉽게 관리할 수 있도록 돕습니다.
  • 쿠버네티스 내장: Kustomize는 kubectl에 내장되어 있어 별도의 설치 없이 사용할 수 있습니다.
  • 선언적 구성: Kustomize는 선언적(Declarative) 방식으로 쿠버네티스 리소스 설정을 관리합니다.

3. kustomization.yaml 파일 구조 분석#

kustomization.yaml 파일은 Kustomize의 핵심 설정 파일로서, 쿠버네티스 리소스 커스터마이징 방법을 정의합니다. 이 섹션에서는 kustomization.yaml 파일의 주요 구성 요소인 bases, patches, resources, namePrefix, nameSuffix, commonLabels, commonAnnotations에 대해 자세히 분석합니다.

3.1 apiVersion, kind#

모든 쿠버네티스 리소스와 마찬가지로 kustomization.yaml 파일도 apiVersion과 kind를 명시해야 합니다.

  • apiVersion: Kustomize 설정 파일의 API 버전을 지정합니다. 일반적으로 kustomize.config.k8s.io/v1beta1을 사용합니다.
  • kind: 리소스 종류를 지정합니다. Kustomize 설정 파일의 경우 Kustomization을 사용합니다.

예시:

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

3.2 resources#

resources 필드는 Kustomize가 커스터마이징할 Base 매니페스트 파일 목록을 지정합니다. Base 매니페스트 파일은 상대 경로 또는 절대 경로로 지정할 수 있으며, URL을 사용하여 원격 파일도 지정할 수 있습니다.

예시:

resources:
  - deployment.yaml  # 로컬 Deployment 파일
  - service.yaml     # 로컬 Service 파일
  - ../base         # 상위 디렉토리의 base 디렉토리
  - https://example.com/manifests/configmap.yaml  # 원격 ConfigMap 파일

3.3 bases#

bases 필드는 resources와 유사하지만, 다른 Kustomize 설정 파일을 참조하는 데 사용됩니다. bases 필드를 사용하면 여러 개의 Kustomize 설정을 계층적으로 구성할 수 있습니다.

예시:

bases:
  - ../../base  # 상위 디렉토리의 base 디렉토리에 있는 Kustomize 설정 파일

3.4 patches#

patches 필드는 Base 매니페스트 파일에 적용할 변경 사항을 정의합니다. Kustomize는 두 가지 방식의 패치(Patch)를 제공합니다.

  • patchesStrategicMerge: 기존 리소스의 설정을 병합하는 방식입니다. 이 방식은 Kubernetes Strategic Merge Patch 방식을 사용하며, YAML 형식으로 작성된 패치 파일을 사용합니다.
  • patchesJson6902: JSON Patch 형식을 사용하여 설정을 변경하는 방식입니다. 이 방식은 JSON Patch 표준을 따르며, JSON 형식으로 작성된 패치 파일을 사용합니다.

patchesStrategicMerge 예시:

patchesStrategicMerge:
  - deployment-patch.yaml

deployment-patch.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app-deployment  # 변경할 Deployment 이름
spec:
  template:
    spec:
      containers:
      - name: my-app-container
        image: my-app:1.0.1  # 이미지 태그 변경

patchesJson6902 예시:

patchesJson6902:
  - target:
      kind: Deployment
      name: my-app-deployment  # 변경할 Deployment 이름
    patch: |-
      - op: replace
        path: /spec/template/spec/containers/0/image
        value: my-app:1.0.1  # 이미지 태그 변경

3.5 namePrefix, nameSuffix#

namePrefix와 nameSuffix 필드는 Kustomize가 생성하는 모든 리소스 이름에 접두사 또는 접미사를 추가합니다. 이는 여러 환경에서 동일한 리소스 이름을 사용해야 하는 경우 유용합니다.

예시:

namePrefix: dev-  # 리소스 이름에 "dev-" 접두사 추가
nameSuffix: -dev  # 리소스 이름에 "-dev" 접미사 추가

3.6 namespace#

namespace 필드는 Kustomize가 생성하는 모든 리소스의 네임스페이스를 변경합니다. 이는 개발, 스테이징, 프로덕션 등 여러 환경에서 동일한 리소스를 다른 네임스페이스에 배포해야 하는 경우 유용합니다.

예시:

namespace: development  # 네임스페이스를 "development"로 변경

3.7 commonLabels#

commonLabels 필드는 Kustomize가 생성하는 모든 리소스에 공통 레이블을 추가합니다. 이는 리소스를 그룹화하고 관리하는 데 유용합니다.

예시:

commonLabels:
  environment: development  # "environment: development" 레이블 추가

3.8 commonAnnotations#

commonAnnotations 필드는 commonLabels와 유사하지만, 레이블 대신 어노테이션을 추가합니다. 어노테이션은 리소스에 대한 메타데이터를 저장하는 데 사용되며, 리소스의 동작에 영향을 미치지 않습니다.

예시:

commonAnnotations:
  owner: john.doe@example.com  # "owner: john.doe@example.com" 어노테이션 추가
  - bases, patches, resources, namePrefix, nameSuffix, commonLabels, commonAnnotations

4. Kustomize를 이용한 설정 변경 실습: 이미지 태그 변경, 리소스 제한 변경, 환경 변수 설정#

이 섹션에서는 Kustomize를 사용하여 쿠버네티스 리소스 설정을 변경하는 실습을 진행합니다. 이미지 태그 변경, 리소스 제한 변경, 환경 변수 설정과 같은 일반적인 설정 변경 작업을 Kustomize를 통해 어떻게 수행하는지 단계별로 설명합니다.

4.1 실습 환경 준비#

먼저 Kustomize를 사용할 수 있는 환경을 준비합니다.

  • Base 매니페스트 파일 준비: 다음과 같은 Base 매니페스트 파일을 생성합니다.

    base/deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: my-app-container
        image: my-app:latest  # 기본 이미지 태그
        ports:
        - containerPort: 80
        resources:
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            cpu: 200m
            memory: 256Mi
        env:
        - name: MY_ENV_VAR
          value: "default_value"  # 기본 환경 변수 값

base/service.yaml:

apiVersion: v1
kind: Service
metadata:
  name: my-app-service
spec:
  selector:
    app: my-app
  ports:
  - protocol: TCP
    port: 80
    targetPort: 80
  type: ClusterIP
  • Overlay 디렉토리 생성: 다음과 같은 Overlay 디렉토리를 생성합니다.
my-app/
├── base/
│   ├── deployment.yaml
│   └── service.yaml
└── overlays/
    └── dev/  # 개발 환경 Overlay

4.2 이미지 태그 변경#

개발 환경에서 사용할 이미지 태그를 "1.0.0"으로 변경합니다.

  • overlays/dev/kustomization.yaml: 파일 생성 및 내용 작성
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../../base

namespace: development

images:
  - name: my-app
    newName: my-app
    newTag: 1.0.0  # 이미지 태그 변경
  • Kustomize 적용:
kubectl apply -k overlays/dev
  • 결과 확인:
kubectl get deployment my-app-deployment -n development -o yaml | grep image:

출력 결과에서 이미지 태그가 "1.0.0"으로 변경되었는지 확인합니다.

4.3 리소스 제한 변경#

개발 환경에서 Pod의 리소스 제한을 변경합니다.

  • overlays/dev/kustomization.yaml: 파일 수정
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../../base

namespace: development

images:
  - name: my-app
    newName: my-app
    newTag: 1.0.0

patchesStrategicMerge:
  - deployment-patch.yaml  # 패치 파일 추가
  • overlays/dev/deployment-patch.yaml: 패치 파일 생성 및 내용 작성
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app-deployment  # 변경할 Deployment 이름
spec:
  template:
    spec:
      containers:
      - name: my-app-container
        resources:
          requests:
            cpu: 50m  # CPU 요청량 변경
            memory: 64Mi  # 메모리 요청량 변경
          limits:
            cpu: 100m  # CPU 제한량 변경
            memory: 128Mi  # 메모리 제한량 변경
  • Kustomize 적용:
kubectl apply -k overlays/dev
  • 결과 확인:
kubectl get deployment my-app-deployment -n development -o yaml | grep resources:

출력 결과에서 리소스 제한이 변경되었는지 확인합니다.

4.4 환경 변수 설정#

개발 환경에서 사용할 환경 변수를 추가하거나 변경합니다.

  • overlays/dev/kustomization.yaml: 파일 수정
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../../base

namespace: development

images:
  - name: my-app
    newName: my-app
    newTag: 1.0.0

patchesStrategicMerge:
  - deployment-patch.yaml
  • overlays/dev/deployment-patch.yaml: 패치 파일 수정
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app-deployment  # 변경할 Deployment 이름
spec:
  template:
    spec:
      containers:
      - name: my-app-container
        resources:
          requests:
            cpu: 50m
            memory: 64Mi
          limits:
            cpu: 100m
            memory: 128Mi
        env:
        - name: MY_ENV_VAR
          value: "dev_value"  # 환경 변수 값 변경
        - name: NEW_ENV_VAR
          value: "new_value"  # 새로운 환경 변수 추가
  • Kustomize 적용:
kubectl apply -k overlays/dev
  • 결과 확인:
kubectl get deployment my-app-deployment -n development -o yaml | grep MY_ENV_VAR:
kubectl get deployment my-app-deployment -n development -o yaml | grep NEW_ENV_VAR:

출력 결과에서 환경 변수 값

이 변경되었는지, 새로운 환경 변수가 추가되었는지 확인합니다.

4.5 실습 결과 검증#

각 단계별로 kubectl get 명령어를 사용하여 리소스의 상태를 확인하고, 변경 사항이 제대로 적용되었는지 검증합니다.

4.6 Kustomize 장점 활용#

이 실습에서는 Kustomize의 핵심 장점인 기존 매니페스트 파일 수정 최소화, 환경별 설정 관리 용이성을 직접 경험했습니다. Base 매니페스트 파일을 변경하지 않고 Overlay 디렉토리에 패치 파일을 추가하여 개발 환경에 맞는 설정을 적용할 수 있었습니다.