liminfoArgoCD Reference
ArgoCD CLI, Application 매니페스트, Sync 정책 레퍼런스
ArgoCD Reference 소개
ArgoCD 레퍼런스는 ArgoCD의 주요 개념을 5개 카테고리로 정리한 검색 가능한 치트 시트입니다. CRD(Application, AppProject, ApplicationSet), 동기화 정책(automated sync prune/selfHeal, manual sync, sync wave, retry backoff), 훅(PreSync DB 마이그레이션, Sync, PostSync 테스트/알림, SyncFail 롤백), 인증(RBAC policy.csv, OIDC/Dex SSO GitHub 연동), CLI(argocd app create, sync, diff, get, delete, cluster add)를 모두 다룹니다.
이 레퍼런스는 ArgoCD로 GitOps 워크플로우를 구현하는 플랫폼 엔지니어, DevOps 팀, Kubernetes 개발자를 위해 설계되었습니다. Helm 차트를 가리키는 Application CRD 정의, Git 디렉토리 트리에서 앱을 자동 생성하는 ApplicationSet 구성, 개발자는 sync는 가능하지만 삭제는 불가한 RBAC 설정 등 실무에 필요한 YAML 애너테이션과 CLI 플래그를 즉시 찾을 수 있습니다.
ArgoCD의 선언적 GitOps 모델에서는 세부 설정 하나하나가 중요합니다. "prune: true" 누락은 고아 리소스를 남기고, sync wave 순서는 데이터베이스 먼저 배포하는 데 필수적입니다. 5개 카테고리는 앱 정의, 동기화 제어, 수명 주기 훅, 접근 보안, CLI 운영이라는 일상적인 운영 관심사를 반영합니다. 브라우저 기반으로 무료이며 다크 모드를 지원합니다.
주요 기능
- Application CRD: repoURL, path, targetRevision, 목적지 서버 및 네임스페이스를 포함한 전체 YAML 스펙
- AppProject: 멀티팀 접근 제어를 위한 destination 및 sourceRepos 제한
- ApplicationSet: 디렉토리마다 Application을 자동 생성하는 Git 디렉토리 생성기
- 자동 동기화: 고아 리소스 prune, drift selfHeal, allowEmpty 플래그
- Sync wave: 리소스 생성 순서를 지정하는 argocd.argoproj.io/sync-wave 애너테이션
- Sync 재시도 정책: 탄력적 배포를 위한 limit, backoff duration, factor, maxDuration 설정
- 수명 주기 훅: PreSync(DB 마이그레이션), Sync, PostSync(스모크 테스트), SyncFail(롤백) 및 hook-delete-policy
- RBAC 및 SSO: policy.csv 역할 정의와 GitHub SSO를 위한 Dex OIDC 커넥터 설정
자주 묻는 질문
ArgoCD의 Application CRD란 무엇인가요?
Application CRD는 ArgoCD의 핵심 리소스로, 소스(Git 저장소 URL, 경로, 대상 리비전)와 목적지(Kubernetes 클러스터 API 서버와 네임스페이스)를 정의합니다. ArgoCD는 라이브 클러스터 상태를 Git에 선언된 상태와 지속적으로 비교하여 Synced/OutOfSync 상태를 보고합니다.
자동 동기화와 수동 동기화의 차이는 무엇인가요?
자동 동기화는 Git 변경을 감지하면 클러스터에 자동으로 적용합니다. "prune: true"는 Git에서 삭제된 리소스를 제거하고, "selfHeal: true"는 수동 클러스터 변경을 Git 선언 상태로 복원합니다. 수동 동기화는 "argocd app sync myapp" 실행 또는 UI에서 Sync를 클릭할 때만 적용됩니다.
Sync wave는 무엇이며 왜 중요한가요?
Sync wave는 동기화 중 리소스 적용 순서를 제어합니다. "argocd.argoproj.io/sync-wave: \"1\""으로 wave를 지정하면 ArgoCD가 낮은 번호의 wave를 먼저 적용하고 상태 검사를 통과한 뒤 다음 wave로 진행합니다. 예를 들어 데이터베이스 Deployment가 정상 상태가 된 후 애플리케이션 Deployment가 시작되도록 보장할 수 있습니다.
PreSync와 PostSync 훅은 어떻게 동작하나요?
PreSync 훅은 리소스 적용 전에 실행되어 DB 스키마 마이그레이션에 적합합니다. PostSync 훅은 모든 리소스가 정상 상태가 된 후 실행되어 통합 테스트나 Slack 알림에 사용됩니다. SyncFail 훅은 동기화 실패 시에만 실행되어 자동 롤백이나 알림에 활용됩니다. "hook-delete-policy: HookSucceeded"로 완료된 Job을 정리할 수 있습니다.
개발자가 sync는 할 수 있지만 애플리케이션을 삭제하지 못하게 RBAC을 설정하는 방법은?
policy.csv에 "p, role:developer, applications, sync, */*, allow"로 sync 권한을, "p, role:developer, applications, get, */*, allow"로 읽기 권한을 부여합니다. "g, my-team, role:developer"로 팀을 역할에 바인딩합니다. delete 권한을 추가하지 않으면 개발자는 애플리케이션을 삭제할 수 없습니다.
ApplicationSet은 언제 사용하나요?
ApplicationSet은 생성기를 사용하여 여러 Application 리소스를 자동으로 생성합니다. Git 디렉토리 생성기는 저장소의 디렉토리를 스캔하여 각 디렉토리마다 ArgoCD Application을 하나씩 생성합니다. 각 Application을 수동으로 정의하지 않고도 일관된 GitOps 설정이 필요한 멀티 클러스터 또는 멀티 환경 배포에 적합합니다.
CLI로 라이브 클러스터 상태와 Git 상태를 비교하려면?
"argocd app diff myapp"으로 다음 동기화 시 ArgoCD가 적용할 변경 사항을 확인합니다. "--local ./k8s/"를 사용하면 Git 대신 로컬 매니페스트와 비교할 수 있습니다. 특히 프로덕션 환경에서 동기화 전 변경 사항을 미리 확인하는 데 유용합니다.
외부 Kubernetes 클러스터를 ArgoCD에 추가하는 방법은?
대상 클러스터 컨텍스트가 구성된 머신에서 "argocd cluster add <kubectl-context-name>"을 실행합니다. ArgoCD가 대상 클러스터에 서비스 계정을 설치하고 자격 증명을 argocd-cm에 저장합니다. 이후 Application CRD의 destination에 해당 클러스터를 지정할 수 있습니다.