91. Kustomize (커스터마이즈) - 오버레이 기반 선언적 매니페스트 관리 도구

⚠️ 이 문서는 쿠버네티스(K8s)에 웹 서버를 띄울 때, 개발망(dev)에는 램 1GB를 세팅하고 운영망(prod)에는 램 10GB를 세팅하기 위해 deployment.yaml 파일을 귀찮게 2개로 복사(Copy & Paste)해서 쓰다가 오타가 나서 망하는 것을 막으려 도입한 'Helm(헬름)'이, **{{ .Values.memory }} 같은 지저분한 변수 구멍을 뚫느라 원본 YAML 파일의 아름다움을 파괴하고 가독성을 박살 내자, 분노한 K8s 진영에서 "원본 YAML 파일은 1글자도 수정하지 말고 순정 그대로 놔둬라! 그냥 그 위에 투명 셀로판지(Overlay)를 덮어씌워서 글자만 살짝 덧칠(Patch)해 버리자!"라는 철학으로 K8s 본체에 내장시켜 버린 네이티브 K8s 템플릿 끝판왕 도구, 'Kustomize(커스터마이즈)'**를 다룹니다.

핵심 인사이트 (3줄 요약)

  1. 본질: 템플릿 변수({{ }})가 없다. 100% 순수한 K8s yaml 파일들만 존재한다. 공통으로 쓸 뼈대 폴더(base)를 하나 만들어두고, 환경(dev, prod)별로 덧바를 스티커 폴더(overlays)를 만들어 런타임에 찰떡같이 병합(Merge)해 내는 기술이다.
  2. 가치: 헬름(Helm)처럼 외부 툴을 따로 깔거나 문법을 공부할 필요가 없다. K8s의 기본 명령어인 kubectl apply -k 안에 이미 내장(Built-in)되어 있어, 완벽한 클라우드 네이티브(K8s-Native) 호환성을 자랑하며 GitOps(ArgoCD) 툴들과 극강의 시너지를 낸다.
  3. 기술 체계: 변하지 않는 진리의 뼈대인 Base, 각 환경에 맞게 글자를 덮어치는 Overlays, 그리고 "이 폴더 안의 yaml들을 싹 다 긁어모아라"라고 지시하는 kustomization.yaml 이라는 조립 지시서가 3각 편대로 돌아간다.

Ⅰ. Helm의 딜레마: 구멍 뚫린 빵틀(Template)의 지저분함

변수를 편하게 넣으려다, 원본 도면이 외계어가 되어버렸다.

  1. 헬름(Helm) 템플릿의 역효과:
    • 어제 배운 Helm은 훌륭하다. 하지만 deployment.yaml 속살을 까보면 끔찍하다.
    • replicas: {{ .Values.replicaCount | default 1 }}
    • image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
    • 순수한 K8s YAML 문법은 온데간데없고, 중괄호({{ }})와 조건문(if-else)이 떡칠 되어 인간이 눈으로 읽고 이해할 수 없는 외계어 빵틀이 되어버렸다. 이 파일을 K8s API 서버에 다이렉트로 던지면 "문법 에러"라며 뱉어낸다. (순정 K8s 객체가 아님)
  2. Kustomize의 등판 선언 (Template-free):
    • 구글 엔지니어들이 빡쳐서 만들었다. "왜 멀쩡한 YAML에 구멍을 뚫고 지저분하게 코딩(Template)을 섞냐? 우린 100% 쌩얼 K8s YAML 파일의 순수성을 보존하겠다!"
    • Kustomize는 변수 주입({{ }}) 방식을 완전히 쓰레기통에 버리고, **'오버레이 패치(Overlay Patching)'**라는 완전히 다른 차원의 접근법으로 환경(dev/prod) 분리를 해결해 냈다.

📢 섹션 요약 비유: Helm은 벽돌집을 지을 때 시멘트 반죽 자체에 파란색 색소(변수 템플릿)를 비벼 넣어서 벽돌을 찍어내는 방식입니다. 나중에 색을 바꾸려면 벽돌을 처음부터 다시 부수고 구워야 합니다(복잡함). Kustomize는 순백의 하얀 벽돌집(Base)을 일단 완벽하게 지어놓습니다(순수 YAML 보존). 그리고 그 위에 파란색 셀로판지(Dev Overlay)를 덮거나 빨간색 셀로판지(Prod Overlay)를 겹쳐 덮어서(Patching), 밑바탕은 건드리지 않고 밖에서 보이는 색깔만 자유자재로 바꾸는 위대한 투명막 마법입니다.

Ⅱ. 베이스(Base)와 오버레이(Overlay)의 이중주

원본은 절대 건드리지 마라. 투명 필름을 덮어 글씨만 덮어써라.

  1. 폴더 구조의 분리 (Base vs Overlays):
    • 깃허브(Git)에 폴더를 예쁘게 찢어 파놓는다.
    • base/: 여기엔 운영망이든 개발망이든 똑같이 들어가는 완벽한 순정 K8s deployment.yaml (파드 1개 띄우기)을 딱 1벌만 놔둔다.
    • overlays/dev/: 개발망 전용 폴더다.
    • overlays/prod/: 운영망 전용 폴더다.
  2. 오버레이 패치 (Patching)의 덮어치기 마법:
    • overlays/prod/ 폴더 안에는 전체 도면이 없다. 딱 한 장의 작은 쪽지(patch.yaml)만 들어있다.
    • 쪽지 내용: replicas: 100 (운영망은 파드 100개 띄워라)
    • 터미널에 kubectl apply -k overlays/prod 라고 마법의 -k 옵션을 주고 엔터를 쾅! 친다.
    • 조립 시작: Kustomize 엔진이 base/ 폴더의 원본 뼈대(파드 1개)를 쫙 스캔해서 가져온 뒤, 그 위에 prod/ 폴더의 쪽지(파드 100개)를 투명 셀로판지처럼 스윽 덮어씌운다(Patch). 1이 100으로 덮어 써진다.
    • 결과물: 뼈대는 그대로 유지하면서, 램 할당량, 파드 개수, 데이터베이스 IP 주소만 운영망에 맞게 싹 덮어치기 된 완성본 YAML 뭉치가 0.1초 만에 조립되어 클러스터로 다이렉트 슛 꽂힌다.
  3. kustomization.yaml (조립 지시서):
    • 폴더마다 무조건 이 파일이 1개씩 박혀있다.
    • 내용: "내 뼈대는 저 밑에 있는 ../base 폴더고, 내가 덮어쓸 패치 파일은 patch.yaml 이야. 그리고 모든 파드 이름표(Label) 앞에는 강제로 env: prod라는 딱지를 전부 쑤셔 넣어줘!"라고 지시하는 컨트롤 타워 텍스트 파일이다.

📢 섹션 요약 비유: 화가가 밑그림(Base)으로 눈, 코, 입이 달린 마네킹 스케치를 딱 1장 그렸습니다. 이걸 지우개로 지웠다 다시 그리는 게 아닙니다(복사 붙여넣기의 멸망). 화가는 그 밑그림 위에 투명한 OHP 필름(Overlays)을 덮습니다. 첫 번째 필름(Dev)에는 '선글라스'만 그려져 있습니다. 덮으면 선글라스를 낀 마네킹이 됩니다. 두 번째 필름(Prod)에는 '정장 아머'가 그려져 있습니다. 겹치면 완벽한 전투 요원이 됩니다. 원본 마네킹 그림(순정 YAML)은 단 한 줄도 훼손당하지 않고 영구 보존되면서 무한한 변신(다형성)을 꾀하는 투명 필름 레이어링 기술입니다.

Ⅲ. Helm과 Kustomize의 혼인: ArgoCD의 축복

서로를 죽이는 적이 아니다. 헬름이 빵을 구우면, 커스터마이즈가 버터를 바른다.

  1. 누가 승자인가? (용도의 차이):
    • "그럼 Helm은 버리고 Kustomize만 써야 하나요?" $\rightarrow$ 절대 아니다.
    • Helm (남이 만든 거 가져올 때): Kafka, Redis, Jenkins처럼 내가 소스코드를 짠 게 아니라, 오픈소스 천재들이 1만 줄로 복잡하게 짜놓은 외부 솔루션을 1초 만에 패키지로 다운받아 깔 때는 무조건 Helm이 압도적 1등이다.
    • Kustomize (내가 짠 회사 앱 배포할 때): 우리 회사가 짠 결제 모듈, 쇼핑 모듈을 개발망(dev), 검증망(stg), 운영망(prod) 서버로 똑같은 코드를 3번씩 배포할 때, 예쁜 YAML 뼈대를 훼손하지 않고 환경 변수만 살짝 패치해서 던질 때는 Kustomize가 신이다.
  2. Post-Rendering (헬름 위에 셀로판지 덮기):
    • 최근 진성 고인물 데브옵스 엔지니어들의 궁극의 콤보 전술이다.
    • 외부에서 엄청 복잡한 헬름 차트를 다운받았다. 근데 우리 회사 보안팀이 "야! 모든 파드 이름 앞에 강제로 [kakao-보안] 이라는 글씨를 다 쑤셔 넣어!"라고 말도 안 되는 지시를 내렸다.
    • 헬름 차트를 뜯어고치려니 1만 줄이라 불가능하다. 이때 Kustomize를 헬름 위에 덮어버린다.
    • 헬름 엔진이 빵(YAML)을 1차로 쫙 구워내면, Kustomize가 그 튀어나온 빵 전체에 셀로판지(Patch)를 확 덮어씌워서 일괄적으로 이름표를 싹 다 갈아 치워 버린다 (Post-Rendering).
  3. ArgoCD 뱃속의 완벽한 소화:
    • 어제 배운 GitOps 대장 봇(ArgoCD)은 이 미친 콤보를 뱃속에서 알아서 완벽하게 지원한다.
    • 개발자가 깃허브에 kustomization.yaml 파일을 띡 올려놓으면, ArgoCD가 "아하, 이건 헬름이 아니라 커스터마이즈 엔진으로 조립해서 덮어씌워 줘야 하는구나!"라고 1초 만에 눈치채고 엔진을 윙~ 돌려 완벽한 운영망용 YAML을 찍어내어 클러스터에 박아넣는다. 100% 무인 인프라 자동화의 완성이다.

📢 섹션 요약 비유: Helm은 외부 공장(오픈소스)에서 대량 생산해 온 [완제품 케이크]입니다. 내가 직접 반죽할 필요가 없어 편합니다. 하지만 이 케이크에 우리 회사 로고(패치)를 꼭 박아야 합니다. 케이크를 해체하고 다시 구우면 망가집니다. 이때 **Kustomize(오버레이)**라는 기계를 가져와서, 완성된 케이크 위에 '우리 회사 깃발 스티커'만 1초 만에 찰칵! 하고 일괄적으로 꽂아줍니다(Post-Rendering). ArgoCD(주방장)는 이 콤보 기술을 완벽히 마스터하고 있어서, 공장에서 떼 온 케이크에 깃발을 꽂는 전 과정을 1초 만에 전자동으로 세팅하여 진열장에 올려놓는 환상적인 콤비네이션입니다.