정정지용
기술스택 목록
DevOps

ArgoCD

프로젝트 16개에서 사용했습니다. 각 프로젝트에서 어떤 역할로 썼는지 아래에 정리했습니다.

이 기술은 무엇인가요?

Git 저장소의 매니페스트 상태를 쿠버네티스 클러스터에 자동으로 동기화하는 GitOps 도구

ArgoCD는 쿠버네티스를 위한 GitOps 지속적 배포(CD) 도구로, Git 저장소에 선언된 매니페스트를 진실의 원천(source of truth)으로 삼아 실제 클러스터 상태를 그 상태와 지속적으로 비교하고 맞춰준다. 배포 스크립트를 직접 실행하는 대신 Git 커밋만으로 배포가 이루어지도록 하여, 배포 이력 추적과 롤백을 Git 히스토리로 관리할 수 있게 하려는 목적으로 만들어졌다. 클러스터 내부에서 컨트롤러 형태로 동작하며 대상 클러스터 상태를 주기적으로 감시(watch)한다.

이럴 때 사용합니다

  • 배포 변경 이력과 승인 과정을 Git 커밋/PR로 남기고 감사(audit)하고 싶을 때
  • 여러 클러스터·환경에 걸쳐 배포 상태를 일관되게 유지하고 싶을 때
  • 수동 kubectl apply 없이 선언적 방식으로 배포를 자동화하고 싶을 때
  • 배포 상태 드리프트(설정 불일치)를 자동으로 감지하고 되돌리고 싶을 때

핵심 개념

GitOps
Git 저장소의 선언적 설정을 시스템의 유일한 진실의 원천으로 삼고, 실제 상태를 그에 맞춰 자동 수렴시키는 운영 방식이다.
Application
ArgoCD가 관리하는 배포 단위로, 어떤 Git 저장소·경로를 어떤 클러스터·네임스페이스에 배포할지를 정의하는 커스텀 리소스다.
Sync
Git에 정의된 원하는 상태(desired state)와 클러스터의 실제 상태(live state) 차이를 감지해 실제 상태를 원하는 상태로 맞추는 동작이다.
Reconcile Loop
컨트롤러가 대상 상태와 현재 상태를 지속적으로 비교하며 차이가 생기면 자동으로 교정하는 제어 루프 개념이다.
Kustomize/Helm 연동
매니페스트를 순수 YAML뿐 아니라 Kustomize overlay나 Helm 차트 형태로도 정의할 수 있게 지원해 환경별 값 관리를 돕는다.

ArgoCD Application 정의 예시

infra-repo의 production overlay 경로를 감시하다가 변경이 생기면 자동으로 클러스터에 동기화(prune·selfHeal 포함)하는 Application 리소스다.

YAML
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-service
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/org/infra-repo.git
    targetRevision: main
    path: overlays/production
  destination:
    server: https://kubernetes.default.svc
    namespace: my-service
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

처음 쓸 때 흔한 함정

  • automated sync 미설정 시 Git 변경이 있어도 수동으로 sync 버튼을 눌러야 반영된다.
  • 클러스터에서 kubectl로 직접 수정하면 selfHeal에 의해 곧 원래 상태로 되돌려진다.
  • Application의 source 저장소·경로 오타나 권한 문제로 조용히 OutOfSync 상태에 머무를 수 있다.

위 개요는 기술 학습을 돕기 위해 자동 생성된 일반 설명입니다. 정확한 사양과 최신 정보는 공식 문서를 확인하세요.

프로젝트별 활용 방식

위 개념이 실제 프로젝트에서 어떻게 쓰였는지 보여줍니다.

  2. 02인프라
    2026년 7월

    멀티체인 NFT 워커 GitOps 배포 문서

    NFT 마켓플레이스 워커 서비스를 체인별(Polygon/Klaytn/Ethereum)로 Kustomize와 ArgoCD로 배포하는 구조를 정리한 문서

    이 프로젝트에서의 ArgoCD 활용

    GitOps 방식으로 오버레이 변경을 감지해 대상 클러스터에 sync

    nft-marketplace-worker-argocd-deploy-docs프로젝트 자세히 보기 →
  4. 04인프라
    2026년 7월

    NFT 마켓 어드민 GitOps 배포 문서

    NFT 마켓플레이스 어드민 프런트엔드의 ArgoCD 기반 GitOps 배포 구조와 CI/CD 흐름을 정리한 문서 저장소입니다.

    이 프로젝트에서의 ArgoCD 활용

    Git에 커밋된 매니페스트를 감지해 클러스터에 자동 동기화

    nft-marketplace-admin-frontend-argocd-deploy-docs프로젝트 자세히 보기 →
  9. 09인프라
    2026년 7월

    멀티체인 크론 스케줄러 배포 구조 문서

    체인별 폴더 구조와 Kustomize base/overlays로 크론 스케줄러를 Jenkins-ArgoCD GitOps 흐름으로 배포하는 구조를 정리한 문서

    이 프로젝트에서의 ArgoCD 활용

    레포에 커밋된 이미지 태그/overlay 값을 클러스터에 자동 동기화하는 GitOps 배포

    cron-scheduler-argocd-deploy-docs프로젝트 자세히 보기 →
  11. 11인프라
    2026년 5월

    레이싱 플랫폼 API 서버 GitOps 배포

    온라인 레이싱 게임 API 서버를 ArgoCD와 Kustomize로 운영하는 GitOps 배포 구성과 게임 도메인 특화 대응 정리

    이 프로젝트에서의 ArgoCD 활용

    GitOps 기반으로 매니페스트 변경을 자동 동기화 및 배포

    racing-platform-backend-api-argocd-deploy-docs프로젝트 자세히 보기 →

함께 사용한 기술

위 프로젝트들에서 같이 쓰인 다른 기술입니다.

Kubernetes16Kustomize16Jenkins12PostgreSQL4Docker3Redis3Prometheus2AWS ALBAWS Route53AWS SQSAWS SSM Parameter StoreDocker Compose