🛠️ Argo CD x Kustomize 마스터 가이드: 이미지 오버라이드와 버전 고정 기법

쿠버네티스 환경에서 GitOps를 실천할 때 가장 많이 사용하는 도구 조합이 바로 Argo CD와 Kustomize입니다. 하지만 운영을 하다 보면 특정 환경에서만 이미지를 살짝 바꾸고 싶거나, Kustomize 버전에 따라 빌드 결과가 달라져 곤란한 상황을 겪게 되죠.

오늘은 Argo CD Application에서 Kustomize 이미지 태그를 오버라이드(Override)하는 구체적인 위치와 방법, 그리고 특정 Kustomize 버전을 고정(Pinning)하여 빌드 안정성을 확보하는 법까지 아주 상세하게 파헤쳐 보겠습니다! 🚀

안녕하세요! 오늘은 Argo CD를 통해 Kustomize 매니페스트를 배포할 때, 운영 효율을 극대화할 수 있는 두 가지 핵심 테크닉을 준비했습니다. 10분만 투자해서 여러분의 GitOps 파이프라인을 한 단계 더 업그레이드해 보세요.

---

1. Kustomize 이미지 태그는 어디서 오버라이드할 수 있나요? 🖼️

일반적으로 Kustomize를 사용할 때는 kustomization.yaml 파일에 images 필드를 정의합니다. 하지만 Argo CD를 사용하면 Git 저장소를 직접 수정하지 않고도 Application 리소스 수준에서 이미지를 동적으로 변경할 수 있습니다.

① Argo CD Application Manifest (YAML)에서 설정

가장 권장되는 방법입니다. Application 리소스의 spec.source.kustomize 경로에 오버라이드할 이미지 정보를 선언합니다.

📝 코드 예시 및 설명

YAML

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-kustomize-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/my-infra.git
    targetRevision: HEAD
    path: overlays/production
    # Kustomize 관련 설정을 정의하는 섹션입니다.
    kustomize:
      # 여기서 이미지 태그를 오버라이드합니다.
      # kustomization.yaml에 정의된 이미지 이름을 찾아 새 태그로 치환합니다.
      images:
        - name: my-api-image         # 원본 이미지 이름
          newName: my-api-image     # (선택) 이미지 이름을 바꿀 경우
          newTag: v2.0.0-release    # 새로운 태그 버전 지정 👈 핵심!
  destination:
    server: https://kubernetes.default.svc
    namespace: prod

② Argo CD CLI를 통한 실시간 변경

CI 파이프라인(Jenkins, GitHub Actions 등)에서 배포 직전에 태그를 바꾸고 싶을 때 유용합니다.

Bash

# 특정 애플리케이션의 이미지 태그를 즉시 변경하는 명령
argocd app set my-kustomize-app --kustomize-image my-api-image=v2.0.0-release

③ Argo CD Web UI에서 변경

사용자 인터페이스(UI)에서도 가능합니다.

• Application 접속 -> PARAMETERS 탭 클릭 -> Kustomize 섹션에서 images 항목 수정.

---

2. 특정 Kustomize 버전을 고정(Pinning)하는 방법 📌

Argo CD는 내장된 Kustomize 바이너리를 사용합니다. 하지만 로컬에서 사용하는 버전과 Argo CD 내부 버전이 다를 경우, 매니페스트 렌더링 결과가 달라져 OutOfSync가 발생하거나 배포 오류가 날 수 있습니다. 이를 방지하기 위해 버전을 고정하는 방법은 크게 두 가지입니다.

① Argo CD ConfigMap (argocd-cm) 수정 ⚙️

Argo CD 설정 파일인 argocd-cm을 수정하여 기본적으로 사용할 Kustomize 실행 파일 경로를 지정할 수 있습니다. 하지만 이 방법은 Argo CD가 지원하는 범위 내에서만 가능합니다.

YAML

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  # kustomize.buildOptions 등을 통해 빌드 옵션을 제어할 수 있습니다.
  kustomize.buildOptions: "--load-restrictor LoadRestrictionsNone"

② Custom Tooling (Sidecar Container) 활용 📦

가장 확실하고 강력한 방법입니다. Argo CD의 repo-server에 원하는 버전의 Kustomize 바이너리를 설치한 사이드카 컨테이너를 붙이거나, 이미지를 커스텀하여 특정 버전을 포함시킵니다.

📝 Argo CD Repo-Server 커스텀 예시 (Docker)

Dockerfile

# Argo CD 공식 이미지를 베이스로 사용
FROM argoproj/argocd:v2.8.4

# root 권한으로 전환하여 설치 진행
USER root

# 원하는 특정 버전의 Kustomize 다운로드 (예: v5.0.0)
RUN curl -L https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize%2Fv5.0.0/kustomize_v5.0.0_linux_amd64.tar.gz | tar -xz && \
    mv kustomize /usr/local/bin/kustomize-v5

# 다시 argocd 유저로 변경
USER 999

 

그 후, argocd-cm에서 이 커스텀 바이너리를 사용하도록 설정하거나 **Config Management Plugin(CMP)**을 정의하여 사용합니다.

---

3. 요약 및 실무 체크리스트 📊

작업 내용	위치 / 방법	비고
이미지 태그 변경	Application Spec (spec.source.kustomize.images)	Git 수정 없이 환경별 태그 분리 가능
임시 이미지 변경	Argo CD CLI / Web UI	빠른 테스트 및 수동 배포에 적합
Kustomize 버전 고정	argocd-repo-server 커스텀 바이너리 설치	일관된 빌드 결과 보장 (강력 권장)
빌드 옵션 추가	argocd-cm 내 kustomize.buildOptions	플래그(--enable-alpha-plugins 등) 추가 시 사용

---

🏁 마치며

Kustomize 이미지 오버라이드는 Argo CD를 진정한 **'환경별 설정 도구'**로 만들어 줍니다. 또한 Kustomize 버전을 명확히 고정하는 습관은 "내 컴퓨터에서는 되는데 서버에서는 왜 안 되지?"라는 고전적인 문제를 원천 봉쇄해 줍니다.

여러분의 프로젝트 상황에 맞춰 가장 적절한 오버라이드 방식을 선택해 보세요! 🛠️