[argocd] ArgoCD Architecture

Argo CD는 Kubernetes에서 애플리케이션을 자동으로 배포하고 상태를 유지해주는 여러 구성요소로 구성된 컨트롤 플레인이다. 이 도구는 여러 개의 구성요소로 이루어져 있으며, 모두 Kubernetes 클러스터 안에서 실행된다. 기본적으로는 Argo CD가 설치된 클러스터 안의 애플리케이션을 관리하지만, ServiceAccount 토큰이나 클러스터 인증서 및 키, 혹은 클러스터 API 서버 주소를 제공하면 외부 클러스터도 관리할 수 있다.  예를 들어, Dev 클러스터에 Argo CD를 설치해놓고, Prod 클러스터의 애플리케이션도 관리할 수 있다는 뜻이다. Argo CD는 다음과 같은 구성요소로 이루어져 있다.

API 서버 (argocd-server)

• 사용자의 모든 외부 인터페이스 요청을 수신하는 엔드포인트
• REST API 서버이며, CLI, 웹 UI, Webhook, SSO 등 모든 클라이언트가 이 서버를 통해 접근
• 인증: JWT 기반 인증 처리 및 쿠키 세션 지원
• 권한 제어: RBAC 기반 정책을 통해 접근 제어 수행
• HTTPS 서버로 동작하며, TLS 인증서를 통해 보안 연결을 유지

리포지터리 서버 (argocd-repo-server)

• Git 저장소로부터 원본 애플리케이션 정의를 fetch하고, 이를 Kubernetes가 이해할 수 있는 형태로 변환(render)하는 역할
• Helm, Kustomize, Jsonnet, Ksonnet 등의 도구를 통해 템플릿을 실제 매니페스트로 렌더링
• 이 컴포넌트는 API 서버가 요청할 때마다 호출됨
• 앱 마다 Git HEAD를 기준으로 작업을 수행하며, 파일 시스템으로 clone 후, 렌더링 결과를 gRPC로 controller에 반환
• Git 인증에 필요한 SSH key, basic auth token, OAuth token 등 다양한 인증 수단 지원
• 성능 최적화를 위해 디스크 기반 캐시를 사용하며, 동일한 Git SHA에 대해 중복 연산을 피함

애플리케이션 컨트롤러 (argocd-application-controller)

• Argo CD의 핵심 컨트롤러로, 클러스터 상태(Live)와 Git 선언 상태(Desired)를 비교(diff)하고 동기화(sync)를 수행
• Kubernetes 리소스를 생성, 수정, 삭제하는 책임을 가짐
• Informer 패턴을 사용하여 클러스터 리소스 상태를 감시
• 차이 감지(differencing)는 YAML AST 레벨 비교를 통해 수행
• 동기화는 기본적으로 kubectl apply 전략을 따르며, CRD 및 커스텀 리소스도 지원
• 동기화 중에는 Hook, Sync Policy, Wave 같은 고급 전략 사용 가능
• Kubernetes RBAC를 통해 리소스에 접근

Dex (선택적 구성 요소)

• OIDC 인증 서버로, 외부 인증 시스템(GitHub, LDAP, Google 등)과 연동할 수 있도록 도와주는 bridge 역할
• 사용자 인증 요청을 받아 ID 토큰을 발급하고 Argo CD에 전달
• 자체적으로 static client 및 connector 설정을 관리
• Argo CD는 Dex를 OIDC Provider로 설정하여 OAuth2 flow를 통해 인증 처리
• 사용하지 않을 경우, Argo CD는 자체 로그인 기능(Local user/password 또는 SSO proxy 연동)만 사용

Redis

• Argo CD의 캐시 저장소로 사용
• 애플리케이션 및 프로젝트 관련 정보를 빠르게 조회할 수 있도록 지원

아키텍처 흐름 상세

사용자가 애플리케이션 정의를 등록

사용자는 CLI(argocd app create) 또는 Web UI를 통해 Kubernetes 클러스터에 Application 리소스를 생성한다. 이 리소스는 Custom Resource Definition(CRD)으로, 다음과 같은 주요 정보를 포함한다.

• source : Git 저장소, 브랜치, Helm/Kustomize 등 어떤 방식으로 배포할지
  • Git 저장소 주소 (repo URL)
  • Git 브랜치 혹은 commit hash
  • 해당 저장소 내 경로 (path)
  • 템플릿 엔진 종류 (Helm, Kustomize 등)
• destination : 어느 클러스터의 어느 namespace에 배포할지
• project : 권한/정책 관리를 위한 Argo CD 프로젝트 이름

Argo CD에서는 배포 대상 애플리케이션을 정의하는 "설정 파일"을 Kubernetes 리소스로 만들어 관리한다. 이 설정 파일의 이름이 바로 Application 리소스이다.

• Kubernetes는 Custom Resource(사용자 정의 리소스)를 통해 새로운 리소스 타입을 정의할 수 있다.
• Argo CD는 자신만의 리소스인 Application을 정의해서, GitOps 방식으로 애플리케이션 배포 정보를 관리한다.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
spec:
  source:
    repoURL: https://github.com/example/repo.git
    targetRevision: main
    path: charts/my-app
    helm:
      valueFiles: [values-prod.yaml]
  destination:
    server: https://kubernetes.default.svc
    namespace: prod
  project: default

 

API 서버가 요청을 수신하고 인증/인가 수행

• argocd-server는 Web UI, CLI, API 호출, webhook 등 외부 요청을 처리
• 로그인 시 JWT 기반 인증을 수행하며, RBAC 정책에 따라 사용자의 권한을 검증
• 사용자 요청에 따라 Kubernetes API 서버에 Application 리소스를 생성하거나 수정

Application Controller가 리소스 변경 감지

argocd-application-controller는 Argo CD의 핵심 엔진으로 해당 컨트롤러는 모든 Application 리소스를 지켜보면서(watch) 다음과 같은 역할을 한다.

• 새로운 Application이 생성되었는지 감지
• Git의 선언적 상태(원하는 모습)와 클러스터의 현재 상태를 비교
• 차이가 있다면 동기화(Sync) 수행

Kubernetes의 기본 구조를 이해하면 쉽게 알 수 있다. Kubernetes의 컨트롤러는 일반적으로 다음과 같은 메커니즘으로 동작한다.

• watch 메서드를 통해 리소스 변경 이벤트를 실시간 감지
• Application Controller는 Application 리소스와 Kubernetes 리소스를 모두 감시

Git의 변경 감지

• Controller는 Git 저장소에서 일정 시간마다 polling하거나 webhook을 통해 소스 코드 변경을 감지
• Git의 commit hash가 바뀌면, 렌더링 결과가 달라질 수 있으므로 다시 동기화를 수행

클러스터 상태의 변경 감지

• Controller는 Informer를 사용해 Kubernetes API 서버로부터 리소스 상태를 실시간으로 구독
• 클러스터의 리소스(예: Deployment, Service 등)가 변경되면 diff가 발생하고 OutOfSync 상태로 표시

즉, "Application 리소스"는 선언적 정의이고, "Application Controller"는 이 선언적 정의와 실제 상태를 비교하고 차이가 나면 자동으로 맞춰주는 역할을 한다.

예시

• 사용자가 Argo CD에 새로운 Application을 생성 (예: my-app)
• Controller가 이를 감지하고 Git 저장소에서 매니페스트들을 가져와 렌더링
• 현재 클러스터 상태와 비교
• 다르면 동기화 수행 → kubectl apply와 같은 방식으로 리소스를 생성/수정

Repository Server에서 선언적 리소스 렌더링

• Controller는 argocd-repo-server에 gRPC 요청을 보내 Git 저장소에서 리소스를 가져오고 매니페스트를 렌더링하라고 지시
• repo-server는 다음 단계를 수행
  • 지정된 Git 저장소에서 targetRevision 브랜치를 clone (로컬 디스크에 캐시)
  • path 디렉토리로 이동
  • Helm, Kustomize, Ksonnet, Jsonnet 등으로 템플릿 처리 수행
  • 결과: Kubernetes 매니페스트(YAML 리소스 리스트)

Application Controller가 Live State와 Desired State 비교

• Controller는 현재 클러스터 상태(Live State)를 Informer를 통해 수집
• repo-server가 렌더링한 결과(Desired State)와 비교(diff)하여 다음을 판단
  • 어떤 리소스가 누락되었는가?
  • 어떤 리소스가 수정되었는가?
  • 어떤 리소스를 삭제해야 하는가?

비교는 YAML 수준에서 수행되며, 리소스 종류별로 특정 필드(metadata, spec, status)를 구분하여 처리한다.

동기화 수행 (kubectl apply와 유사)

• 사용자가 수동으로 argocd app sync 명령을 호출하거나, 애플리케이션이 자동 동기화(auto-sync) 설정이 되어 있는 경우 동기화가 시작된다.
• Controller는 kubectl apply와 유사한 방식으로 필요한 리소스를 생성/수정/삭제

Redis에 상태 캐시 및 메트릭 기록

• 동기화 결과 및 현재 상태는 Redis에 캐시됩니다. 이는 다음에 동일한 Git SHA를 사용할 때 속도를 개선한다.
• 또한 상태 및 이벤트 메트릭은 Prometheus 형식으로 노출되어, Grafana 등으로 시각화 가능

Web UI 또는 CLI에서 실시간 상태 확인

• 사용자는 CLI(argocd app get, argocd app diff) 또는 Web UI를 통해 다음을 확인할 수 있다.
  • 각 리소스의 배포 여부
  • 상태(Healthy, Degraded 등)
  • 동기화 상태(Synced, OutOfSync 등)
  • 오류 발생 시 로그 및 이벤트

이 모든 정보는 Controller의 상태 계산 결과와 Redis 캐시를 바탕으로 API 서버가 응답한다.

Webhook 또는 Polling을 통한 Git 변경 감지

Argo CD는 Git 저장소의 변경을 두 가지 방식 중 하나로 감지할 수 있다.

• Webhook: GitHub/GitLab/Bitbucket의 webhook을 사용해 push 이벤트를 Argo CD에 전달
• Polling: 일정 주기로 Git 저장소를 polling 하여 변경 감지

변경이 감지되면 Application Controller가 즉시 해당 Application을 다시 평가하고, auto-sync가 활성화되어 있다면 자동으로 재배포하게 된다.