ArgoCD Image Updater — GitOps 이미지 자동 승격 워크플로 | 기술노트

핵심 요약

ArgoCD Image Updater 0.16이 2026년 5월 기준 안정. CI가 새 이미지를 푸시하면 Updater가 레지스트리를 polling해 매니페스트 레포에 자동 커밋, ArgoCD가 sync. dev/stg는 latest semver, prd는 PR 기반 승인 게이트로 분리하는 패턴이 표준이 됐다. 단, polling 간격과 write-back 충돌이 함정.

1. 왜 필요한가

전통적 GitOps에서는 CI가 이미지 푸시 후 매니페스트 레포에 sed로 태그 바꿔서 커밋하는 스크립트를 직접 짠다. 이게 환경마다, 서비스마다 늘어나면 관리 불능. Image Updater는 이 역할을 선언적 어노테이션으로 위임한다.

2. 기본 어노테이션

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: api-dev
  annotations:
    argocd-image-updater.argoproj.io/image-list: api=ghcr.io/acme/api
    argocd-image-updater.argoproj.io/api.update-strategy: semver
    argocd-image-updater.argoproj.io/api.allow-tags: regexp:^1\.[0-9]+\.[0-9]+-dev$
    argocd-image-updater.argoproj.io/write-back-method: git
    argocd-image-updater.argoproj.io/git-branch: main

3. 네 가지 업데이트 전략

전략	용도	예시
semver	안정 릴리즈	1.2.3 → 1.2.4
latest	최신 푸시	created 시각 기준
digest	mutable 태그	main 태그 디지스트 추적
name	알파벳 정렬	커밋 해시 태그

dev는 digest로 main 태그를 따라가게, stg는 semver로 -rc 허용, prd는 semver 안정만. 실수 적은 조합.

4. write-back — git이 사실상 표준

annotations:
  argocd-image-updater.argoproj.io/write-back-method: git:secret:argocd/git-creds
  argocd-image-updater.argoproj.io/write-back-target: kustomization
  argocd-image-updater.argoproj.io/git-repository: https://github.com/acme/manifests
  argocd-image-updater.argoproj.io/git-branch: main:image-updates/{{.Name}}

5. 환경별 승격 — dev 자동, prd 게이트

name: image-updater-pr
on:
  push:
    branches: ['image-updates/**']
jobs:
  pr:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - run: |
          gh pr create --base main --head "\$GITHUB_REF_NAME" \
            --title "chore(image): \$(basename \$GITHUB_REF_NAME)" \
            --label auto-promotion --label needs-review

CODEOWNERS로 prd 매니페스트 디렉터리에 SRE 팀 리뷰 필수. 자동 머지는 절대 금물.

6. 실측 — 30개 서비스

지표	수동 스크립트	Image Updater
커밋 누락	월 3~4건	0건
평균 푸시→배포	8분	2분 40초
레지스트리 호출	~120/h	~800/h
운영 인력 시간/월	22h	4h

7. Flux Image Reflector와 비교

Flux는 ImageRepository, ImagePolicy, ImageUpdateAutomation 세 CRD로 분리. 더 선언적이지만 학습 곡선이 가파르다. ArgoCD를 이미 쓰고 있다면 Updater가 통합 비용 0. Flux 풀스택이라면 Reflector가 자연. 기능 차는 거의 없고 정책 표현력만 Flux가 약간 풍부하다.

8. 함정 — write-back 충돌

여러 서비스가 같은 kustomization.yaml을 동시에 수정하면 git push 충돌. Updater는 재시도 3회 후 포기, 다음 polling까지 대기. 서비스별로 디렉터리를 분리하거나 git-write-back-targets로 파일 단위 분리 권장. Helm chart 하나에 image 10개 묶는 안티패턴은 금물.

9. 보안

매니페스트 레포 푸시 권한이 클러스터 내부 ServiceAccount에 위임된다. SSO 우회 경로. 별도 deploy key로 격리하고, signed commit을 강제. Sigstore cosign으로 이미지 서명 검증을 ImagePolicy 단계에서 같이.

참고

argocd-image-updater.readthedocs.io
fluxcd.io/flux/components/image
github.com/argoproj-labs/argocd-image-updater