Argo CD 개념

Argo CD가 Git을 애플리케이션 배포의 단일 정보 원천으로 취급하는 GitOps 구현 방식과, EKS용 Argo CD 캐퍼빌리티를 사용하며 이해해야 할 핵심 개념을 설명합니다.

출처: 문서

본문

Argo CD는 Git을 애플리케이션 배포의 단일 정보 원천으로 취급하는 GitOps를 구현합니다. 이 항목은 실제 예시를 살펴본 후, EKS용 Argo CD 캐퍼빌리티를 사용할 때 이해해야 할 핵심 개념을 설명합니다.

Argo CD 시작하기

Argo CD 캐퍼빌리티를 만든 후(Argo CD 캐퍼빌리티 생성 참고) 애플리케이션 배포를 시작할 수 있습니다. 이 예시는 클러스터 등록과 Application 생성을 안내합니다.

1단계: 설정

클러스터 등록(필수) - 애플리케이션을 배포하려는 클러스터를 등록합니다. 이 예시에서는 Argo CD가 실행되는 것과 같은 클러스터를 등록하겠습니다(대부분의 Argo CD 예시와 호환되도록 in-cluster 이름을 사용할 수 있습니다).

# Get your cluster ARN
CLUSTER_ARN=$(aws eks describe-cluster \
  --name my-cluster \
  --query 'cluster.arn' \
  --output text)

# Register the cluster using Argo CD CLI
argocd cluster add $CLUSTER_ARN \
  --aws-cluster-name $CLUSTER_ARN \
  --name in-cluster \
  --project default

참고

EKS의 Argo CD 캐퍼빌리티와 함께 작동하도록 Argo CD CLI를 구성하는 방법은 관리형 캐퍼빌리티에서 Argo CD CLI 사용하기를 참고하세요.

또는 Kubernetes 시크릿을 사용해 클러스터를 등록할 수도 있습니다(대상 클러스터 등록 참고).

리포지토리 접근 구성(선택) - 이 예시는 공개 GitHub 리포지토리를 사용하므로 리포지토리 구성이 필요하지 않습니다. 프라이빗 리포지토리는 AWS Secrets Manager, CodeConnections 또는 Kubernetes 시크릿을 사용해 접근을 구성하세요(리포지토리 접근 구성 참고).
- AWS 서비스(Helm 차트용 ECR, CodeConnections, CodeCommit)는 Repository를 만들지 않고 Application 리소스에서 직접 참조할 수 있습니다. 캐퍼빌리티 역할에 필요한 IAM 권한이 있어야 합니다. 자세한 내용은 리포지토리 접근 구성을 참고하세요.

2단계: Application 생성

my-app.yaml에 이 Application 매니페스트를 생성합니다.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
    path: guestbook
  destination:
    name: in-cluster
    namespace: guestbook
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true

Application을 적용합니다.

kubectl apply -f my-app.yaml

이 Application을 적용하면 Argo CD는 다음을 수행합니다.

Git에서 클러스터로 애플리케이션을 동기화합니다(초기 배포).
변경 사항을 모니터링하기 위해 Git 리포지토리를 감시합니다.
이후 변경 사항을 클러스터에 자동으로 동기화합니다.
원하는 상태에서 벗어난 드리프트를 감지하고 수정합니다.
UI에서 상태(health)와 동기화 이력을 제공합니다.

애플리케이션 상태를 확인합니다.

kubectl get application guestbook -n argocd

Argo CD CLI 또는 Argo CD UI(클러스터의 Capabilities 탭 아래 EKS 콘솔에서 접근 가능)로도 애플리케이션을 볼 수 있습니다.

참고

관리형 캐퍼빌리티에서 Argo CD CLI를 사용할 때는 네임스페이스 접두사를 포함해 애플리케이션을 지정하세요: argocd app get argocd/guestbook.

참고

destination.name에 클러스터 이름(클러스터 등록 시 사용한 이름)을 사용하세요. 관리형 캐퍼빌리티는 로컬 in-cluster 기본값(kubernetes.default.svc)을 지원하지 않습니다.

핵심 개념

GitOps 원칙과 소스 유형

Argo CD는 애플리케이션 소스가 배포의 단일 정보 원천이 되는 GitOps를 구현합니다.

선언적(Declarative) - 원하는 상태를 YAML 매니페스트, Helm 차트, Kustomize 오버레이로 선언
버전 관리(Versioned) - 모든 변경이 완전한 감사 추적으로 추적
자동화(Automated) - Argo CD가 소스를 지속적으로 모니터링하고 변경을 자동 동기화
자가 치유(Self-healing) - 원하는 상태와 실제 클러스터 상태 간의 드리프트를 감지하고 수정

지원되는 소스 유형:

Git 리포지토리 - GitHub, GitLab, Bitbucket, CodeCommit(HTTPS, SSH 또는 CodeConnections)
Helm 레지스트리 - HTTP 레지스트리(예: https://aws.github.io/eks-charts)와 OCI 레지스트리(예: public.ecr.aws)
OCI 이미지 - 매니페스트나 Helm 차트를 포함한 컨테이너 이미지(예: oci://registry-1.docker.io/user/my-app)

이 유연성 덕분에 조직은 보안 및 규정 준수 요구 사항에 맞는 소스를 선택할 수 있습니다. 예를 들어 클러스터의 Git 접근을 제한하는 조직은 Helm 차트나 OCI 이미지에 ECR을 사용할 수 있습니다. 자세한 내용은 Argo CD 문서의 Application Sources를 참고하세요.

동기화와 리컨실리에이션

Argo CD는 소스와 클러스터를 지속적으로 모니터링해 차이를 감지하고 수정합니다.

소스의 변경 사항을 폴링합니다(기본값: 6분마다).
원하는 상태를 클러스터 상태와 비교합니다.
애플리케이션을 Synced 또는 OutOfSync로 표시합니다.
변경을 자동으로 동기화하거나(구성된 경우) 수동 승인을 기다립니다.
동기화 후 리소스 상태(health)를 모니터링합니다.

동기화 웨이브(sync wave)는 어노테이션을 사용해 리소스 생성 순서를 제어합니다.

metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "0"  # Default if not specified

리소스는 웨이브 순서대로 적용됩니다(음수인 -1을 포함해 낮은 숫자 먼저). 웨이브 0이 지정하지 않았을 때의 기본값입니다. 이렇게 하면 네임스페이스(웨이브 -1) → 배포(웨이브 0) → 서비스(웨이브 1) 순으로 의존성을 만들 수 있습니다.

자가 치유는 수동 변경을 자동으로 되돌립니다.

spec:
  syncPolicy:
    automated:
      selfHeal: true

참고

관리형 캐퍼빌리티는 Kubernetes 규약과 다른 도구와의 더 나은 호환성을 위해 라벨 기반이 아닌 어노테이션 기반 리소스 추적을 사용합니다.

동기화 단계, 훅, 고급 패턴에 대한 자세한 내용은 Argo CD 동기화 문서를 참고하세요.

애플리케이션 상태(health)

Argo CD는 애플리케이션의 모든 리소스 상태(health)를 모니터링합니다.

상태(health) 값:

Healthy - 모든 리소스가 예상대로 실행 중
Progressing - 리소스가 생성 또는 업데이트 중
Degraded - 일부 리소스가 정상이 아님(파드 크래시, 잡 실패)
Suspended - 애플리케이션이 의도적으로 일시 중지됨
Missing - Git에 정의된 리소스가 클러스터에 없음

Argo CD는 일반적인 Kubernetes 리소스(Deployments, StatefulSets, Jobs 등)에 대한 기본 제공 상태(health) 검사를 가지며, CRD에 대한 커스텀 상태(health) 검사도 지원합니다. 애플리케이션 상태(health)는 모든 리소스에 의해 결정됩니다. 리소스 하나가 Degraded면 애플리케이션도 Degraded입니다. 자세한 내용은 Argo CD 문서의 Resource Health를 참고하세요.

멀티 클러스터 패턴

Argo CD는 두 가지 주요 배포 패턴을 지원합니다.

허브 앤 스포크 - 여러 워크로드 클러스터에 배포하는 전용 관리 클러스터에서 Argo CD를 실행합니다.
- 중앙 집중형 제어와 가시성
- 모든 클러스터에 걸친 일관된 정책
- 관리할 Argo CD 인스턴스 하나
- 제어 플레인과 워크로드의 명확한 분리
클러스터별(Per-cluster) - 각 클러스터에서 Argo CD를 실행해 해당 클러스터의 애플리케이션만 관리합니다.
- 클러스터 분리(하나의 장애가 다른 클러스터에 영향을 주지 않음)
- 더 간단한 네트워킹(교차 클러스터 통신 없음)
- 더 쉬운 초기 설정(클러스터 등록 없음)

많은 클러스터를 관리하는 플랫폼 팀에는 허브 앤 스포크를, 독립 팀이나 클러스터가 완전히 격리되어야 하는 경우에는 클러스터별 패턴을 선택하세요. 자세한 멀티 클러스터 구성은 Argo CD 고려 사항을 참고하세요.

프로젝트(Projects)

프로젝트는 Application에 논리적 그룹화와 접근 제어를 제공합니다.

소스 제한 - 사용할 수 있는 Git 리포지토리 제한
대상 제한 - 대상으로 지정할 수 있는 클러스터와 네임스페이스 제한
리소스 제한 - 배포할 수 있는 Kubernetes 리소스 유형 제한
RBAC 통합 - 프로젝트를 AWS Identity Center 사용자 및 그룹 ID에 매핑

Application은 단일 프로젝트에 속합니다. 지정하지 않으면 기본적으로 제한이 없는 default 프로젝트를 사용합니다. 프로덕션에서는 default 프로젝트를 편집해 접근을 제한하고, 적절한 제한이 있는 새 프로젝트를 만드세요. 프로젝트 구성과 RBAC 패턴은 Argo CD 권한 구성을 참고하세요.

동기화 옵션

일반적인 옵션으로 동기화 동작을 세밀하게 조정합니다.

CreateNamespace=true - 대상 네임스페이스를 자동으로 생성
ServerSideApply=true - 더 나은 충돌 해결을 위해 서버 측 적용 사용
SkipDryRunOnMissingResource=true - CRD가 아직 없을 때 드라이 런 건너뛰기(kro 인스턴스에 유용)

spec:
  syncPolicy:
    syncOptions:
    - CreateNamespace=true
    - ServerSideApply=true
    - SkipDryRunOnMissingResource=true

동기화 옵션의 전체 목록은 Argo CD 동기화 옵션 문서를 참고하세요.

다음 단계

리포지토리 접근 구성 - Git 리포지토리 접근 구성
대상 클러스터 등록 - 배포용 대상 클러스터 등록
Application 생성 - 첫 Application 만들기
Argo CD 고려 사항 - EKS별 패턴, Identity Center 통합, 멀티 클러스터 구성
Argo CD 문서 - 동기화 훅, 상태(health) 검사, 고급 패턴을 포함한 종합적인 Argo CD 문서

더 알아보기 (Learn more)

공식 문서