ArgoCD는 Kubernetes 네이티브 GitOps CD(지속적 배포) 도구입니다. 애플리케이션 정의, 설정, 환경을 Git 저장소에 선언적으로 관리하고, 클러스터 상태를 Git에 정의된 desired state와 지속적으로 동기화합니다.
Git에 push만 하면 ArgoCD가 자동으로 클러스터에 반영. drift(차이) 발생 시 즉시 복구.
애플리케이션 상태, 동기화 이력, 리소스 트리를 직관적으로 시각화.
여러 K8s 클러스터를 하나의 ArgoCD로 관리. 프로젝트 단위 권한 제어.
기존 CI/CD 도구(Jenkins, Spinnaker, Flux 등)와 비교한 ArgoCD의 차별점:
| 비교 항목 | ArgoCD | Jenkins | Flux | Spinnaker |
|---|---|---|---|---|
| GitOps 네이티브 | ✅ 핵심 | ❌ 플러그인 필요 | ✅ | ❌ |
| Web UI | ✅ 매우 풍부 | ✅ 기본 | ❌ CLI 중심 | ✅ |
| 멀티 클러스터 | ✅ 기본 지원 | ❌ 까다로움 | ✅ | ✅ |
| 자동 동기화(Drift) | ✅ 강력 | ❌ 수동 | ✅ | ❌ |
| 선언적 설정 | ✅ K8s CRD | ❌ 스크립트 | ✅ | ❌ |
결론: GitOps 기반 CD가 필요한 팀, 특히 멀티 클러스터 운영과 Git을 단일 진실 공급원으로 활용하려는 조직에 ArgoCD가 가장 적합합니다.
ArgoCD의 주요 구성 요소:
ArgoCD는 Git 저장소를 주기적으로 polling하거나 webhook으로 변경을 감지하고, 현재 클러스터 상태와 차이를 계산하여 자동 또는 수동으로 동기화합니다.
ArgoCD를 설치하고 첫 번째 애플리케이션을 배포해보겠습니다.
kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml# CLI 다운로드 (Linux/macOS)
curl -sSL -o /usr/local/bin/argocd https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
chmod +x /usr/local/bin/argocd
# 초기 admin 비밀번호 확인
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -dGit 저장소에 배포할 manifest를 준비합니다. Python 스크립트로 ArgoCD API를 호출하여 애플리케이션을 생성할 수도 있습니다.
# Python: ArgoCD API를 사용한 Application 생성 (예시)
import requests
import json
argocd_server = "https://localhost:8080"
token = "your-argocd-token" # argocd account generate-token
app_manifest = {
"apiVersion": "argoproj.io/v1alpha1",
"kind": "Application",
"metadata": {"name": "my-app", "namespace": "argocd"},
"spec": {
"project": "default",
"source": {
"repoURL": "https://github.com/your-org/your-repo.git",
"targetRevision": "HEAD",
"path": "k8s-manifests"
},
"destination": {
"server": "https://kubernetes.default.svc",
"namespace": "default"
},
"syncPolicy": {"automated": {"prune": True, "selfHeal": True}}
}
}
headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
resp = requests.post(f"{argocd_server}/api/v1/applications",
headers=headers, data=json.dumps(app_manifest), verify=False)
print(resp.status_code, resp.json())⚠️ 보안 주의: 위 예제는 로컬 테스트용입니다. 프로덕션에서는 인증서 검증, 토큰 관리, 네트워크 정책을 반드시 설정하세요.
또는 CLI로 간편하게 생성:
argocd app create my-app \
--repo https://github.com/your-org/your-repo.git \
--path k8s-manifests \
--dest-server https://kubernetes.default.svc \
--dest-namespace default \
--sync-policy automated자주 사용되는 Application spec 및 Project spec 필드:
| 필드 | 타입 | 설명 |
|---|---|---|
spec.source.repoURL | string | Git 저장소 URL |
spec.source.path | string | manifest가 위치한 디렉토리 경로 |
spec.source.targetRevision | string | 브랜치, 태그, 커밋 SHA |
spec.destination.server | string | 대상 K8s API 서버 (멀티 클러스터 시 중요) |
spec.destination.namespace | string | 배포할 네임스페이스 |
spec.syncPolicy.automated | object | {prune, selfHeal, allowEmpty} 등 자동 동기화 설정 |
spec.project | string | 소속 Project (RBAC 적용) |
spec.ignoreDifferences | array | 특정 리소스 필드의 diff 무시 (예: secrets 데이터) |
Project CRD 예시:
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: data-team
namespace: argocd
spec:
description: "Data engineering project"
sourceRepos:
- 'https://github.com/your-org/data-*'
destinations:
- namespace: 'data-*'
server: 'https://kubernetes.default.svc'
clusterResourceWhitelist:
- group: '*'
kind: 'Namespace'원인: 잘못된 manifest, 네트워크 문제, 권한 부족.
해결: argocd app get my-app로 상태 확인, argocd app logs로 상세 로그 조회. Git 저장소 접근 권한 확인.
문제: Secrets 등 자동 변경되는 리소스가 계속 동기화 트리거.
해결: spec.ignoreDifferences에 jsonPointer나 managedFields 등을 추가.
원인: GitHub/GitLab webhook 설정 미비, ArgoCD 서버 접근 불가.
해결: argocd-server에 Ingress 또는 LoadBalancer로 외부 접근 허용, webhook secret 확인.
💡 Pro Tip: argocd app sync --prune --force는 위험할 수 있으므로, 운영 환경에서는 --dry-run 먼저 사용하세요.
자주 사용하는 진단 명령어:
# 애플리케이션 상태
argocd app get my-app -o yaml
# 동기화 상태 및 이벤트
argocd app logs my-app --since=5m
# 리소스 트리 (UI에서도 가능)
argocd app resources my-app
# 비교 결과
argocd app diff my-app