[MacOS 환경 #26] 쿠버네티스 동적으로 배포하기 (Kustomize)

도람·2025년 11월 30일

🖥️제로부터 시작하는 Docker & 쿠버네티스

목록 보기

55/82

Kustomize란 무엇인가

Kustomize는 쿠버네티스 리소스를 템플릿 없이 덧입혀서(overlays) 관리하기 위한 도구이다.
요즘은 kubectl 안에 통합되어 있어서 별도 설치 없이 kubectl kustomize, kubectl apply -k 같은 식으로 바로 쓴다.

핵심 아이디어:

디렉터리 하나에 kustomization.yaml 파일을 만든다.
그 안에
- resources: → “원본 YAML 들”
  - images: → “이미지 이름/태그 덮어쓰기”
  - 그 외 namePrefix, patches 등
을 적어두고,
kubectl kustomize . 로 “최종 YAML”을 한 번에 만들어서 배포하는 방식이다.

공식 문서에서도 images 필드로 컨테이너 이미지를 바꾸는 예제가 나와있다.

resources:
- deployment.yaml
images:
- name: nginx
  newName: my.image.registry/nginx
  newTag: 1.4.0

이렇게만 적어두면, deployment.yaml 안에 있는 image: nginx 가
자동으로 image: my.image.registry/nginx:1.4.0 으로 바뀐다.

왜 MetalLB 버전 올릴 때 Kustomize를 쓰는가?

MetalLB 같이 여러 개의 YAML 파일로 설치하는 애드온은 보통:

namespace 정의
CRD
controller Deployment
speaker DaemonSet …

이렇게 파일이 여러 개로 흩어져 있다.

버전만 살짝 올리고 싶어도,
각 파일에 들어있는 quay.io/metallb/controller:v0.14.4 / speaker:v0.14.4 를
일일이 찾아서 v0.14.5 로 바꿔야 한다.

Kustomize를 쓰면:

원본 YAML(res/metallb-native-*.yaml)은 그대로 두고
kustomization.yaml 에서 이미지 태그만 한 번에 덮어쓰기 해서
kustomize build 결과만 배포

하는 구조로 만들 수 있다.

결국 “버전 업 할 때는 kustomization.yaml 의 newTag 만 고치면 된다”

디렉터리 구조 예시

예를 들어 res/metallb-native/ 디렉터리 안에 이렇게 있다고 하자.

metallb-kustomize/
├── metallb-namespace.yaml     # 네임스페이스 매니페스트
├── metallb-native-v0.14.4.yaml  # 기존 MetalLB 설치 YAML (v0.14.4 버전)
└── kustomization.yaml         # 우리가 새로 만들 파일

여기서 metallb-native-v0.14.4.yaml은
기존에 쓰던 설치용 YAML(버전 0.14.4)이라고 생각하면 된다.

# 실습 – MetalLB 매니페스트에 Kustomize 입히기

이번 실습 목표는 간단하다.

MetalLB 공식 매니페스트를 그대로 가져오고
그 위에 kustomization.yaml로 이미지 태그만 바꿔서 배포해보는 것

이다.

1. MetalLB 네임스페이스 YAML 직접 만들기

먼저 MetalLB가 설치될 네임스페이스를 하나 만든다.

파일명: metallb-namespace.yaml

apiVersion: v1
kind: Namespace
metadata:
  name: metallb-system
  labels:
    pod-security.kubernetes.io/enforce: privileged
    pod-security.kubernetes.io/audit: privileged
    pod-security.kubernetes.io/warn: privileged

적용& 확인 명령어

kubectl apply -f metallb-namespace.yaml
kubectl get ns metallb-system

2. MetalLB 공식 매니페스트 파일 내려받기

이제 MetalLB 본체 리소스들이 들어 있는 매니페스트를 공식 깃허브에서 그대로 받아온다.

파일명: metallb-native-v0.14.4.yaml

curl -o metallb-native-v0.14.4.yaml \
  https://raw.githubusercontent.com/metallb/metallb/v0.14.4/config/manifests/metallb-native.yaml

이렇게 하면 현재 디렉터리에 metallb-native-v0.14.4.yaml 파일이 생성된다

이 yaml 파일의 내용을 조금 확인해보고 싶다면 head를 사용해서 간략하게 확인해볼 수 있다.

head -n 20 metallb-native-v0.14.4.yaml

3. kustomization.yaml 작성

이제 이 두 파일을 기반으로,
이미지 태그만 v0.14.4 → v0.14.5로 올려주는 kustomization.yaml 을 만든다.

파일명: kustomization.yaml

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

resources:
  - metallb-native-v0.14.4.yaml   # 공식 매니페스트만 사용

images:
  - name: quay.io/metallb/controller
    newTag: v0.14.5
  - name: quay.io/metallb/speaker
    newTag: v0.14.5

resources
- 방금 만든 metallb-namespace.yaml,
  그리고 MetalLB 공식 매니페스트 metallb-native-v0.14.4.yaml 을 그대로 불러온다.
images
- resources 안에서 image: quay.io/metallb/controller:* 를 찾아서
  태그를 v0.14.5 로 덮어쓴다.
- quay.io/metallb/speaker:* 도 마찬가지로 v0.14.5 로 덮어쓴다.

중요한 포인트는:

원본 metallb-native-v0.14.4.yaml 안에는 여전히 v0.14.4 라고 적혀 있어도 상관없다.
최종 결과를 만들 때 Kustomize가 알아서 전부 v0.14.5 로 교체한 YAML을 만들어준다는 것

이다.

4. Kustomize 빌드 결과 확인

이제 진짜 적용하기 전에,
“최종으로 어떤 YAML이 생성되는지”부터 한 번 눈으로 확인해보는 게 좋다.

# kustomization.yaml 이 있는 디렉터리에서
kubectl kustomize .

혹은 독립 실행형 kustomize 바이너리를 쓴다면:

kustomize build .

출력되는 YAML에서 image: 부분만 grep 해보면 된다.

kubectl kustomize . | grep -i "quay.io/metallb" -n

여기서

quay.io/metallb/controller:v0.14.5
quay.io/metallb/speaker:v0.14.5

처럼 보이면 Kustomize 변환은 잘 된 것이다.

5. 실제로 적용하기

이제 진짜 클러스터에 적용한다.

# kustomization.yaml 있는 디렉터리에서
kubectl apply -k .

여기서 -k 옵션이 말 그대로

“이 디렉터리를 Kustomize 디렉터리로 보고,
kustomization.yaml 을 읽어서 최종 YAML을 만들어서 apply 해라”

라는 의미이다.

6. MetalLB 파드 및 이미지 버전 확인

설치 후에는 MetalLB 파드가 metallb-system 네임스페이스에 떠 있는지 확인한다.

kubectl get pods -n metallb-system -o wide

그리고 실제로 이미지가 v0.14.5 로 바뀌었는지 확인한다.

# Deployment 기준으로 이미지 확인
kubectl -n metallb-system get deploy -o yaml | grep -i "quay.io/metallb" -n

quay.io/metallb/controller:v0.14.5
quay.io/metallb/speaker:v0.14.5

로 나와 있으면,
“공식 매니페스트는 v0.14.4를 쓰되, Kustomize로 v0.14.5로 올려서 배포” 하는 구조가 잘 동작한 거다.

전체 흐름 정리

공식 매니페스트 준비

metallb-namespace.yaml : 네임스페이스 정의
metallb-native-v0.14.4.yaml : MetalLB 공식 매니페스트 그대로 curl 로 다운로드

kustomization.yaml 작성

resources 로 위 두 파일 묶기
images 섹션에서 controller/speaker 태그만 v0.14.5 로 변경

kubectl kustomize / kubectl apply -k

빌드 결과로 실제 적용될 YAML 확인
kubectl apply -k . 로 배포

버전 검증

kubectl get pods -n metallb-system
kubectl -n metallb-system get deploy -o yaml | grep image

참고 자료 (공식 문서)
[쿠버네티스 공식 홈페이지 - Declarative Management of Kubernetes Objects Using Kustomize]
https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/