🏗️ Argo CD 아키텍처 깊이 파헤치기: 주요 CR과 관계도 완벽 가이드

안녕하세요! Kubernetes에서 GitOps를 실현할 때 우리에게 가장 친숙한 도구는 단연 Argo CD입니다. 하지만 대시보드 너머에서 실제로 어떤 리소스들이 움직이고 있는지 정확히 파악하는 것은 또 다른 영역이죠.

오늘은 Argo CD의 핵심을 이루는 Custom Resources(CR)들을 살펴보고, 이들이 클러스터 내부에서 어떻게 연결되어 '선언적 배포'를 완성하는지 상세히 알아보겠습니다. 🛠️

---

1. 🌟 Argo CD의 4대 핵심 커스텀 리소스 (CR)

Argo CD 설치 시 클러스터에는 여러 개의 CRD가 생성됩니다. 그중 운영자가 반드시 알아야 할 핵심 리소스는 다음 4가지입니다.

① Application (가장 핵심!)

사용자가 정의한 '소스(Git)'와 '대상(Cluster)'을 연결하는 최소 단위입니다.

• 역할: 어떤 리포지토리의 어떤 경로에 있는 매니페스트를 어느 클러스터의 네임스페이스에 배포할지 정의합니다.

② AppProject (논리적 그룹)

Application들을 묶어주는 거버넌스 및 보안 경계입니다.

• 역할: 멀티 테넌시 환경에서 팀별로 접근 가능한 리포지토리, 대상 클러스터, 리소스 종류를 제한합니다.

③ ApplicationSet (자동화의 꽃)

여러 개의 Application을 패턴에 따라 동적으로 생성해 주는 템플릿 엔진입니다.

• 역할: "모든 리전에 이 앱을 배포해줘" 혹은 "Git의 모든 폴더를 각각의 앱으로 만들어줘" 같은 요구사항을 처리합니다.

④ ArgoCD (인스턴스 관리)

Argo CD 연산자(Operator)를 통해 설치했을 때 나타나는 리소스로, Argo CD 자체의 설정을 담당합니다.

---

2. 🧬 리소스 간의 관계 (Relationship)

이 리소스들은 독립적으로 존재하지 않고 톱니바퀴처럼 맞물려 돌아갑니다.

• AppProject ↔ Application: 모든 Application은 반드시 하나의 AppProject에 속해야 합니다. 프로젝트는 부모와 같은 역할을 하며 자식인 앱의 권한을 통제합니다.
• ApplicationSet ↔ Application: ApplicationSet은 일종의 '붕어빵 틀'입니다. 설정된 Generator(패턴)에 따라 여러 개의 Application 리소스를 자동으로 찍어냅니다.
• Application ↔ Kubernetes Resources: Application이 싱크(Sync)되면, 비로소 실제 Deployment, Service 같은 표준 쿠버네티스 리소스들이 생성됩니다.

---

3. 💻 실전 코드와 상세 설명

각 리소스의 YAML 구조를 보며 실무에서 어떻게 설정하는지 살펴보겠습니다.

📜 AppProject: 보안과 경계 설정

먼저 앱들이 담길 '그릇'인 프로젝트를 만듭니다.

YAML

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: platform-team-project
  namespace: argocd
spec:
  description: "플랫폼 팀 전용 프로젝트"
  # 1. 허용할 Git 리포지토리 제한 📦
  sourceRepos:
    - "https://github.com/my-org/platform-infra.git"
  # 2. 배포 가능한 대상 클러스터 및 네임스페이스 지정 🎯
  destinations:
    - server: "https://kubernetes.default.svc"
      namespace: "production-*"
  # 3. 배포 가능한 리소스 종류 제한 (보안 강화) 🛡️
  clusterResourceWhitelist:
    - group: ""
      kind: Namespace

📜 Application: 소스와 대상의 매핑

가장 많이 사용하게 될 리소스입니다.

YAML

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook-app
  namespace: argocd
spec:
  # 어떤 프로젝트에 속할지 지정 (위에서 만든 프로젝트)
  project: platform-team-project
  source:
    repoURL: "https://github.com/my-org/platform-infra.git"
    targetRevision: HEAD
    path: "guestbook" # Git 내부 경로
  destination:
    server: "https://kubernetes.default.svc"
    namespace: "production-apps"
  # 자동 동기화 정책 설정 🔄
  syncPolicy:
    automated:
      prune: true     # Git에서 삭제되면 클러스터에서도 삭제
      selfHeal: true  # 클러스터에서 수동 수정 시 다시 되돌림

📜 ApplicationSet: 대규모 배포 자동화

여러 클러스터나 여러 폴더를 한 번에 관리할 때 사용합니다.

YAML

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: microservices-set
  namespace: argocd
spec:
  # 1. 생성 패턴 정의 (여기서는 List 사용) 📋
  generators:
    - list:
        elements:
          - cluster: engineering-dev
            url: https://1.2.3.4
          - cluster: engineering-prod
            url: https://5.6.7.8
  # 2. 실제 생성될 Application의 템플릿 🏗️
  template:
    metadata:
      name: '{{cluster}}-guestbook' # 변수 치환
    spec:
      project: default
      source:
        repoURL: https://github.com/argoproj/argocd-example-apps.git
        targetRevision: HEAD
        path: guestbook
      destination:
        server: '{{url}}'
        namespace: guestbook

---

4. 🔍 심화: 리소스 간의 생명 주기와 의존성

우리가 이전에 논의했던 내용들을 바탕으로 실무에서 주의해야 할 점을 정리해 보겠습니다.

1. Cascading Delete (폭포수 삭제): Application을 삭제할 때 실제 배포된 리소스들도 같이 삭제할지 결정할 수 있습니다. finalizers 설정을 통해 제어합니다.
2. Project-level RBAC: AppProject 내에 정의된 Role은 argocd-rbac-cm과 연동되어 특정 팀이 자신들의 프로젝트만 볼 수 있게 만듭니다.
3. Status Sync: Application CR 내부의 status 필드는 현재 Git과 클러스터 사이의 차이점(Diff)과 헬스 상태를 실시간으로 저장합니다.

---

📝 요약 테이블

리소스명	주요 역할	비유
AppProject	권한 제어, 리소스 제한	울타리, 관리 구역
Application	1개 앱의 배포 정의	실제 배포 명세서
ApplicationSet	동적/대량 앱 생성	붕어빵 틀
ArgoCD	Argo CD 설정 제어	관제탑 설정

---

💡 마치며

Argo CD의 CR 구조를 이해하는 것은 안정적인 GitOps 운영의 첫걸음입니다. 특히 ApplicationSet과 AppProject의 관계를 잘 설계하면, 수백 개의 마이크로서비스를 단 몇 줄의 코드로 안전하게 관리할 수 있습니다. 🎯

여러분의 클러스터에도 이러한 구조적 설계를 적용하여 더 단단한 인프라를 구축해 보세요!

---