🏗️ Argo CD 아키텍처 완벽 해부: GitOps의 심장부를 들여다보다

안녕하세요! Kubernetes 환경에서 선언적 지속 배포(Declarative CD)를 가능하게 하는 Argo CD. 단순히 "Git에 올리면 배포된다"는 결과 뒤에는 매우 정교하게 설계된 마이크로서비스 아키텍처가 숨어 있습니다.

오늘 이 시간에는 Argo CD를 구성하는 주요 컴포넌트들과 그들 사이의 데이터 흐름, 그리고 왜 이런 구조로 설계되었는지에 대해 깊이 있게 알아보겠습니다. 🛠️

https://argo-cd.readthedocs.io/en/stable/operator-manual/architecture/

---

1. 🌐 Argo CD 아키텍처 개요 (High-level View)

Argo CD는 크게 세 가지 주요 서비스로 구성된 마이크로서비스 아키텍처입니다. 각 서비스는 독립적인 역할을 수행하며, 클러스터 내부에서 유기적으로 통신합니다.

핵심 구성 요소

1. API Server: 사용자와 외부 도구의 관문
2. Repository Server (Repo Server): 소스 코드(Git) 관리의 중심
3. Application Controller: 클러스터 상태를 감시하는 뇌

---

2. 🚦 API Server: 관문과 보안

API Server는 사용자(UI/CLI)나 외부 시스템(CI 도구)이 Argo CD와 대화하는 유일한 창구입니다. gRPC/REST 서버로 구현되어 있습니다.

• 인증 및 인가 (AuthN/AuthZ): 사용자가 누구인지 확인하고, argocd-rbac-cm에 정의된 대로 권한을 체크합니다.
• 애플리케이션 관리: 애플리케이션 생성, 수정, 삭제 요청을 처리합니다.
• RBAC 적용: 특정 프로젝트(AppProject)에 대한 접근 제어를 수행합니다.

💡 팁: 우리가 이전에 다뤘던 Scoped Token 역시 이 API Server가 검증하고 처리하는 핵심 보안 요소입니다.

---

3. 📂 Repository Server: 소스의 진실 (Source of Truth)

Repository Server는 내부 캐시를 유지하며 Git 리포지토리의 매니페스트를 관리합니다.

• 매니페스트 생성: Git에 있는 Helm, Kustomize, 혹은 생 YAML 파일을 Argo CD가 이해할 수 있는 순수 Kubernetes 객체로 렌더링합니다.
• 캐싱 엔진: 매번 Git에서 가져오면 느리기 때문에, 변경 사항이 없을 때는 로컬 캐시를 활용해 성능을 극대화합니다.
• Kustomize/Helm 지원: 앞서 논의했던 kustomize.path 설정 등을 통해 특정 바이너리 버전으로 렌더링 작업을 수행하는 곳이 바로 여기입니다.

💻 (참고) Repo Server 커스텀 설정 예시

앞서 배운 InitContainer 기법을 통해 Repo Server에 Helm 레포를 사전 등록하는 설정의 아키텍처적 위치를 확인하세요.

YAML

 

# argocd-repo-server는 렌더링을 위해 외부 Helm 레포와 통신할 준비가 되어 있어야 합니다.
containers:
- name: argocd-repo-server
  env:
  - name: ARGOCD_REPO_SERVER_HELM_BIN
    value: "/usr/local/bin/kustomize-v5" # 커스텀 바이너리 사용 시

---

4. 🧠 Application Controller: 상태의 수호자

이 컴포넌트가 바로 Argo CD의 '뇌'이자 GitOps의 핵심 엔진입니다.

• 지속적 감시 (Continuous Monitoring): 현재 실행 중인 클러스터의 상태(Live State)와 Git에 정의된 상태(Desired State)를 끊임없이 비교합니다.
• 상태 판단 (Health Assessment): 우리가 argocd-cm에서 정의했던 resource.customizations.health 루아 스크립트가 실행되는 곳이 여기입니다.
• 자동 복구 (Self-Healing): 클러스터에서 누군가 수동으로 설정을 바꿨을 때, 다시 Git 상태로 되돌리는 작업을 수행합니다.

---

5. 🔄 데이터의 흐름: 배포가 일어나는 과정

사용자가 Sync 버튼을 눌렀을 때 아키텍처 내부에서 일어나는 일들을 단계별로 살펴봅시다.

1. 사용자 요청: 사용자가 UI/CLI를 통해 API Server에 Sync 명령을 보냅니다.
2. Manifest 요청: API Server는 Repo Server에 "최신 커밋 버전으로 매니페스트 렌더링해줘"라고 요청합니다.
3. 렌더링: Repo Server는 Git에서 코드를 가져와(혹은 캐시에서) Helm/Kustomize를 실행해 최종 YAML을 만듭니다.
4. 비교 및 실행: Application Controller는 전달받은 YAML(Desired)과 현재 클러스터 상태(Live)를 비교하여 변경 사항만 클러스터에 적용(Apply)합니다.
5. 상태 업데이트: 배포가 끝나면 Controller는 최종 상태를 기록하고 UI에 Synced 혹은 Healthy 배지를 표시합니다.

---

6. 🏗️ 고급 아키텍처: HA(High Availability) 구성

운영 환경에서는 서비스 중단을 막기 위해 각 컴포넌트를 고가용성 모드로 운영합니다.

• Redis: Repo Server의 캐시 데이터를 저장하는 외부 저장소 역할을 하여, 여러 개의 Repo Server가 상태를 공유하게 합니다.
• Sharding: 관리하는 클러스터가 수천 개일 경우, Application Controller를 여러 개로 쪼개어(Sharding) 부하를 분산합니다.

💻 Controller Sharding 설정 예시 (argocd-cmd-params-cm)

YAML

 

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cmd-params-cm
data:
  # 컨트롤러 하나가 담당할 클러스터의 수를 제한하여 샤딩을 유도합니다. ⚖️
  controller.replicas: "2"
  controller.cluster.sharding.algorithm: "round-robin"

---

📝 요약 테이블: 아키텍처 컴포넌트 비교

컴포넌트	주요 역할	관련 설정파일	비유
API Server	인증, 인가, API 제공	argocd-rbac-cm	안내 데스크
Repo Server	매니페스트 렌더링, 캐싱	argocd-cm (kustomize)	번역 및 설계국
Controller	상태 비교, 동기화, 복구	argocd-cm (health)	현장 감독관
Redis	데이터 캐싱 공유	-	공동 메모장

---

💡 마치며

Argo CD의 아키텍처는 "상태를 정의하는 곳(Git)"과 "상태를 유지하는 곳(Cluster)" 사이의 간극을 메우기 위해 철저히 분업화되어 있습니다. 이 구조를 이해하면 트러블슈팅이 발생했을 때 어느 컴포넌트의 로그를 봐야 할지 명확해집니다.

• 로그인이 안 된다면? → API Server
• Git 변경 사항이 반영 안 된다면? → Repo Server
• 배포는 됐는데 계속 Progressing이라면? → Application Controller

여러분의 클러스터를 지키는 이 보이지 않는 영웅들의 구조를 이해하는 데 도움이 되셨길 바랍니다! 🎯

---