ArgoCD를 활용한 Kubernetes Continuous Delivery 심층 가이드

현대 소프트웨어 개발에서 빠른 배포와 안정적인 운영은 핵심 경쟁력입니다. 특히 마이크로서비스 아키텍처와 컨테이너 기반의 환경이 보편화되면서, Kubernetes와 같은 컨테이너 오케스트레이션 도구는 복잡한 인프라 관리를 위한 필수적인 요소가 되었습니다. 이러한 환경에서 지속적 배포(Continuous Delivery, CD)를 효율적으로 구현하는 것은 DevOps 엔지니어들에게 중요한 과제이며, GitOps 원칙을 기반으로 하는 ArgoCD는 이 과제를 해결하는 강력한 도구로 자리매김하고 있습니다.

이 글에서는 ArgoCD를 활용하여 Kubernetes 환경에서 GitOps 기반의 지속적 배포 파이프라인을 구축하는 방법을 심층적으로 다룹니다. ArgoCD의 기본 개념부터 실제 설치 및 설정, Application 생성 및 관리, 그리고 고급 기능 활용법과 베스트 프랙티스까지 상세하게 안내하여, 여러분의 DevOps 워크플로우를 한 단계 발전시키는 데 도움을 드리고자 합니다.

GitOps와 ArgoCD의 이해

클라우드 네이티브 환경에서 효율적인 배포를 위해 GitOps는 강력한 패러다임으로 부상하고 있습니다. GitOps는 Git을 "진실의 유일한 원천(Single Source of Truth)"으로 삼아 인프라와 애플리케이션 배포를 관리하는 운영 모델입니다. 모든 변경 사항은 Git Repository에 코드 형태로 저장되며, 이 Git Repository의 상태가 실제 배포된 시스템의 상태와 일치하도록 보장하는 것이 핵심입니다.

GitOps의 기본 원칙

GitOps는 다음 네 가지 핵심 원칙을 기반으로 합니다.

1. 선언적(Declarative): 시스템의 상태는 선언적으로 기술되어야 합니다. Kubernetes YAML 파일이나 Helm Chart 등이 이에 해당합니다.
2. 버전 관리(Versioned & Immutable): 시스템의 원하는 상태는 Git에 버전 관리되어야 하며, 변경 불가능해야 합니다. 모든 변경 사항은 Git 커밋으로 기록됩니다.
3. 자동화된 동기화(Pulled Automatically): 승인된 변경 사항이 Git에 푸시되면, 자동화된 에이전트가 이를 감지하고 실제 환경에 동기화합니다.
4. 지속적인 조정(Continuously Reconciled): 소프트웨어 에이전트가 Git의 선언된 상태와 실제 환경의 상태를 지속적으로 비교하고, 불일치가 발생하면 자동으로 조정하여 일치시킵니다.

ArgoCD란 무엇인가?

ArgoCD는 Kubernetes를 위한 선언적(Declarative) GitOps 지속적 배포 도구입니다. Git Repository에 정의된 애플리케이션의 상태를 Kubernetes 클러스터에 배포하고, Git의 상태와 클러스터의 실제 상태를 지속적으로 모니터링하여 불일치가 발생하면 자동으로 또는 수동으로 동기화합니다.

ArgoCD의 가장 큰 특징은 "Pull-based CD" 방식이라는 점입니다. 기존의 CI/CD 도구(Jenkins, GitLab CI 등)가 CI 파이프라인 마지막 단계에서 kubectl apply 명령어를 통해 Kubernetes 클러스터로 변경 사항을 "Push"하는 방식이었다면, ArgoCD는 Kubernetes 클러스터 내에서 동작하는 에이전트가 Git Repository를 지속적으로 모니터링하다가 변경 사항이 감지되면 스스로 클러스터로 변경 사항을 "Pull"하여 적용합니다.

Push-based CD와 Pull-based CD (ArgoCD) 비교

특징	Push-based CD (예: Jenkins)	Pull-based CD (예: ArgoCD)
배포 주체	CI 서버 또는 외부 에이전트가 클러스터로 푸시	클러스터 내의 에이전트(ArgoCD)가 Git으로부터 풀(Pull)
보안	CI 서버가 Kubernetes API 접근 권한 필요 (외부에서 클러스터로 접근)	ArgoCD 에이전트가 클러스터 내에서 Git Repository 접근 (내부에서 외부로 접근)
상태 관리	CI 파이프라인이 완료되면 상태 추적 어려움	Git이 진실의 원천이며, ArgoCD가 클러스터 상태를 지속적으로 모니터링하고 조정
복구 용이성	수동 복구 또는 별도 파이프라인 구성 필요	Git 커밋 롤백만으로 간단하게 이전 상태로 복구 가능
확장성	CI 서버의 부하 및 확장 문제 발생 가능	Kubernetes 클러스터 내에서 동작하므로 클러스터 확장과 함께 확장
복잡성	CI 파이프라인 구성 및 유지보수 복잡	Git Repository 관리 및 ArgoCD Application 정의에 집중

이러한 Pull-based 방식은 보안적으로 더 유리하고, 클러스터의 실제 상태와 Git의 선언된 상태 간의 드리프트(drift)를 자동으로 감지하고 복구할 수 있어 안정적인 운영에 큰 이점을 제공합니다.

ArgoCD 설치 및 초기 설정

ArgoCD를 Kubernetes 클러스터에 설치하는 과정은 비교적 간단합니다. 이 섹션에서는 ArgoCD를 설치하고 초기 접근 설정을 완료하는 방법을 설명합니다.

전제 조건

• Kubernetes 클러스터: v1.16 이상 버전의 Kubernetes 클러스터가 준비되어 있어야 합니다. (minikube, kind, EKS, GKE, AKS 등)
• kubectl: Kubernetes 클러스터와 상호작용하기 위한 kubectl CLI 도구가 설치되어 있어야 합니다.
• Git Repository: 배포할 애플리케이션의 Kubernetes Manifest 파일이 저장될 Git Repository (GitHub, GitLab, Bitbucket 등)가 필요합니다.

ArgoCD 설치

ArgoCD는 자체 argocd 네임스페이스에 설치됩니다. 다음 명령어를 사용하여 ArgoCD를 설치할 수 있습니다.

# argocd 네임스페이스 생성
kubectl create namespace argocd

# ArgoCD 설치 (Core Components)
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

설치가 완료되면 argocd 네임스페이스에 여러 Pod들이 생성되고 실행되는 것을 확인할 수 있습니다.

kubectl get pods -n argocd

출력 예시:

NAME                                    READY   STATUS    RESTARTS   AGE
argocd-application-controller-0         1/1     Running   0          5m
argocd-dex-server-796d8595d6-xxxxx      1/1     Running   0          5m
argocd-notifications-controller-xxxx    1/1     Running   0          5m
argocd-redis-784869c9b5-xxxxx           1/1     Running   0          5m
argocd-repo-server-6789c849b-xxxxx      1/1     Running   0          5m
argocd-server-784869c9b5-xxxxx          1/1     Running   0          5m

ArgoCD CLI 설치

ArgoCD를 보다 편리하게 관리하기 위해 CLI 도구를 설치하는 것이 좋습니다.

macOS (Homebrew):

brew install argocd

Linux (Shell Script):

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

설치 후 argocd version 명령어로 확인합니다.

ArgoCD UI 접근 및 초기 비밀번호 설정

ArgoCD는 웹 UI를 통해 애플리케이션 상태를 시각적으로 확인하고 관리할 수 있습니다. argocd-server 서비스는 기본적으로 ClusterIP 타입으로 생성되므로, 외부에서 접근하려면 Port Forwarding을 사용하거나 LoadBalancer, NodePort 등으로 서비스 타입을 변경해야 합니다.

Port Forwarding (로컬 개발 및 테스트용):

kubectl port-forward svc/argocd-server -n argocd 8080:443

이제 웹 브라우저에서 https://localhost:8080으로 접속할 수 있습니다.

초기 비밀번호 확인: 초기 비밀번호는 argocd-initial-admin-secret Secret에 저장되어 있습니다.

kubectl get secret argocd-initial-admin-secret -n argocd -o jsonpath="{.data.password}" | base64 -d

이 명령어로 얻은 비밀번호와 사용자명 admin으로 ArgoCD 웹 UI에 로그인합니다. 로그인 후에는 보안을 위해 비밀번호를 변경하는 것을 권장합니다.

argocd login localhost:8080 # CLI 로그인
argocd account update-password # 비밀번호 변경

ArgoCD Application 생성 및 관리

ArgoCD의 핵심은 Application 리소스입니다. Application은 Git Repository의 특정 경로에 있는 Kubernetes Manifest (YAML, Helm Chart, Kustomize 등)를 Kubernetes 클러스터의 특정 네임스페이스에 배포하는 방법을 정의합니다.

Git Repository 준비

배포할 간단한 Nginx 애플리케이션의 Kubernetes Manifest 파일을 Git Repository에 준비합니다. 예를 들어, my-app이라는 Git Repository에 manifests/dev 경로에 다음과 같은 nginx-deployment.yaml 파일을 생성합니다.

# my-app/manifests/dev/nginx-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
        - containerPort: 80

apiVersion: v1
kind: Service
metadata:
  name: nginx-service
  labels:
    app: nginx
spec:
  selector:
    app: nginx
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
  type: ClusterIP

ArgoCD Application 생성

ArgoCD Application은 YAML 파일로 정의하거나 ArgoCD CLI 또는 웹 UI를 통해 생성할 수 있습니다. 여기서는 YAML 파일을 사용하는 방법을 먼저 설명합니다.

1. Application YAML 정의: argocd-app.yaml 파일을 생성합니다.

# argocd-app.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-nginx-app
  namespace: argocd # ArgoCD Application은 argocd 네임스페이스에 생성됩니다.
spec:
  project: default # ArgoCD 프로젝트. 기본값은 default.
  source:
    repoURL: https://github.com/YOUR_GITHUB_USER/my-app.git # Git Repository URL
    targetRevision: HEAD # 사용할 브랜치 또는 커밋 해시 (예: main, HEAD)
    path: manifests/dev # Git Repository 내 Kubernetes Manifest 파일 경로
  destination:
    server: https://kubernetes.default.svc # 배포할 Kubernetes 클러스터 (기본값)
    namespace: dev # 애플리케이션이 배포될 대상 네임스페이스
  syncPolicy:
    automated:
      prune: true # 클러스터에서 더 이상 필요 없는 리소스 자동 삭제
      selfHeal: true # 클러스터 상태가 Git과 다를 경우 자동으로 동기화
    syncOptions:
    - CreateNamespace=true # 대상 네임스페이스가 없으면 자동으로 생성

2. Application 생성:

kubectl apply -n argocd -f argocd-app.yaml

또는 ArgoCD CLI를 사용할 수도 있습니다.

argocd app create my-nginx-app \
  --repo https://github.com/YOUR_GITHUB_USER/my-app.git \
  --path manifests/dev \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace dev \
  --sync-policy automated \
  --auto-prune \
  --self-heal \
  --upsert

YOUR_GITHUB_USER를 본인의 GitHub 사용자 이름으로 변경해야 합니다.

Application 상태 모니터링

Application이 생성되면 ArgoCD는 Git Repository를 모니터링하고, 정의된 경로의 Manifest 파일을 가져와 대상 클러스터에 배포합니다. 웹 UI 또는 CLI를 통해 Application의 상태를 확인할 수 있습니다.

웹 UI: https://localhost:8080에 접속하여 my-nginx-app을 클릭하면 배포된 리소스의 상태, 동기화 상태, 헬스 상태 등을 시각적으로 확인할 수 있습니다.

CLI:

argocd app list
argocd app get my-nginx-app
argocd app history my-nginx-app

argocd app get my-nginx-app 명령어를 실행하면 Sync Status가 Synced로, Health Status가 Healthy로 표시되는 것을 확인할 수 있습니다. 이는 Git의 상태와 클러스터의 실제 상태가 일치하며, 애플리케이션이 정상적으로 동작하고 있음을 의미합니다.

수동 동기화 및 자동 동기화 설정

syncPolicy 필드를 통해 동기화 방식을 설정할 수 있습니다.

• 수동 동기화 (Manual Sync): syncPolicy를 정의하지 않거나 automated를 false로 설정하면, Git Repository에 변경 사항이 생겨도 ArgoCD는 자동으로 배포하지 않습니다. 웹 UI의 "SYNC" 버튼을 누르거나 argocd app sync <APP_NAME> 명령어로 수동 동기화를 실행해야 합니다.
• 자동 동기화 (Automated Sync): syncPolicy.automated를 true로 설정하면 ArgoCD는 Git Repository의 변경 사항을 감지하여 자동으로 클러스터에 배포합니다.
  • prune: true: Git Repository에서 삭제된 리소스는 클러스터에서도 자동으로 삭제됩니다.
  • selfHeal: true: 클러스터의 리소스 상태가 Git의 상태와 다를 경우, ArgoCD가 자동으로 Git의 상태로 복구합니다 (드리프트 감지 및 복구).

고급 ArgoCD 기능 활용

ArgoCD는 단순한 배포를 넘어, 복잡한 배포 시나리오와 운영 요구사항을 충족시키기 위한 다양한 고급 기능을 제공합니다.

Sync Options

syncOptions는 동기화 동작을 세밀하게 제어할 수 있게 해줍니다.

• CreateNamespace=true: 대상 네임스페이스가 존재하지 않으면 자동으로 생성합니다.
• PrunePropagationPolicy=foreground/background/orphan: 리소스 삭제 시 자식 리소스를 어떻게 처리할지 정의합니다.
• Replace=true: 기존 리소스를 kubectl replace 방식으로 업데이트합니다. (주의: 일반적으로 kubectl apply 방식이 권장됨)
• ServerSideApply=true: Kubernetes 1.16+에서 도입된 Server-Side Apply를 사용하여 리소스를 관리합니다. 이는 필드 병합 충돌을 더 효과적으로 처리합니다.
• ApplyOutOfSyncOnly=true: Git과 일치하지 않는 리소스만 동기화합니다.
• RespectIgnoreDifferences=true: ignoreDifferences에 정의된 필드 차이는 무시하고 동기화합니다.

예시:

spec:
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true
    - ServerSideApply=true # Server-Side Apply 활성화

Health Checks 및 Resource Hooks (PreSync, Sync, PostSync)

ArgoCD는 배포된 리소스의 헬스 상태를 자동으로 감지하고 표시합니다. 또한, 배포 전/중/후에 특정 작업을 수행하도록 Resource Hooks를 사용할 수 있습니다. 이는 데이터베이스 마이그레이션, 캐시 클리어, 테스트 실행 등 복잡한 배포 시나리오에 유용합니다.

Resource Hooks는 Kubernetes Manifest에 Annotation으로 정의됩니다.

• argocd.argoproj.io/hook: PreSync: 동기화 시작 전 실행
• argocd.argoproj.io/hook: Sync: 동기화 중 (일반 리소스와 함께) 실행
• argocd.argoproj.io/hook: PostSync: 모든 리소스가 동기화된 후 실행
• argocd.argoproj.io/hook: SyncFail: 동기화 실패 시 실행
• argocd.argoproj.io/hook: Skip: 해당 리소스는 ArgoCD 동기화에서 제외

예시 (PreSync Hook을 이용한 데이터베이스 마이그레이션 Job):

apiVersion: batch/v1
kind: Job
metadata:
  name: db-migration-job
  annotations:
    argocd.argoproj.io/hook: PreSync # PreSync 훅으로 지정
    argocd.argoproj.io/hook-delete-policy: HookSucceeded # 성공 시 Job 삭제
spec:
  template:
    spec:
      containers:
      - name: migration
        image: your-migration-image:latest
        command: ["/app/migrate"]
      restartPolicy: Never
  backoffLimit: 4

Sync Waves를 이용한 배포 순서 제어

마이크로서비스 아키텍처에서는 애플리케이션의 구성 요소들이 특정 순서로 배포되어야 하는 경우가 많습니다 (예: 데이터베이스 -> 백엔드 -> 프론트엔드). ArgoCD의 Sync Waves 기능을 사용하면 이러한 배포 순서를 제어할 수 있습니다.

Sync Waves는 Kubernetes Manifest에 argocd.argoproj.io/sync-wave Annotation을 추가하여 정의합니다. 숫자가 낮은 Wave부터 높은 Wave 순서로 배포가 진행됩니다.

예시:

# db-deployment.yaml (Wave 0)
apiVersion: apps/v1
kind: Deployment
metadata:
  name: database-deployment
  annotations:
    argocd.argoproj.io/sync-wave: "0" # 가장 먼저 배포
spec:
  # ...



# backend-deployment.yaml (Wave 1)
apiVersion: apps/v1
kind: Deployment
metadata:
  name: backend-deployment
  annotations:
    argocd.argoproj.io/sync-wave: "1" # 데이터베이스 배포 후 배포
spec:
  # ...

Rollback 기능

GitOps의 큰 장점 중 하나는 쉬운 롤백입니다. ArgoCD는 Git Repository의 커밋 히스토리를 기반으로 특정 시점의 상태로 쉽게 롤백할 수 있습니다.

웹 UI에서 Application의 History and Rollback 탭을 통해 이전 배포 버전들을 확인하고, 원하는 버전으로 롤백할 수 있습니다. CLI로는 다음과 같이 롤백할 수 있습니다.

# 이전 배포 히스토리 확인
argocd app history my-nginx-app

# 특정 ID의 리비전으로 롤백
argocd app rollback my-nginx-app --revision <REVISION_ID>

이 기능은 문제가 발생했을 때 신속하게 이전 안정적인 상태로 복구하는 데 매우 중요합니다.

ArgoCD Best Practices

효율적이고 안정적인 지속적 배포를 위해 ArgoCD를 활용할 때 고려해야 할 몇 가지 베스트 프랙티스가 있습니다.

Repository 구조화

Git Repository를 어떻게 구성하느냐는 GitOps 워크플로우의 효율성에 큰 영향을 미칩니다. 일반적으로 다음과 같은 구조를 권장합니다.

• Monorepo (단일 리포지토리): 모든 애플리케이션 및 인프라 Manifest를 하나의 Git Repository에 저장합니다. 환경별(dev, staging, prod) 디렉토리를 두어 관리합니다.
• Multi-repo (다중 리포지토리): 애플리케이션 코드 리포지토리와 배포 Manifest 리포지토리를 분리합니다. 또는 환경별로 Manifest 리포지토리를 분리할 수도 있습니다.
  • app-code-repo: 애플리케이션 소스 코드, Dockerfile, CI 파이프라인
  • app-manifest-repo: 애플리케이션의 Kubernetes Manifest (Helm Chart, Kustomize)
  • infra-manifest-repo: 클러스터 애드온, 네임스페이스 등 인프라 관련 Manifest

어떤 구조를 선택하든, Git 브랜치 전략(GitFlow, GitHub Flow 등)과 일관성을 유지하고, 환경별 구성을 명확히 분리하는 것이 중요합니다. Helm Chart나 Kustomize를 사용하여 환경별 설정을 오버라이딩하는 방법을 적극 활용하십시오.

Multi-cluster 관리

ArgoCD는 단일 인스턴스로 여러 Kubernetes 클러스터를 관리할 수 있습니다. 이는 여러 개발, 스테이징, 프로덕션 클러스터를 중앙에서 관리해야 하는 시나리오에 매우 유용합니다.

새로운 클러스터를 ArgoCD에 등록하려면 kubeconfig 파일이 필요합니다.

# 대상 클러스터의 kubeconfig 파일이 있는 경우
argocd cluster add <CONTEXT_NAME_IN_KUBECONFIG>

# 또는 직접 kubeconfig 내용을 전달
argocd cluster add <CLUSTER_NAME> --service-account argocd-manager --kubeconfig <PATH_TO_KUBECONFIG>

등록된 클러스터는 ArgoCD 웹 UI에서 확인할 수 있으며, Application 정의 시 destination.server 필드에 해당 클러스터의 API 서버 URL을 지정하여 배포할 수 있습니다.

보안 고려사항 (RBAC)

ArgoCD는 강력한 RBAC(Role-Based Access Control) 기능을 제공하여 사용자 및 그룹별로 ArgoCD 리소스(Application, Project, Cluster)에 대한 접근 권한을 세밀하게 제어할 수 있습니다.

• Projects: ArgoCD Project는 애플리케이션을 논리적으로 그룹화하고, 특정 Git Repository, 대상 클러스터/네임스페이스, 리소스 유형에 대한 배포를 제한하는 데 사용됩니다.
• Roles: 사용자 또는 그룹에 할당될 역할을 정의하며, 특정 Project 내의 Application에 대한 get, create, update, delete, sync 등의 권한을 부여합니다.
• SSO 연동: Dex를 통해 LDAP, OAuth2, SAML 등 다양한 SSO(Single Sign-On) 제공자와 연동하여 사용자 인증을 통합할 수 있습니다.

ArgoCD의 argocd-rbac-cm ConfigMap을 수정하여 사용자 정의 RBAC 정책을 설정할 수 있습니다.

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
  namespace: argocd
data:
  # 기본 역할
  policy.csv: |
    p, role:admin, applications, *, */*, allow
    p, role:developer, applications, get, */*, allow
    p, role:developer, applications, sync, */*, allow
    g, my-dev-group, role:developer # my-dev-group 그룹에 developer 역할 부여

마무리

ArgoCD는 GitOps 원칙을 기반으로 Kubernetes 환경에서 지속적 배포를 혁신하는 강력한 도구입니다. 이 글에서 다룬 ArgoCD의 개념, 설치, Application 관리, 고급 기능 및 베스트 프랙티스를 통해 여러분의 DevOps 파이프라인을 더욱 자동화하고 안정적으로 구축할 수 있을 것입니다. Git을 진실의 원천으로 삼아 인프라와 애플리케이션을 선언적으로 관리함으로써, 배포 프로세스의 투명성, 신뢰성, 그리고 회복탄력성을 크게 향상시킬 수 있습니다. ArgoCD와 함께라면 더욱 효율적인 클라우드 네이티브 환경을 구축하고 운영할 수 있습니다.