본문 바로가기
IT/k8s

[k8s] Argo CD 멀티 클러스터 GitOps 베스트 프랙티스 체크리스트

by 수누다 2026. 6. 17.

목차

Argo CD 멀티 클러스터 GitOps 베스트 프랙티스 체크리스트

안녕하세요, 13년차의 서버실 운영자입니다. 오늘은 제가 홈랩과 회사에서 Argo CD 멀티 클러스터 환경을 구축하면서 겪었던 일들과, 여러분이 효율적인 GitOps 베스트 프랙티스를 적용할 수 있도록 돕는 GitOps 체크리스트를 공유해드리려고 합니다.

요즘 Kubernetes 다중 클러스터 관리는 선택이 아니라 필수가 되어가고 있죠. 개발, 스테이징, 프로덕션 환경이 따로 있거나, DR(재해 복구)을 위해 여러 리전에 클러스터를 두는 경우가 많습니다. 근데 이 클러스터들을 일일이 관리하는 게 보통 일이 아니더라고요. 직접 해보니 삽질 좀 했습니다. (ㅎㅎ)

이런 고민을 하시는 분들을 위해, Argo CD를 활용한 멀티 클러스터 GitOps의 개념부터 실전 전략, 그리고 제가 직접 겪었던 트러블슈팅 경험까지 솔직하게 풀어보겠습니다. 이 글을 통해 여러분의 Argo CD 배포 전략이 한층 더 견고해지길 바랍니다. 드디어 배포가 편해지는 그 날을 위해!

Argo CD 멀티 클러스터 GitOps 아키텍처 다이어그램

Argo CD를 이용한 멀티 클러스터 GitOps의 전체 아키텍처는 위 그림처럼 구성할 수 있습니다. 중앙의 Argo CD가 여러 클러스터를 관리하는 형태죠.

Argo CD와 GitOps, 그리고 멀티 클러스터 관리 핵심 개념

우선, 핵심 개념부터 쉽고 편하게 짚고 넘어가 볼까요? 제가 처음 Argo CD를 접했을 때를 생각하면서 설명해 드릴게요.

GitOps: Git이 진리의 원천입니다

GitOps(깃옵스)는 말 그대로 Git을 운영(Operations)의 중심으로 삼는 방식입니다. 모든 인프라와 애플리케이션의 상태를 Git 리포지토리에 선언적으로 정의하고, 이 Git 리포지토리의 변경사항이 자동으로 실제 환경에 반영되도록 하거든요. 쉽게 말해, kubectl apply -f를 사람이 직접 하는 게 아니라, Git에 커밋만 하면 시스템이 알아서 해주는 거죠. 제가 처음 이걸 알았을 때, '와, 이거 진짜 편하겠다!' 싶었어요.

GitOps의 장점은 명확합니다:

  • 버전 관리(Version Control): 모든 변경 이력을 Git에서 확인할 수 있어요. 누가 언제 뭘 바꿨는지 투명하게 알 수 있죠.
  • 자동화(Automation): 수동 작업이 줄어들어 휴먼 에러를 최소화하고, 배포 속도를 높일 수 있습니다.
  • 복원력(Resilience): 문제가 발생하면 Git의 이전 상태로 쉽게 롤백(Rollback)할 수 있습니다.
  • 협업(Collaboration): 개발팀과 운영팀이 Git을 통해 더 효율적으로 협업할 수 있습니다.

Argo CD: GitOps를 Kubernetes에 현실로 만들어주는 도구

그럼 Argo CD(아르고 CD)는 뭘까요? Argo CD는 선언적(Declarative) GitOps 지속적 배포(Continuous Delivery) 도구거든요. Kubernetes(쿠버네티스) 애플리케이션의 배포와 라이프사이클 관리를 Git에서 정의된 상태에 따라 자동으로 동기화(Sync)해주는 역할을 해요. 제가 써보니까, 복잡한 배포 파이프라인을 구축하는 수고를 엄청나게 덜어주더라고요.

멀티 클러스터 관리: 복잡성을 단순화하기

여러 개의 Kubernetes 클러스터를 관리하는 건 마치 여러 대의 서버를 손으로 직접 관리하는 것과 비슷해요. 하나만 관리할 때는 괜찮지만, 두 개, 세 개… 점점 늘어나면 감당하기 어려워집니다. Kubernetes 다중 클러스터 관리는 이런 복잡성을 줄이고 일관성을 유지하기 위한 전략이 필요해요. Argo CD는 이 문제를 ApplicationSet(애플리케이션셋)이라는 기능을 통해 아주 우아하게 해결해 줍니다. 처음엔 이게 뭔가 싶었는데, 써보니 진짜 물건이더라고요!

실전 구현: Argo CD 멀티 클러스터 환경 설정 베스트 프랙티스

이제 이론을 바탕으로 실제로 어떻게 구성하는지 알아볼 시간입니다. 제가 홈랩에서 여러 시도를 해보고, 회사에서 적용하면서 얻은 노하우들을 풀어드릴게요.

1. Argo CD Control Plane 설치

먼저, Argo CD가 설치될 메인 클러스터, 즉 Control Plane(컨트롤 플레인) 클러스터가 필요합니다. 이곳에서 모든 배포를 관장하게 됩니다. 기본적인 Argo CD 설치는 공식 문서에 잘 나와 있는데, 간단히 요약해볼게요.


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

설치 후에는 Argo CD UI에 접속하여 초기 비밀번호를 설정하고 로그인할 수 있습니다.

2. Managed Clusters(관리 대상 클러스터) 등록

다음으로, Argo CD가 관리할 다른 Kubernetes 클러스터들을 등록해야 합니다. 저는 개발, 스테이징, 프로덕션 클러스터를 각각 등록했거든요. Argo CD는 kubectl 명령어를 통해 쉽게 클러스터를 등록할 수 있도록 해줍니다.


# 먼저 Argo CD CLI를 설치합니다.
brew install argocd # macOS 기준

# Argo CD API 서버에 로그인합니다.
argocd login <ARGOCD_SERVER_IP_OR_HOSTNAME>

# 관리 대상 클러스터의 kubeconfig 컨텍스트로 전환합니다.
kubectl config use <MANAGED_CLUSTER_CONTEXT_NAME>

# 현재 컨텍스트의 클러스터를 Argo CD에 등록합니다.
argocd cluster add <MANAGED_CLUSTER_CONTEXT_NAME>

이 명령어를 실행하면 Argo CD가 해당 클러스터에 필요한 RBAC(Role-Based Access Control) 권한을 자동으로 설정하고, 클러스터를 관리 목록에 추가합니다. 이게 정말 편리하더라고요. 제가 일일이 RBAC을 설정할 필요가 없어서 좋았어요.

Argo CD UI에서 여러 Kubernetes 클러스터가 관리되는 모습

Argo CD UI에 접속하면 이렇게 등록된 여러 클러스터들이 한눈에 보입니다. 각 클러스터의 상태도 직관적으로 확인할 수 있죠.

3. ApplicationSet 활용: 멀티 클러스터 배포의 꽃!

수동으로 각 클러스터에 Application(애플리케이션)을 생성하는 건 비효율적입니다. 여기서 ApplicationSet이 빛을 발합니다. ApplicationSet은 여러 클러스터에 동일하거나 유사한 형태의 Application을 자동으로 생성해주는 CRD(Custom Resource Definition)거든요. 제가 처음엔 Application을 복사 붙여넣기 했었는데, ApplicationSet을 알고 나서는 '아, 이래서 쓰는구나!' 하고 무릎을 탁 쳤습니다.

ApplicationSet을 사용하면 Git 리포지토리의 특정 경로에 있는 매니페스트를 여러 클러스터에 배포하거나, 클러스터 이름에 따라 다른 설정 값을 주입하는 등의 고급 배포 전략을 구현할 수 있습니다.

예시 YAML 코드를 한번 볼까요? 저는 Git 제너레이터를 이용해서 특정 Git 경로의 폴더들을 클러스터로 배포하는 방식을 즐겨 사용합니다.


apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: my-multi-cluster-app
spec:
  generators:
  - git:
      repoURL: https://github.com/my-org/my-gitops-repo.git
      revision: HEAD
      directories:
      - path: clusters/dev/*
      - path: clusters/stg/*
      - path: clusters/prod/*
  template:
    metadata:
      name: '{{path.basename}}-app'
      labels:
        app.kubernetes.io/managed-by: argocd
    spec:
      project: default
      source:
        repoURL: https://github.com/my-org/my-gitops-repo.git
        targetRevision: HEAD
        path: '{{path}}'
      destination:
        server: '{{path.basename | clusterServer}}' # 클러스터 이름에 따라 서버 URL 매핑
        namespace: default
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
          - CreateNamespace=true

위 예시에서는 clusters/dev, clusters/stg, clusters/prod 폴더 각각을 하나의 GitOps Application으로 인식하고, 해당 폴더 이름에 매핑되는 클러스터에 배포하도록 설정한 거예요. {{path.basename | clusterServer}}와 같은 템플릿 문법을 활용해서 클러스터의 서버 URL을 동적으로 주입할 수 있습니다. 물론 clusterServer 같은 함수는 직접 구현하거나, Argo CD의 List 제너레이터 등 다른 제너레이터를 활용하여 클러스터 정보를 직접 명시할 수도 있습니다.

Argo CD 멀티 클러스터 GitOps 베스트 프랙티스 체크리스트

이제 제가 경험하면서 중요하다고 느꼈던 Argo CD 멀티 클러스터 GitOps 베스트 프랙티스들을 체크리스트 형태로 정리해 보았습니다. 이대로만 따라 하셔도 웬만한 삽질은 피할 수 있을 거예요!

  1. ✅ 단일 Git 리포지토리(Single Source of Truth) 사용: 모든 클러스터와 애플리케이션의 상태는 하나의 Git 리포지토리에서 관리하는 것이 좋습니다. 폴더 구조를 잘 정리해서 혼란을 줄이세요. (예: repo/clusters/dev, repo/clusters/prod, repo/apps/my-app)
  2. ✅ ApplicationSet 적극 활용: 멀티 클러스터 배포의 핵심입니다. 클러스터별 배포, 환경별 차이점 관리 등을 ApplicationSet으로 자동화하세요.
  3. ✅ Helm(헬름) 또는 Kustomize(커스터마이즈)로 설정 관리: 환경(dev, stg, prod)별로 다른 설정이 필요할 때, Helm Values나 Kustomize Overlays를 사용하여 매니페스트의 차이를 관리합니다. 저는 Helm을 주로 사용하는데, 템플릿 기능이 강력해서 유연하게 대응할 수 있더라고요.
  4. ✅ RBAC(Role-Based Access Control) 최소 권한 원칙 준수: Argo CD 컨트롤 플레인과 각 관리 대상 클러스터 간의 통신 시, Argo CD가 필요한 최소한의 권한만 가지도록 RBAC을 설정해야 합니다. 보안은 아무리 강조해도 지나치지 않아요!
  5. ✅ Secret(시크릿) 관리 전략 수립: 민감 정보는 Git에 직접 올리지 않고, HashiCorp Vault, Sealed Secrets, External Secrets Operator 같은 도구를 사용하여 안전하게 관리해야 합니다.
  6. ✅ 자동 동기화(Automated Sync) 및 Self-Heal(자가 복구) 활성화: Git의 변경사항이 자동으로 클러스터에 반영되고, 클러스터의 상태가 Git과 다를 경우 자동으로 복구되도록 설정합니다. 이게 GitOps의 가장 큰 매력 중 하나죠.
  7. ✅ Rollback(롤백) 전략 수립 및 테스트: 문제가 발생했을 때 신속하게 이전 버전으로 롤백할 수 있도록 전략을 세우고, 실제 롤백 테스트를 주기적으로 수행하세요.
  8. ✅ 모니터링(Monitoring) 및 로깅(Logging) 구축: Argo CD의 상태, 배포 이력, 각 클러스터의 애플리케이션 상태 등을 모니터링하고 로깅 시스템에 연동하여 가시성을 확보해야 합니다. Prometheus(프로메테우스)와 Grafana(그라파나)는 국룰이죠.
  9. ✅ PreSync/PostSync Hooks(훅) 활용: 배포 전후에 특정 작업을 수행해야 할 경우, PreSync/PostSync Hooks를 사용하여 데이터베이스 마이그레이션이나 캐시 초기화 같은 작업을 자동화할 수 있습니다.

⚠️ 삽질 경험 & 트러블슈팅: 제가 겪었던 문제들

13년차 엔지니어도 삽질은 피할 수 없는 운명입니다. 제가 Argo CD 멀티 클러스터를 구축하면서 겪었던 몇 가지 삽질과 해결책을 공유해 드릴게요.

1. 네트워크 연결 문제: 방화벽은 항상 제 발목을 잡죠

문제: Argo CD Control Plane에서 Managed Cluster로 접근이 안 되는 경우가 있었습니다. 클러스터가 다른 VPC나 다른 데이터센터에 있을 때 주로 발생하더라고요.

해결: 뻔하지만 가장 중요한 건 방화벽(Firewall)과 네트워크 ACL(Access Control List) 설정입니다. Argo CD Control Plane이 Managed Cluster의 Kubernetes API 서버에 접근할 수 있도록 네트워크 경로를 열어줘야 합니다. 보통 443 포트를 사용하죠. 저는 보안 그룹 설정을 빼먹어서 한참 헤맸습니다. 😭

2. RBAC 권한 부족: 'Forbidden' 메시지는 언제나 당황스럽습니다

문제: Argo CD가 특정 클러스터에 애플리케이션을 배포하려는데 Forbidden 에러가 뜨는 경우가 있었습니다. ApplicationSet이 Application을 생성하지 못하거나, Application이 특정 리소스를 생성하지 못하는 상황이었죠.

해결: Argo CD가 Managed Cluster에 설치하는 argocd-manager ServiceAccount(서비스 어카운트)의 RBAC 권한을 확인해야 합니다. ClusterRole 또는 Role이 필요한 verbs(get, list, watch, create, update, patch, delete)와 resources(pods, deployments, services 등)를 가지고 있는지 점검해야 합니다. 저는 CustomResourceDefinition(CRD)을 배포하려는데 권한이 없어서 한참 고생했어요. CRD는 특별한 권한이 필요하거든요.

3. Sync Status 'Out Of Sync': Git과 실제 상태가 다를 때

문제: Argo CD UI에서 분명히 Sync를 했는데 계속 Out Of Sync 상태로 남아있는 경우가 있었습니다. 특히 Helm 차트를 사용할 때 자주 발생했죠.

해결: 여러 원인이 있을 수 있습니다. 첫째, Helm Hooks(훅)가 제대로 동작하지 않거나, helm.sh/hook-delete-policy 같은 주석이 설정되어 있지 않은 경우. 둘째, CRD가 먼저 배포되지 않은 상태에서 해당 CRD를 사용하는 리소스가 배포되려 할 때. 셋째, 클러스터 내부의 컨트롤러가 Git에 없는 변경을 일으키는 경우. 넷째, resource.customizations 설정을 통해 특정 리소스의 필드를 무시하도록 설정하는 방법도 있습니다. 저는 특히 CRD 배포 순서 때문에 많이 헷갈렸는데, PreSync Hook을 이용하거나, ApplicationSet에서 CRD Application을 먼저 배포하도록 순서를 조정해서 해결했습니다.

검증 및 결과: 이제 배포가 이렇게 편해집니다!

이런 삽질과 노하우를 바탕으로 Argo CD 멀티 클러스터 GitOps 환경을 제대로 구축하고 나니, 정말 배포의 패러다임이 바뀌는 것을 느꼈습니다. 제가 직접 Git에 커밋하고 푸시만 하면, 개발, 스테이징, 프로덕션 클러스터에 알아서 척척 배포되는 모습을 보면 정말 뿌듯하더라고요.

  • 🎉 일관성 있는 배포: 모든 클러스터에 동일한 방식으로 애플리케이션이 배포됩니다.
  • 🎉 배포 속도 향상: 수동 작업이 사라지고, Git 변경만으로 배포가 완료됩니다.
  • 🎉 가시성 확보: Argo CD UI에서 모든 클러스터의 애플리케이션 상태를 한눈에 파악할 수 있습니다.
  • 🎉 안정성 증가: 잘못된 배포는 Git 롤백으로 쉽게 되돌릴 수 있습니다.
Argo CD 대시보드에서 멀티 클러스터 배포 성공 현황

위 그림처럼 Argo CD 대시보드에서 여러 클러스터에 걸쳐 배포된 애플리케이션들의 상태를 실시간으로 확인할 수 있습니다. 모든 것이 'Synced' 상태일 때의 그 쾌감이란! (웃음)

마무리: 더 나은 GitOps 여정을 위해

오늘은 Argo CD 멀티 클러스터 GitOps에 대한 저의 경험과 베스트 프랙티스 체크리스트를 공유해드렸습니다. 처음에는 복잡하게 느껴질 수 있지만, 한번 구축하고 나면 정말 강력한 배포 시스템을 손에 넣게 될 겁니다. 저도 처음엔 헷갈렸는데, 계속 시도하고 삽질하면서 익숙해지더라고요. 독자 여러분도 이 글을 통해 성공적인 GitOps 여정을 시작하시길 바랍니다.

혹시 GitOps 환경에서 더 깊이 있는 보안 강화나, CI(Continuous Integration) 파이프라인과의 연동에 대해 궁금하시다면, 다음 글에서 다룰 예정이니 기대해주세요!

Argo CD 멀티 클러스터 GitOps 베스트 프랙티스 요약 체크리스트

지금까지의 내용을 요약한 체크리스트입니다. 여러분의 GitOps 환경을 점검할 때 유용하게 활용되길 바랍니다.

'IT > k8s' 카테고리의 다른 글

[k8s] Rancher 2.x에서 차세대로 마이그레이션: 실제 경험과 주요 변경점  (1) 2026.06.20
[k8s] Argo CD 멀티 클러스터 동기화 문제 해결: 실제 운영 사례와 디버깅 팁  (0) 2026.06.19
[k8s] Kubernetes 스토리지: Longhorn vs Rook-Ceph 성능 벤치마크  (0) 2026.06.18
[k8s] Argo CD 멀티 클러스터 GitOps 도입 사례: 운영 노하우와 도전 과제  (0) 2026.06.13
[k8s] Kustomize와 Helm, K8s 설정 관리 도구 실측 성능 비교  (0) 2026.06.12
[K8s] Pod Security Admission 1년 사용 후기 및 실수담  (0) 2026.06.10

관련글

티스토리툴바