ArgoCD로 멀티 클러스터 GitOps 배포 자동화 완벽 가이드

안녕하세요, 13년차 서버실 지킴이입니다. 오늘도 어김없이 여러분의 인프라 여정에 도움이 될 만한 꿀팁을 들고 왔습니다. 혹시 여러 쿠버네티스 클러스터를 운영하면서 배포 때문에 머리 아팠던 경험 있으신가요? 개발, 스테이징, 운영 환경이 각각 다른 클러스터에 존재하거나, 온프레미스와 클라우드를 넘나드는 하이브리드 환경에서 일관된 배포를 유지하는 게 정말 쉽지 않거든요. 저도 처음엔 수동 배포 지옥에서 헤매던 시절이 있었죠. 클러스터마다 kubectl 명령어를 치고, YAML 파일을 수정하고, 휴먼 에러로 인해 서비스 장애를 겪었던 아찔한 순간들도 많았고요. 😱

하지만 GitOps(깃옵스)를 만나고, 특히 ArgoCD(아르고CD)를 활용하면서 이런 배포 스트레스가 확 줄었습니다. 오늘은 저처럼 멀티 클러스터 환경에서 배포 자동화에 목마른 분들을 위해, ArgoCD로 GitOps를 구현하고 여러 클러스터에 애플리케이션을 자동으로 배포하는 멀티 클러스터 GitOps 배포 자동화 방법을 완벽하게 가이드해 드리려고 합니다. 제가 직접 삽질하며 터득한 경험들을 솔직하게 공유할 테니, 끝까지 따라오시면 분명 큰 도움이 될 겁니다! 자, 그럼 시작해 볼까요?

ArgoCD를 활용한 멀티 클러스터 GitOps 배포 아키텍처는 위와 같이 구성될 수 있습니다. 하나의 ArgoCD 인스턴스가 여러 쿠버네티스 클러스터에 애플리케이션을 배포하고 관리하는 모습이죠. Git을 중심으로 모든 클러스터의 상태를 동기화하는 핵심 아이디어를 담고 있습니다.

1. GitOps와 ArgoCD, 그리고 멀티 클러스터 배포, 이게 뭔가요?

본격적인 실전에 앞서, 핵심 개념들을 짚고 넘어가는 게 중요하겠죠? 제가 늘 강조하는 부분인데, 도구를 잘 쓰는 것도 중요하지만, 그 도구가 왜 필요하고 어떤 철학을 담고 있는지 이해하는 게 진짜 실력입니다.

• GitOps (깃옵스): 쉽게 말해, Git을 유일한 진실의 원천(Single Source of Truth)으로 삼아 인프라와 애플리케이션 배포를 자동화하는 운영 방식이에요. 모든 설정과 배포 상태를 Git 리포지토리에 코드로 관리하고, Git에 변경사항이 푸시되면 자동으로 인프라에 반영되도록 하는 거죠. 개발자들이 코드 관리하듯이 인프라를 관리한다고 생각하시면 됩니다. 일관성, 버전 관리, 감사 추적(Audit Trail)이 가능하다는 엄청난 장점이 있어요.

• ArgoCD (아르고CD): 이 친구는 GitOps를 쿠버네티스(Kubernetes) 환경에서 구현해주는 선언적(Declarative) GitOps 지속적 배포(Continuous Delivery) 툴입니다. Git 리포지토리에 정의된 원하는 상태(Desired State)와 실제 쿠버네티스 클러스터의 현재 상태(Live State)를 끊임없이 비교하고, 만약 다르면 Git에 정의된 상태로 클러스터를 동기화(Sync)시켜 줍니다. 마치 클러스터 상태를 감시하는 파수꾼 같다고 할까요? 정말 든든한 친구더라고요.

• 멀티 클러스터 배포 (Multi-Cluster Deployment): 여러 개의 쿠버네티스 클러스터에 동일하거나 다른 애플리케이션을 배포하고 관리하는 시나리오를 말합니다. 개발, 스테이징, 운영 환경을 분리하거나, 재해 복구(DR)를 위해 지리적으로 분산된 클러스터를 운영할 때 주로 사용하죠. ArgoCD는 하나의 중앙 인스턴스에서 여러 클러스터를 관리할 수 있어서, 멀티 클러스터 환경에서 배포를 중앙 집중화하고 자동화하는 데 아주 탁월한 솔루션입니다.

2. 실전 구현: ArgoCD로 멀티 클러스터 GitOps 환경 구축하기

자, 이제 이론은 충분히 봤으니, 저와 함께 직접 만들어 볼 시간입니다. 제가 홈랩에서 여러 번 시도하면서 가장 효율적이라고 생각했던 방법으로 안내해 드릴게요. 따라만 하시면 됩니다! 💡

2.1. 사전 준비물 (Prerequisites)

시작하기 전에 몇 가지 준비물이 필요합니다.

• 쿠버네티스 클러스터 2개 이상: 하나는 ArgoCD를 설치할 ‘컨트롤 플레인 클러스터’로, 나머지는 애플리케이션을 배포할 ‘타겟 클러스터’로 사용할 겁니다. (저는 KIND나 K3s로 쉽게 구성했어요.)
• kubectl: 쿠버네티스 클러스터를 제어하는 CLI 도구.
• Helm (선택 사항): 쿠버네티스 패키지 매니저. ArgoCD 설치에 Helm을 사용하진 않지만, 애플리케이션 배포에 유용할 수 있습니다.
• Git 리포지토리: 배포할 애플리케이션의 YAML 파일들을 저장할 공간 (GitHub, GitLab, Bitbucket 등).

2.2. 단계 1: ArgoCD 설치 (컨트롤 플레인 클러스터)

먼저 ArgoCD를 설치할 클러스터에 ArgoCD를 배포합니다. 이 클러스터가 모든 배포의 중앙 통제실 역할을 하게 됩니다.

1. ArgoCD 네임스페이스 생성

   kubectl create namespace argocd

2. ArgoCD 설치 YAML 적용

   kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

   이 명령은 ArgoCD의 모든 컴포넌트(API 서버, 컨트롤러, 레포 서버 등)를 설치합니다. 잠시 기다리면 파드들이 정상적으로 올라올 거예요.

3. ArgoCD CLI 설치 (선택 사항이지만 강력 추천!)

   # macOS (Homebrew)
   brew install argocd
   
   # Linux (직접 다운로드)
   curl -sSL -o argocd-linux-amd64 https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
   sudo install -m 555 argocd-linux-amd64 /usr/local/bin/argocd
   rm argocd-linux-amd64

4. 초기 비밀번호 확인 및 UI 접근

   ArgoCD API 서버의 초기 비밀번호는 컨트롤 플레인 클러스터의 argocd-initial-admin-secret 시크릿에 저장되어 있습니다.

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

   UI에 접근하려면 포트 포워딩(Port Forwarding)을 해줘야 합니다.

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

   이제 웹 브라우저에서 https://localhost:8080으로 접속한 후, 사용자명 admin과 위에서 확인한 비밀번호로 로그인하세요. 첫 로그인 후 비밀번호를 변경하는 것을 추천합니다.

2.3. 단계 2: Git Repository 준비

배포할 애플리케이션의 YAML 파일들을 Git 리포지토리에 준비해야 합니다. 저는 간단한 Nginx 배포 파일을 예시로 들어볼게요.

my-gitops-repo/apps/nginx/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

my-gitops-repo/apps/nginx/service.yaml

apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  selector:
    app: nginx
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
  type: LoadBalancer # 또는 ClusterIP, NodePort

이 파일들을 Git 리포지토리에 푸시해 주세요. (예: https://github.com/your-org/my-gitops-repo.git)

2.4. 단계 3: 타겟 클러스터 등록 (ArgoCD에 연결)

이제 ArgoCD가 애플리케이션을 배포할 타겟 클러스터들을 ArgoCD에 등록해야 합니다. ArgoCD CLI를 사용하면 아주 쉽게 등록할 수 있어요.

1. ArgoCD CLI 로그인

   argocd login localhost:8080

   초기 비밀번호로 로그인합니다.

2. 타겟 클러스터 등록

   현재 kubeconfig 파일에 정의된 클러스터 컨텍스트(Context)를 사용해서 등록합니다. 등록할 클러스터의 컨텍스트로 kubectl config use-context <TARGET_CLUSTER_CONTEXT> 명령어를 실행한 후, 아래 명령어를 실행하세요.

   argocd cluster add <TARGET_CLUSTER_CONTEXT>

   예를 들어, dev-cluster와 prod-cluster라는 컨텍스트가 있다면 각각 등록해 줍니다.

   이 명령은 ArgoCD가 타겟 클러스터에 접근할 수 있도록 필요한 RBAC 설정과 시크릿을 자동으로 생성해 줍니다. ⚠️ 권한 문제로 많이들 삽질하시는데, 이 단계에서 정확한 컨텍스트를 선택했는지 꼭 확인하세요.

3. 등록된 클러스터 확인

   argocd cluster list

   등록된 클러스터 목록이 보이면 성공입니다! ArgoCD UI에서도 ‘Clusters’ 메뉴에서 확인할 수 있습니다.

ArgoCD UI에서 클러스터가 성공적으로 등록되고 ApplicationSet이 여러 클러스터에 배포되는 모습을 시각적으로 확인할 수 있습니다. 각 클러스터별로 애플리케이션 상태를 한눈에 파악할 수 있죠.

2.5. 단계 4: ApplicationSet으로 멀티 클러스터 배포 자동화

이제 이 글의 핵심인 ApplicationSet(애플리케이션셋)을 활용해서 여러 클러스터에 Nginx 애플리케이션을 배포해 볼 시간입니다. ApplicationSet은 여러 개의 ArgoCD Application 리소스를 동적으로 생성해주는 컨트롤러입니다. 특히 멀티 클러스터 환경에서 빛을 발하죠!

ApplicationSet을 사용하면, 등록된 모든 클러스터에 동일한 애플리케이션을 배포하거나, 클러스터별로 약간 다른 설정을 적용하여 배포할 수 있습니다. 여기서는 Cluster Generator를 사용해서 ArgoCD에 등록된 모든 클러스터에 Nginx를 배포하도록 해볼게요.

my-gitops-repo/applicationsets/nginx-applicationset.yaml

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: multi-cluster-nginx
  namespace: argocd
spec:
  generators:
  - clusters: {}
  template:
    metadata:
      name: '{{name}}-nginx' # 클러스터 이름 기반으로 Application 이름 생성
      namespace: argocd
    spec:
      project: default
      source:
        repoURL: https://github.com/your-org/my-gitops-repo.git # 본인의 Git 리포지토리 URL로 변경
        targetRevision: HEAD
        path: apps/nginx
      destination:
        server: '{{server}}'
        namespace: default
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
          - CreateNamespace=true # 대상 클러스터에 네임스페이스가 없으면 생성

위 YAML 파일을 Git 리포지토리에 푸시한 후, ArgoCD가 설치된 컨트롤 플레인 클러스터에 적용합니다.

kubectl apply -n argocd -f my-gitops-repo/applicationsets/nginx-applicationset.yaml

잠시 후 ArgoCD UI의 ‘Applications’ 메뉴로 이동해 보세요. 등록된 클러스터 개수만큼 <클러스터이름>-nginx 형태의 애플리케이션이 자동으로 생성되고, 배포가 시작되는 것을 확인할 수 있을 겁니다. 정말 신기하더라고요! 🎉

3. 주의사항 및 트러블슈팅: 저의 삽질 경험담 ⚠️

제가 13년간 인프라 엔지니어로 일하면서 깨달은 건, 새로운 기술을 도입할 때 늘 예상치 못한 문제가 터진다는 겁니다. ArgoCD도 예외는 아니었죠. 제가 겪었던 주요 삽질 경험과 해결 팁을 공유해 드립니다.

• RBAC (Role-Based Access Control) 문제: 타겟 클러스터 등록 시 ArgoCD가 해당 클러스터에 접근할 권한이 없어서 배포가 실패하는 경우가 많았습니다. argocd cluster add 명령이 자동으로 RBAC를 설정해주지만, 때로는 특정 리소스에 대한 추가 권한이 필요할 수 있어요. ArgoCD 서버의 서비스 어카운트(Service Account)에 필요한 ClusterRoleBinding이 제대로 되어있는지 확인하고, 필요하다면 수동으로 추가해줘야 합니다.

  # 예시: ArgoCD 서비스 어카운트에 Cluster-Admin 권한 부여 (실제 운영에서는 최소 권한 원칙 준수)
  apiVersion: rbac.authorization.k8s.io/v1
  kind: ClusterRoleBinding
  metadata:
    name: argocd-manager-role-binding
  subjects:
  - kind: ServiceAccount
    name: argocd-argocd-application-controller
    namespace: argocd
  roleRef:
    apiGroup: rbac.authorization.k8s.io
    kind: ClusterRole
    name: cluster-admin # or a more specific role

• Kubeconfig 파일 접근 권한: ArgoCD가 타겟 클러스터에 접근하려면 컨트롤 플레인 클러스터에서 타겟 클러스터의 API 서버에 네트워크적으로 연결이 가능해야 합니다. 방화벽, VPC 설정 등을 꼼꼼히 확인하세요. 특히 온프레미스와 클라우드 하이브리드 환경에서는 네트워크 경로 설정이 복잡해질 수 있습니다.

• Sync Policy 설정: automated: prune: true와 selfHeal: true 옵션은 배포를 매우 편리하게 해주지만, 자칫 잘못하면 예상치 못한 변경이 즉시 반영될 수 있습니다. 특히 운영 환경에서는 신중하게 접근하고, 처음에는 수동 동기화(Manual Sync)로 시작하여 동작을 충분히 이해한 후 자동화하는 것을 추천합니다.

• ApplicationSet Generator 문제: Cluster Generator를 쓸 때, Git 리포지토리의 경로(path)나 targetRevision, 그리고 destination의 server와 namespace 설정에 오타가 없는지 여러 번 확인해야 합니다. 변수({{name}}, {{server}}) 사용법도 헷갈리기 쉽더라고요.

4. 검증 및 결과: 드디어 됐다! ✅

이제 ArgoCD UI에서 모든 애플리케이션들이 Synced 상태인지 확인해 보세요. 각 클러스터에 배포된 Nginx 파드들도 kubectl get pods -n default 명령으로 확인하면 정상적으로 실행되고 있을 겁니다. 드디어 모든 클러스터에 배포가 완료됐네요! 이 맛에 GitOps 하는 거 아니겠습니까? 🎉

여기서 끝이 아닙니다! GitOps의 진정한 가치는 Git 변경 사항이 자동으로 반영되는 데 있거든요. my-gitops-repo/apps/nginx/deployment.yaml 파일의 replicas 수를 2에서 3으로 변경하고 Git에 푸시해 보세요. ArgoCD가 변경 사항을 감지하고, 몇 초 내에 모든 타겟 클러스터의 Nginx 파드 개수가 3개로 자동으로 업데이트되는 것을 볼 수 있을 겁니다. 정말 편하더라고요!

ArgoCD 대시보드에서 여러 클러스터에 배포된 애플리케이션들의 실시간 상태를 모니터링하는 화면입니다. 모든 애플리케이션이 정상적으로 동기화(Synced)된 것을 확인할 수 있습니다.

5. 마무리: GitOps로 한 단계 더 성장하기

오늘은 ArgoCD를 활용하여 멀티 클러스터 GitOps 배포 자동화를 구현하는 과정을 저의 경험을 바탕으로 상세하게 설명해 드렸습니다. 어떠셨나요? 처음엔 복잡해 보이지만, 한 번 구축해 놓으면 배포의 일관성, 속도, 안정성이 비약적으로 향상되는 것을 체감하실 수 있을 겁니다.

멀티 클러스터 환경에서 ArgoCD와 GitOps는 정말 강력한 조합입니다. 수동 작업에서 벗어나 휴먼 에러를 줄이고, Git을 통한 완벽한 버전 관리와 감사 추적이 가능해지거든요. 무엇보다 인프라 엔지니어가 더 중요하고 전략적인 업무에 집중할 수 있도록 도와주는 멋진 도구라고 생각합니다.

물론 초기 설정에 시간과 노력이 필요하고, GitOps 문화에 적응하는 과정도 필요합니다. 하지만 그 투자 가치는 충분하다고 제가 직접 보증합니다. 제 홈랩에서도 이 방식으로 다양한 서비스를 배포하고 있거든요. 😉

다음번에는 오늘 배운 ArgoCD와 GitOps 개념을 확장해서, Helm Chart 통합, Kustomize 활용, 그리고 Argo Rollouts(아르고 롤아웃)를 이용한 블루/그린, 카나리 배포 전략까지 자동화하는 경험담을 들려드릴게요! 이 글이 여러분의 인프라 여정에 작은 이정표가 되었기를 바랍니다. 다음에 또 만나요!

GitOps와 기존 배포 방식, 그리고 ArgoCD의 멀티 클러스터 관리 장점을 요약한 인포그래픽입니다. 어떤 점들이 개선되었는지 한눈에 파악할 수 있습니다.