[Ep.9] [Argo CD 운영 #4] Argo CD에서 애플리케이션을 정의하는 YAML 구조 분석

🔹 Argo CD에서 애플리케이션을 정의하는 방법

Argo CD는 **Application CRD(Custom Resource Definition)**를 통해 애플리케이션을 선언적으로 관리합니다.
즉, YAML 매니페스트를 작성하여 Git 저장소와 Kubernetes 클러스터 간의 동기화를 설정할 수 있습니다.

이번 글에서는 Argo CD 애플리케이션을 정의하는 YAML의 주요 구조와 설정 옵션을 분석하고,
각 항목이 어떤 역할을 수행하는지 상세히 설명하겠습니다.

---

🔹 Argo CD 애플리케이션 YAML의 주요 구성 요소

Argo CD에서 애플리케이션을 정의하는 YAML은 다음과 같은 주요 섹션으로 구성됩니다.

1️⃣ 메타데이터(metadata) → 애플리케이션의 이름 및 네임스페이스 설정
2️⃣ 사양(spec) → 애플리케이션의 원격 저장소, 대상 클러스터, 동기화 정책 등을 설정
3️⃣ 소스(source) → Git 저장소, Helm 차트, Kustomize 등의 배포 방식 정의
4️⃣ 대상(destination) → 애플리케이션이 배포될 Kubernetes 클러스터 및 네임스페이스 지정
5️⃣ 동기화 정책(syncPolicy) → 자동 동기화 여부 및 리소스 정리 정책 설정

---

🔹 Argo CD 애플리케이션 YAML 예제 분석

아래는 Helm 기반 애플리케이션을 Argo CD에서 관리하는 YAML 예제입니다.

apiVersion: argoproj.io/v1alpha1  # Argo CD의 API 버전 지정
kind: Application  # 애플리케이션 리소스 선언
metadata:
  name: example-app  # 애플리케이션 이름
  namespace: argocd  # Argo CD가 관리하는 네임스페이스
spec:
  project: default  # Argo CD에서 관리하는 프로젝트 지정

  source:  # 소스(Git 저장소 또는 Helm 차트) 설정
    repoURL: https://github.com/example/repo.git  # Git 저장소 URL
    targetRevision: main  # 사용할 브랜치 또는 태그
    path: charts/example  # Helm 차트 또는 매니페스트가 위치한 디렉터리
    helm:
      valueFiles:  # Helm 차트의 values 파일 지정
        - values.yaml
        - values-production.yaml

  destination:  # Kubernetes 클러스터 및 네임스페이스 지정
    server: https://kubernetes.default.svc  # 기본 클러스터(Kubernetes API 서버)
    namespace: example-namespace  # 애플리케이션이 배포될 네임스페이스

  syncPolicy:  # 동기화 정책 정의
    automated:
      prune: true  # Git에서 삭제된 리소스를 Kubernetes에서도 삭제
      selfHeal: true  # Kubernetes 리소스가 변경되었을 경우 원래 상태로 자동 복구
    syncOptions:
      - CreateNamespace=true  # 네임스페이스가 없으면 자동 생성
      - PrunePropagationPolicy=foreground  # Prune 동작 방식 설정
      - PruneLast=true  # 삭제 작업을 마지막에 실행

---

🔹 YAML 주요 항목 상세 분석

✅ 1. metadata: 애플리케이션의 기본 정보

metadata:
  name: example-app  # 애플리케이션 이름
  namespace: argocd  # Argo CD 네임스페이스

• name → Argo CD에서 관리할 애플리케이션의 이름
• namespace → Argo CD가 실행되는 네임스페이스 (기본값: argocd)

---

✅ 2. spec.project: 애플리케이션이 속한 프로젝트

spec:
  project: default  # Argo CD에서 관리하는 프로젝트 이름

• Argo CD에서 애플리케이션을 그룹화할 때 사용하는 프로젝트
• 기본적으로 default 프로젝트를 사용하지만, 필요에 따라 다른 프로젝트를 생성할 수도 있음

---

✅ 3. source: 애플리케이션의 소스 코드 저장소

source:
  repoURL: https://github.com/example/repo.git  # Git 저장소 URL
  targetRevision: main  # 사용할 브랜치 또는 태그
  path: charts/example  # Helm 차트 또는 매니페스트가 위치한 디렉터리

• repoURL → Git 저장소의 URL
• targetRevision → 사용할 Git 브랜치(main, develop) 또는 특정 태그
• path → Git 저장소 내에서 매니페스트 파일이 위치한 디렉터리

🚀 Helm을 사용하는 경우
Helm 차트를 사용하는 경우, helm 옵션을 추가하여 values 파일을 지정할 수 있습니다.

helm:
  valueFiles:
    - values.yaml
    - values-production.yaml

---

✅ 4. destination: 애플리케이션이 배포될 Kubernetes 클러스터

destination:
  server: https://kubernetes.default.svc  # 기본 클러스터(Kubernetes API 서버)
  namespace: example-namespace  # 애플리케이션이 배포될 네임스페이스

• server → 애플리케이션이 배포될 Kubernetes 클러스터 주소
  • https://kubernetes.default.svc: 기본 클러스터 (Argo CD와 동일한 클러스터)
  • 다른 클러스터를 사용할 경우, 해당 클러스터의 API 서버 주소 입력
• namespace → 애플리케이션이 배포될 네임스페이스

---

✅ 5. syncPolicy: 애플리케이션 동기화 정책 설정

syncPolicy:
  automated:
    prune: true  # Git에서 삭제된 리소스를 Kubernetes에서도 삭제
    selfHeal: true  # Kubernetes 리소스가 변경되었을 경우 원래 상태로 자동 복구
  syncOptions:
    - CreateNamespace=true  # 네임스페이스가 없으면 자동 생성
    - PrunePropagationPolicy=foreground  # Prune 동작 방식 설정
    - PruneLast=true  # 삭제 작업을 마지막에 실행

• 자동 동기화 옵션
  • prune: true → Git에서 삭제된 리소스를 Kubernetes에서도 삭제
  • selfHeal: true → 수동 변경된 리소스를 Git 상태로 자동 복구
• 추가 동기화 옵션
  • CreateNamespace=true → 네임스페이스가 없으면 자동 생성
  • PrunePropagationPolicy=foreground → 리소스 삭제 순서 지정
  • PruneLast=true → 삭제 작업을 마지막에 실행

---

🔹 Argo CD CLI를 활용한 애플리케이션 생성

YAML 없이 CLI를 사용하여 애플리케이션을 생성할 수도 있습니다.

argocd app create example-app \
  --repo https://github.com/example/repo.git \
  --path charts/example \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace example-namespace \
  --sync-policy automated

이 명령어는 위에서 설명한 YAML과 동일한 역할을 수행합니다.

🔹 프로젝트가 없을 경우 자동 생성하는 Application & AppProject YAML

# 📌 Argo CD에서 프로젝트(AppProject)와 애플리케이션(Application)을 동시에 생성하는 매니페스트
#    - 'database' 프로젝트가 없으면 자동으로 생성
#    - 'chromadb' 애플리케이션을 배포
#    - 프로젝트가 이미 존재하면 기존 설정을 유지한 채 애플리케이션을 배포

---
apiVersion: argoproj.io/v1alpha1  # Argo CD의 API 버전 지정
kind: AppProject  # Argo CD 프로젝트 리소스 정의
metadata:
  name: database  # 프로젝트 이름 (이름이 'database'인 프로젝트 생성)
  namespace: argocd  # Argo CD가 배포되는 네임스페이스 (기본적으로 'argocd' 사용)
spec:
  description: "Project for managing database applications"  # 프로젝트 설명
  sourceRepos:
    - "*"  # 이 프로젝트에서 관리할 수 있는 Git 저장소 (모든 저장소 허용)
  destinations:
    - namespace: database  # 애플리케이션이 배포될 네임스페이스 ('database' 네임스페이스)
      server: https://kubernetes.default.svc  # 배포 대상 Kubernetes 클러스터 (기본 클러스터)
  clusterResourceWhitelist:
    - group: "*"  # 모든 API 그룹의 리소스를 허용
      kind: "*"  # 모든 종류의 리소스를 허용 (예: Deployments, Services 등)
  namespaceResourceWhitelist:
    - group: "*"  # 모든 네임스페이스 리소스 허용
      kind: "*"  # 모든 종류의 네임스페이스 리소스 허용
  roles:
    - name: admin  # 'database' 프로젝트에 대한 관리(Admin) 역할 생성
      description: "Admin access to the database project"  # 역할 설명
      policies:
        - "p, proj:database:admin, applications, *, database/*, allow"  
          # 이 프로젝트 내의 모든 애플리케이션을 관리할 수 있도록 권한 부여

---

apiVersion: argoproj.io/v1alpha1  # Argo CD의 API 버전 지정
kind: Application  # Argo CD에서 관리하는 애플리케이션 리소스 정의
metadata:
  name: chromadb  # 애플리케이션 이름 (Argo CD UI 및 CLI에서 표시됨)
  namespace: argocd  # 애플리케이션이 생성될 네임스페이스 (Argo CD가 관리)
spec:
  project: database  # 위에서 생성한 'database' 프로젝트를 사용

  source:
    repoURL: https://github.com/ch0992/gitops.git  # 애플리케이션이 배포될 Git 저장소
    targetRevision: HEAD  # Git 저장소에서 사용할 브랜치 또는 태그 (HEAD는 최신 상태를 의미)
    path: argocd/chromadb/helm  # Git 저장소 내에서 매니페스트 또는 Helm 차트가 위치한 디렉터리

  destination:
    server: https://kubernetes.default.svc  # Kubernetes API 서버 (기본 클러스터)
    namespace: database  # 애플리케이션이 배포될 네임스페이스

  syncPolicy:  # Argo CD의 동기화 정책 정의
    automated:
      prune: true  # Git 저장소에서 삭제된 리소스를 Kubernetes에서도 삭제
      selfHeal: true  # Kubernetes 리소스가 변경되었을 경우 Git 상태로 자동 복구
    syncOptions:
      - CreateNamespace=true  # 네임스페이스(database)가 없으면 자동으로 생성

---

✅ 주요 설명

🔹 1️⃣ 프로젝트 생성 (AppProject)

• AppProject 리소스를 사용하여 database 프로젝트를 생성합니다.

• 이 프로젝트를 통해 애플리케이션을 그룹화하고 접근 제어를 수행할 수 있습니다.

• sourceRepos: ["*"] → 모든 Git 저장소에서 소스를 허용합니다.

• destinations: ["database"] → database 네임스페이스에 배포를 허용합니다.

• roles: → 프로젝트 수준에서 애플리케이션 관리 권한을 설정할 수 있습니다.

---

🔹 2️⃣ 애플리케이션 정의 (Application)

• chromadb 애플리케이션을 database 프로젝트 내에서 관리하도록 설정합니다.

• repoURL → GitOps 방식을 사용하여 애플리케이션 매니페스트를 관리합니다.

• path → Helm 차트 또는 Kubernetes 매니페스트가 위치한 Git 저장소 경로를 지정합니다.

• destination → 애플리케이션이 배포될 Kubernetes 클러스터와 네임스페이스를 설정합니다.

• syncPolicy → 애플리케이션의 자동 동기화 정책을 설정하여 GitOps를 강화합니다.

---

🚀 적용 방법

위 YAML을 적용하려면 kubectl apply -f 명령어를 실행합니다.

kubectl apply -f application.yaml

💡 예상 출력 값

appproject.argoproj.io/database created
application.argoproj.io/chromadb created

---

🔹 결론: 이번 글에서 배운 핵심 내용 정리

🟢 Argo CD 애플리케이션은 Application CRD를 통해 정의되며, GitOps 원칙에 따라 동작
🟢 YAML 매니페스트에서 metadata, source, destination, syncPolicy를 설정하여 배포를 자동화 가능
🟢 Helm, Kustomize 등의 다양한 배포 방식을 지원하며, CLI를 사용해 애플리케이션을 생성할 수도 있음
🟢 자동 동기화(Automated Sync) 및 Prune 옵션을 활용하여 Kubernetes 리소스의 상태를 유지 가능