본문 바로가기
IT/k8s

[k8s] ArgoCD 멀티 클러스터 배포 전략: GitOps로 K8s 여러 환경을 효과적으로 관리하기

by 수누다 2026. 5. 16.

목차

ArgoCD 멀티 클러스터 배포 전략: GitOps로 K8s 여러 환경을 효과적으로 관리하기

안녕하세요, 13년차의 서버실 주인장입니다. 오늘은 인프라 엔지니어라면 한 번쯤은 고민해봤을 주제, 바로 ArgoCD 멀티 클러스터 배포 전략에 대해 이야기해보려고 합니다. 개발, 스테이징, 프로덕션은 기본이고, DR(재해 복구)이나 여러 리전(Region)에 걸쳐 수많은 쿠버네티스(Kubernetes) 클러스터를 운영하다 보면, "이걸 어떻게 하면 효율적으로 관리할 수 있을까?"라는 질문에 부딪히게 되죠. 저도 예전에 수많은 클러스터들을 수동으로 관리하면서 밤샘 삽질 꽤나 했거든요. 수동 배포는 휴먼 에러의 온상이었고, 클러스터 간 설정 불일치는 늘 제 발목을 잡았습니다. 그러다 GitOps(깃옵스)라는 개념과 ArgoCD(아르고CD)를 만나면서 비로소 광명을 찾았다고 할까요? 오늘은 제가 홈랩과 실제 운영 환경에서 겪었던 경험을 바탕으로, ArgoCD를 이용해 여러 쿠버네티스 환경을 GitOps 방식으로 효과적으로 관리하는 노하우를 공유해드리겠습니다.

그림 1: ArgoCD 멀티 클러스터 배포의 전체 아키텍처 개요

GitOps와 ArgoCD, 그리고 멀티 클러스터 관리의 핵심

먼저 핵심 개념부터 짚고 넘어갈까요? GitOps(깃옵스)는 쉽게 말해, Git(깃)을 인프라 및 애플리케이션 배포의 단일 진실 공급원(Single Source of Truth)으로 사용하는 운영 방식입니다. 모든 클러스터 설정, 애플리케이션 매니페스트 등을 Git 리포지토리에 저장하고, 변경 사항은 Git을 통해서만 적용하는 거죠. 이렇게 하면 누가 언제 무엇을 변경했는지 Git 기록으로 명확하게 남고, 필요하면 언제든 이전 상태로 롤백(Rollback)할 수 있습니다.

그리고 이 GitOps를 쿠버네티스 환경에서 가장 강력하게 구현해주는 도구가 바로 ArgoCD(아르고CD)입니다. ArgoCD는 선언형 GitOps CD 도구로, Git 리포지토리에 정의된 상태와 실제 쿠버네티스 클러스터의 상태를 지속적으로 비교하고, 불일치하면 자동으로 동기화해줍니다. 마치 클러스터의 '자율 주행' 시스템 같다고 할까요? 제가 직접 써보니까, 배포 파이프라인의 복잡성을 확 줄여주면서도 안정성은 훨씬 높아지더라고요.

ArgoCD 멀티 클러스터 관리는 이를 더 확장해, 하나의 중앙 ArgoCD 인스턴스가 여러 개의 원격 쿠버네티스 클러스터(Remote Kubernetes Clusters)에 애플리케이션을 배포하고 관리하는 것을 의미합니다. 중앙 ArgoCD 서버에 원격 클러스터들을 등록하면, ArgoCD는 각 클러스터에 접근하여 Git에 정의된 애플리케이션들을 배포하고 동기화 상태를 유지합니다. 복잡한 Jenkins 파이프라인이나 스크립트 없이도, Git만 잘 관리하면 여러 클러스터를 일관된 상태로 유지할 수 있게 되는 거죠. 이거 진짜 편하더라고요!

실전 구현: ArgoCD로 여러 쿠버네티스 환경 관리하기

자, 그럼 이제 실제 어떻게 구성하는지 단계별로 알아볼까요? 제가 홈랩에서 여러 클러스터를 구성하면서 가장 효과적이었던 방법을 공유합니다.

1. 중앙 ArgoCD 인스턴스 설치 (Central Cluster)

가장 먼저, 모든 것을 관장할 중앙 쿠버네티스 클러스터에 ArgoCD를 설치해야 합니다. 저는 주로 `argocd` 네임스페이스에 설치하는데, 설치 방법은 공식 문서가 워낙 잘 되어 있으니 참고해주세요. Helm(헬름)이나 Kustomize(커스터마이즈)를 사용하면 쉽게 설치할 수 있습니다.

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

# ArgoCD CLI 설치 (macOS 예시)
brew install argocd

2. 원격 클러스터 등록하기

이제 ArgoCD가 관리할 원격 쿠버네티스 클러스터들을 등록해야 합니다. ArgoCD는 `kubectl` 컨텍스트를 활용하여 클러스터를 추가할 수 있습니다. 각 클러스터에 접속할 수 있는 권한이 있는 상태에서 다음 명령어를 실행하면 됩니다.

# 현재 kubectl 컨텍스트 목록 확인
kubectl config get-contexts

# 원격 클러스터 컨텍스트로 전환 (예: my-remote-cluster)
kubectl config use-context my-remote-cluster

# ArgoCD에 클러스터 등록
argocd cluster add my-remote-cluster --name <클러스터_이름> # --name 옵션으로 ArgoCD UI에 표시될 이름 지정

이 명령어를 실행하면 ArgoCD는 해당 클러스터에 argocd-manager 서비스 어카운트(Service Account)와 필요한 RBAC(Role-Based Access Control) 권한을 자동으로 생성합니다. 처음엔 권한 문제로 좀 헤맸는데, 이 서비스 어카운트 방식이 제일 깔끔하더라고요. 여러 클러스터를 등록했다면, ArgoCD UI에서 다음과 같이 등록된 클러스터 목록을 확인할 수 있습니다.

그림 2: ArgoCD UI에 등록된 멀티 쿠버네티스 클러스터 목록

3. Git 리포지토리 구성 전략

GitOps의 핵심인 Git 리포지토리를 어떻게 구성하느냐가 중요합니다. 저는 주로 모노레포(Monorepo) 방식을 선호합니다. 모든 클러스터의 설정과 애플리케이션 매니페스트를 하나의 리포지토리에 모아두면 관리하기가 훨씬 수월하더라고요. 추천하는 디렉토리 구조는 다음과 같습니다.

. 
├── clusters/
│   ├── dev/
│   │   └── cluster-config.yaml
│   ├── stage/
│   │   └── cluster-config.yaml
│   └── prod/
│       └── cluster-config.yaml
└── applications/
    ├── my-app/
    │   ├── base/
    │   │   ├── deployment.yaml
    │   │   └── service.yaml
    │   └── overlays/
    │       ├── dev/
    │       │   └── kustomization.yaml
    │       │   └── values.yaml
    │       ├── stage/
    │       │   └── kustomization.yaml
    │       │   └── values.yaml
    │       └── prod/
    │           └── kustomization.yaml
    │           └── values.yaml
    └── another-app/
        └── ...

clusters/ 디렉토리에는 각 클러스터별로 필요한 기본 설정(예: 네임스페이스 생성, RBAC 설정 등)을 담고, applications/ 디렉토리에는 배포할 애플리케이션의 매니페스트를 저장합니다. 특히 Kustomize(커스터마이즈)를 활용하여 base와 overlays 구조를 만들면, 클러스터별로 다른 설정을 유연하게 적용할 수 있습니다. 예를 들어, my-app/base에 공통적인 배포 스펙을 정의하고, my-app/overlays/prod에서 프로덕션 환경에 필요한 리소스 제한(Resource Limit)이나 레플리카(Replica) 수를 오버라이드(Override)하는 식이죠.

4. ApplicationSet 활용: 동적인 애플리케이션 배포

여러 클러스터에 동일한 애플리케이션을 배포해야 할 때, ArgoCD의 ApplicationSet(애플리케이션셋)은 정말 빛을 발합니다. ApplicationSet은 여러 ArgoCD Application(애플리케이션)을 동적으로 생성해주는 컨트롤러(Controller)입니다. 저는 주로 Git Generator(깃 제너레이터)를 사용하는데, 특정 Git 경로에 있는 디렉토리 목록을 읽어서 각 디렉토리마다 Application을 생성하도록 합니다.

예를 들어, applications/my-app/overlays/ 디렉토리 아래에 dev, stage, prod 디렉토리가 있다면, ApplicationSet이 이 세 디렉토리를 각각의 클러스터에 배포할 Application으로 인식하게 만들 수 있습니다.

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: all-my-apps
spec:
  generators:
  - git:
      repoURL: https://github.com/my-org/my-gitops-repo.git # 본인의 Git 리포지토리 URL
      revision: HEAD
      directories:
      - path: applications/*/overlays/* # 이 경로 아래의 모든 디렉토리를 찾아서 Application 생성
  template:
    metadata:
      name: '{{ path[2] }}-{{ path[4] }}' # 예: my-app-dev
      labels:
        app.kubernetes.io/part-of: '{{ path[2] }}'
    spec:
      project: default
      source:
        repoURL: https://github.com/my-org/my-gitops-repo.git
        targetRevision: HEAD
        path: '{{ path }}'
      destination:
        server: https://kubernetes.default.svc # ArgoCD에 등록된 클러스터의 API 서버 URL
        namespace: '{{ path[2] }}' # 예: my-app
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
          - CreateNamespace=true

위 예시에서 {{ path[2] }}와 {{ path[4] }}는 Git 경로를 기준으로 동적으로 값을 가져오는 변수입니다. 이렇게 ApplicationSet을 사용하면, 새로운 클러스터나 애플리케이션 환경이 추가될 때마다 Application 매니페스트를 일일이 만들 필요 없이, Git에 디렉토리만 추가하면 ArgoCD가 알아서 감지하고 배포해줍니다. 이 부분에서 정말 많은 시간을 절약할 수 있더라고요!

ArgoCD 멀티 클러스터 배포 중 주의할 점들: ⚠️ 제가 겪었던 삽질 모음

아무리 좋은 도구라도 삽질은 피할 수 없는 법이죠. 제가 ArgoCD 멀티 클러스터를 구성하면서 겪었던 주요 문제점들과 해결책을 공유합니다. 혹시 이런 경험 있으신가요?

  1. 권한 문제 (RBAC Hell): argocd cluster add 명령어가 클러스터에 argocd-manager 서비스 어카운트를 생성하지만, 때로는 특정 리소스에 대한 권한이 부족할 때가 있습니다. 특히 CRD(Custom Resource Definition)를 배포하거나 특정 오퍼레이터(Operator)를 사용할 때 권한 에러가 발생하곤 합니다. 💡 해결책: 에러 메시지를 꼼꼼히 확인하고, 필요한 권한(Role, ClusterRole)을 추가로 부여하거나, 가장 간단하게는 cluster-admin 권한을 일시적으로 부여하여 문제가 해결되는지 확인해볼 수 있습니다. 하지만 운영 환경에서는 최소 권한 원칙(Principle of Least Privilege)을 지키는 것이 중요합니다. 저도 처음엔 클러스터 등록이 자꾸 실패해서 몇 시간을 날렸는지 몰라요.
  2. 네트워크 문제: 중앙 ArgoCD 인스턴스가 원격 클러스터의 API 서버에 접근하지 못하는 경우가 있습니다. 방화벽(Firewall), 보안 그룹(Security Group), VPC(Virtual Private Cloud) 설정 등이 원인일 수 있습니다. 💡 해결책: ArgoCD 서버가 실행되는 Pod에서 원격 클러스터의 API 서버 IP 주소와 포트로 telnet이나 curl을 시도하여 연결성을 확인해보세요. 저도 한번은 사설망 연결 문제로 고생 좀 했습니다. ㅎㅎ
  3. Helm Values 오버라이드 복잡성: ApplicationSet과 Helm(헬름) 차트(Chart)를 함께 사용할 때, 클러스터별로 다른 values.yaml 파일을 관리하는 것이 복잡해질 수 있습니다. 💡 해결책: Kustomize의 patches 기능을 활용하여 Helm Chart의 특정 값을 오버라이드하거나, ApplicationSet의 parameters 기능을 이용해 클러스터별로 다른 값을 주입하는 방식을 사용해보세요. 이 과정에서 Git 리포지토리 구조를 잘 설계하는 것이 핵심입니다.
  4. Git Sync 지연 및 캐시 문제: Git 리포지토리에 변경 사항을 푸시(Push)했는데, ArgoCD가 즉시 감지하지 못하거나 오래된 캐시 데이터를 사용하는 경우가 있습니다. 💡 해결책: ArgoCD UI에서 수동으로 Sync(동기화)를 시도하거나, Git Webhook(웹훅)을 설정하여 Git 변경 이벤트 발생 시 ArgoCD가 즉시 알림을 받고 동기화를 시작하도록 구성하는 것이 좋습니다. 그래도 안 되면 ArgoCD 서버 Pod를 재시작해보는 것도 한 방법이더라고요.

검증 및 결과: 🎉 이제 편안하게 관리해볼까요?

모든 설정이 완료되고 나면, ArgoCD UI는 마치 잘 정돈된 지휘소처럼 느껴질 겁니다. 등록된 모든 클러스터와 그 위에 배포된 애플리케이션들의 상태를 한눈에 볼 수 있죠. Git에 코드 푸시하고 잠시 후 ArgoCD 대시보드를 보면, 모든 클러스터에 배포가 쫙~ 완료되어 있는 걸 볼 수 있습니다. 이 쾌감이란!

새로운 클러스터에 애플리케이션을 배포해야 할 때도, ApplicationSet을 통해 정의된 Git 리포지토리 구조에 맞게 단순히 새로운 오버레이(Overlay) 디렉토리와 Kustomization 파일을 추가하고 Git에 커밋(Commit)하기만 하면 됩니다. ArgoCD가 이를 감지하고 자동으로 새로운 Application을 생성하고 배포해줍니다. 인프라 변경 관리의 일관성과 자동화 수준이 비약적으로 향상되는 순간이죠.

그림 3: ArgoCD UI에서 확인하는 멀티 클러스터 애플리케이션 동기화 상태

ArgoCD 멀티 클러스터 배포의 장점과 한계

제가 13년 동안 다양한 인프라 환경을 경험하면서 느낀 ArgoCD 멀티 클러스터 배포의 장점과 한계를 정리해봤습니다.

장점 ✅ 한계 ⚠️
일관성 유지: 모든 클러스터가 Git에 정의된 동일한 상태를 따르므로, 환경 간 불일치를 최소화합니다. 초기 설정 복잡성: Git 리포지토리 구조, ApplicationSet 설정 등 초기 구성에 학습 곡선이 존재합니다.
배포 자동화: Git 변경 사항이 자동으로 감지되어 배포되므로, 수동 작업으로 인한 오류를 줄입니다. GitOps 모델 이해 필요: 개발/운영 팀 모두 GitOps 워크플로우에 대한 이해와 적응이 필요합니다.
빠른 복구 (Disaster Recovery): Git에 모든 설정이 있으므로, 장애 발생 시 새로운 클러스터에 빠르게 복구할 수 있습니다. 중앙 ArgoCD 인스턴스 의존성: 중앙 ArgoCD 서버에 장애가 발생하면 모든 클러스터 배포에 영향을 미칠 수 있습니다 (HA 구성으로 보완 가능).
버전 관리 및 감사: 모든 변경 이력이 Git에 남아 누가 언제 무엇을 변경했는지 추적하기 용이합니다. 시크릿(Secret) 관리: Git에 민감 정보를 직접 저장하기 어려우므로, Vault(볼트) 등 별도의 시크릿 관리 솔루션과 연동해야 합니다.

마무리: 💡 ArgoCD 멀티 클러스터 배포, 지금 시작해볼까?

오늘은 ArgoCD를 활용한 멀티 쿠버네티스 클러스터 배포 전략에 대해 제가 직접 경험하고 삽질하며 얻은 노하우를 공유해드렸습니다. GitOps는 단순히 배포 도구를 넘어, 인프라 운영 패러다임을 혁신하는 강력한 방법론이라고 생각합니다. 13년차 엔지니어로서, 이 정도 자동화는 이제 선택이 아니라 필수라고 생각합니다. 처음엔 좀 어렵고 헷갈릴 수 있지만, 한번 구축하고 나면 정말 편안하고 안정적인 인프라를 운영할 수 있을 거예요.

여러분도 이 글을 통해 ArgoCD 멀티 클러스터 환경 구축에 자신감을 얻으셨기를 바랍니다. 다음 글에서는 ArgoCD의 고가용성(High Availability, HA) 구성이나 외부 시크릿 관리 도구(예: HashiCorp Vault)와의 연동 등 좀 더 심화된 주제를 다뤄볼까 합니다. 궁금한 점이나 공유하고 싶은 삽질 경험이 있다면 언제든지 댓글로 남겨주세요!

그림 4: ArgoCD 멀티 클러스터 배포의 핵심 요약 및 다음 단계

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

[k8s] 쿠버네티스 Ingress Controller 비교: Nginx, Traefik, HAProxy 장단점 분석  (0) 2026.05.18
[k8s] ArgoCD GitOps CI/CD 구축: 쿠버네티스 자동 배포 완벽 가이드  (0) 2026.05.18
[k8s] k3s와 MicroK8s 비교: 경량 쿠버네티스 환경 선택 가이드  (0) 2026.05.18
[k8s] Flux CD GitOps 파이프라인 구축: 안정적인 쿠버네티스 배포 자동화  (0) 2026.05.15
[k8s] 쿠버네티스 서비스 메시: Istio vs Linkerd 심층 비교 및 선택 가이드  (0) 2026.05.14
[k8s] k3s로 경량 쿠버네티스 클러스터 구축: 홈랩과 엣지 완벽 가이드  (0) 2026.05.14

관련글

티스토리툴바