[k8s] Argo CD 멀티 클러스터 동기화 문제 해결: 실제 운영 사례와 디버깅 팁

목차

• Argo CD 멀티 클러스터 동기화 문제 해결: 실제 운영 사례와 디버깅 팁
• Argo CD, GitOps, 그리고 멀티 클러스터, 이게 뭔가요?
• Argo CD 멀티 클러스터 설정과 흔한 문제 시나리오
• ⚠️ 실제 운영 사례로 본 Argo CD 동기화 문제와 디버깅 팁
• ✅ 문제 해결 후 검증하기
• 마무리하며: 삽질은 경험이 되고, 경험은 자산이 됩니다.

Argo CD 멀티 클러스터 동기화 문제 해결: 실제 운영 사례와 디버깅 팁

안녕하세요, 13년차 서버실 지킴이입니다. 요즘 쿠버네티스(Kubernetes) 환경에서 GitOps(깃옵스)를 도입하는 기업들이 정말 많죠? 저도 홈랩과 회사 프로젝트에서 Argo CD(아르고 CD)를 활용해서 여러 쿠버네티스 클러스터를 관리하고 있는데요. 처음엔 "와, 이거 정말 편하겠다!" 싶었는데, 막상 실제 운영 환경에서 멀티 클러스터(Multi-Cluster) 동기화 문제를 만나면 머리가 지끈거릴 때가 많더라고요.

특히 여러 클러스터에 동일한 애플리케이션을 배포하거나, 환경별로 미묘하게 다른 설정을 적용해야 할 때 ApplicationSet(애플리케이션셋)을 쓰면 정말 유용하거든요. 그런데 간혹 특정 클러스터만 동기화가 안 되거나, 알 수 없는 에러로 삽질을 거듭하곤 해요. 제가 직접 겪었던 Argo CD 멀티 클러스터 동기화 문제들과 그 해결 과정을 솔직하게 공유해볼까 해요. 혹시 비슷한 경험으로 고생하고 계시다면, 이 글이 작은 힌트라도 되었으면 좋겠네요! 💡

Argo CD 멀티 클러스터 관리 아키텍처: Git을 중심으로 Argo CD가 여러 쿠버네티스 클러스터에 애플리케이션을 배포하고 동기화하는 흐름을 보여줍니다.

Argo CD, GitOps, 그리고 멀티 클러스터, 이게 뭔가요?

본격적인 문제 해결에 앞서, 핵심 개념들을 간단히 짚고 넘어갈게요. "아, 이건 다 아는데!" 하시는 분들도 계시겠지만, 혹시 처음 접하시는 분들을 위해 쉽게 풀어 설명해 드릴게요.

• Argo CD (아르고 CD): 쿠버네티스 환경에서 GitOps를 구현하기 위한 대표적인 선언적(Declarative) CD(Continuous Delivery, 지속적 배포) 툴입니다. Git 저장소를 애플리케이션의 '원본 소스(Single Source of Truth)'로 삼아, 쿠버네티스 클러스터의 실제 상태가 Git에 정의된 상태와 일치하도록 지속적으로 동기화(Synchronization)를 시도하죠. 즉, Git에 코드를 푸시하면 Argo CD가 알아서 클러스터에 배포해주는 방식입니다.
• GitOps (깃옵스): Git을 운영의 중심(Operational Hub)으로 삼아 인프라와 애플리케이션의 모든 상태를 관리하는 방식입니다. 모든 변경 사항이 Git에 기록되므로, 누가 언제 무엇을 변경했는지 추적하기 쉽고, 문제가 생겼을 때 쉽게 롤백(Rollback)할 수 있다는 장점이 있습니다. "Git에서 정의한 대로 클러스터 상태를 유지한다"는 철학이죠.
• 멀티 클러스터 (Multi-Cluster): 여러 개의 쿠버네티스 클러스터를 동시에 관리하는 환경을 의미합니다. 개발, 스테이징, 프로덕션 환경을 분리하거나, 재해 복구(Disaster Recovery)를 위해 여러 리전에 클러스터를 운영할 때 등 다양한 이유로 멀티 클러스터 환경을 구축합니다. Argo CD는 하나의 중앙 집중식(Centralized) 컨트롤 플레인(Control Plane)으로 여러 원격 클러스터(Remote Cluster)를 관리할 수 있게 해줍니다.

Argo CD 멀티 클러스터 설정과 흔한 문제 시나리오

Argo CD를 이용해 멀티 클러스터를 관리하려면, 먼저 Argo CD 컨트롤 플레인이 설치된 클러스터(보통 '관리 클러스터')에 다른 클러스터들을 등록해야 합니다. argocd cluster add 명령어가 이걸 해주죠. 이때 Argo CD가 원격 클러스터에 접근할 수 있는 ServiceAccount와 ClusterRoleBinding을 생성해줍니다.

그리고 여러 클러스터에 애플리케이션을 배포할 때는 주로 ApplicationSet을 사용합니다. 예를 들어, 다음과 같은 ApplicationSet으로 여러 클러스터에 nginx-app을 배포한다고 가정해봅시다.

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: my-nginx-appset
spec:
  generators:
  - clusters: {}
  template:
    metadata:
      name: '{{name}}-nginx-app'
    spec:
      project: default
      source:
        repoURL: https://github.com/my-org/my-gitops-repo.git
        targetRevision: HEAD
        path: apps/nginx
      destination:
        server: '{{server}}'
        namespace: default
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

이렇게 설정하면 Argo CD가 등록된 모든 클러스터에 apps/nginx 경로의 매니페스트를 배포하려고 시도합니다. 그런데 여기서 문제가 발생하곤 해요. 어떤 클러스터는 잘 동기화(SYNCED)되는데, 다른 클러스터는 계속 OutOfSync 상태이거나 Failed 상태를 벗어나지 못하는 거죠. "아니, 분명 다 똑같이 설정했는데 왜 이럴까?" 하는 생각이 절로 듭니다. 저도 처음엔 정말 막막했는데, 몇 가지 공통적인 원인이 있더라고요. 😅

Argo CD UI의 ApplicationSet 대시보드: 여러 클러스터에 배포된 애플리케이션들의 동기화 상태를 한눈에 볼 수 있으며, 문제가 발생한 애플리케이션을 쉽게 식별할 수 있습니다.

⚠️ 실제 운영 사례로 본 Argo CD 동기화 문제와 디버깅 팁

제가 13년 동안 쌓은 삽질 경험을 바탕으로, Argo CD 멀티 클러스터 환경에서 자주 발생하는 동기화 문제와 그 해결책을 알려드릴게요. 하나씩 체크하다 보면 분명 원인을 찾을 수 있을 겁니다!

1. RBAC (Role-Based Access Control) 권한 문제
   가장 흔하면서도 놓치기 쉬운 문제예요. Argo CD 컨트롤 플레인이 관리 대상 클러스터에 배포할 권한이 없는 경우입니다. argocd cluster add 명령어가 자동으로 필요한 권한을 생성해주지만, 간혹 수동으로 클러스터를 추가했거나, 보안 정책상 특정 권한이 누락된 경우가 있거든요.
   • 관리 대상 클러스터에서 kubectl get serviceaccount argocd-manager -n argocd 명령어로 argocd-manager ServiceAccount가 잘 생성되었는지 확인하세요.
   • 이 ServiceAccount에 연결된 ClusterRoleBinding과 ClusterRole의 권한을 확인해보세요. 보통 cluster-admin 권한이 부여되는데, 만약 특정 리소스에 대한 권한만 있다면 해당 리소스 배포가 실패할 수 있거든요. kubectl describe clusterrole argocd-manager-role 명령으로 권한 목록을 볼 수 있습니다.
   • 특히 ServiceAccount가 아닌 다른 방식으로 인증(예: kubeconfig 파일)을 사용한다면, 해당 kubeconfig 파일에 정의된 사용자에게 충분한 권한이 있는지 확인해야 합니다.
2. 💡 디버깅 팁:
3. 네트워크 연결 문제
   Argo CD 서버가 관리 대상 클러스터의 쿠버네티스 API 서버에 접근할 수 없는 경우네요. 방화벽, VPN, VPC 피어링 등 네트워크 구성을 꼼꼼히 확인해야 합니다. "어제까진 잘 됐는데?" 하다가 네트워크 변경 때문에 막히는 경우가 꽤 있거든요.
   • Argo CD UI에서 해당 클러스터의 상태가 Unavailable인지 확인하세요.
   • Argo CD 컨트롤러 파드(Pod)에서 관리 대상 클러스터의 API 서버로 curl 같은 명령어로 접속을 시도해보세요. 파드에 접속하는 방법은 kubectl exec -it <argocd-repo-server-pod> -n argocd -- bash 후 curl -k https://<cluster-api-server-ip>:<port>/healthz 와 같이 시도해볼 수 있습니다.
   • argocd cluster add 시 입력한 API 서버 주소가 올바른지 다시 한번 확인해보세요. 내부망 주소여야 할 때 외부망 주소를 입력하거나, 그 반대인 경우도 있거든요.
4. 💡 디버깅 팁:
5. ApplicationSet 설정 오류
   ApplicationSet의 generator나 template 설정이 잘못된 경우예요. 특히 cluster 필터링이나 Git 저장소 경로(path)를 잘못 지정했을 때 문제가 발생하곤 합니다.
   • argocd appset get <application-set-name> 명령으로 ApplicationSet의 현재 상태와 생성된 Application 목록을 확인해보세요.
   • ApplicationSet의 template 섹션에서 source.path가 Git 저장소의 실제 경로와 일치하는지 확인하세요. 대소문자나 오타가 있을 수 있거든요.
   • generator에서 특정 클러스터만 선택하도록 설정했다면, 해당 클러스터의 라벨(labels)이 selector와 정확히 일치하는지 확인해보세요.
6. 💡 디버깅 팁:
7. 배포하려는 리소스 매니페스트 오류
   Git 저장소에 있는 쿠버네티스 매니페스트(YAML 파일) 자체에 문제가 있는 경우네요. 문법 오류, 잘못된 필드 이름, 존재하지 않는 StorageClass 참조 등이 있을 수 있거든요.
   • Argo CD UI에서 Application 상태를 확인하고, Events(이벤트) 탭이나 Logs(로그) 탭을 자세히 살펴보세요. 어떤 리소스에서 어떤 에러가 발생했는지 상세하게 나옵니다. 예를 들어, "admission webhook denied the request" 같은 메시지는 Admission Controller(어드미션 컨트롤러)나 OPA Gatekeeper 같은 정책 엔진에 의해 배포가 거부되었음을 의미할 수 있어요.
   • 해당 클러스터에 직접 kubectl apply -f <problematic-manifest.yaml> --dry-run=client 로 배포를 시도하여 문법 오류 등을 미리 확인해보세요.
   • kubectl describe <resource-type> <resource-name> -n <namespace> 명령으로 대상 클러스터에 배포된(혹은 배포 실패한) 리소스의 상세 상태를 확인하세요.
8. 💡 디버깅 팁:
9. Argo CD 컨트롤러 파드 문제
   아주 드물지만, Argo CD 자체의 argocd-application-controller나 argocd-repo-server 파드에 문제가 생겨 동기화가 제대로 작동하지 않을 수 있어요. 리소스 부족, 네트워크 문제, 버그 등이 원인일 수 있거든요.
   • kubectl get pods -n argocd 명령으로 Argo CD 관련 파드들이 모두 Running 상태인지 확인해보세요.
   • 문제 있어 보이는 파드의 로그를 확인해보세요: kubectl logs -f <argocd-pod-name> -n argocd. 특히 argocd-application-controller 로그에 동기화 관련 오류 메시지가 나타날 수 있거든요.
   • 파드를 재시작하거나, 리소스(CPU, Memory)를 늘려주는 것도 방법이 될 수 있습니다.
10. 💡 디버깅 팁:

✅ 문제 해결 후 검증하기

위의 팁들을 바탕으로 문제를 해결했다면, 이제 제대로 동기화가 되는지 확인해야겠죠? 드디어 SYNCED 상태를 봤을 때의 그 쾌감이란! 🎉

1. Argo CD UI/CLI 확인
   가장 먼저 Argo CD UI에 접속해서 해당 Application 또는 ApplicationSet의 상태가 Synced 그리고 Healthy로 표시되는지 확인합니다. CLI를 선호한다면 argocd app list 나 argocd app get <application-name> 명령어를 사용해보세요.
2. 대상 클러스터 직접 확인
   Argo CD UI/CLI에서 Synced로 표시되더라도, 혹시 모르니 해당 클러스터에 접속해서 kubectl get <resource-type> -n <namespace> 명령으로 실제로 리소스가 배포되었는지, 상태는 어떤지 직접 확인하는 게 좋습니다. 특히 Deployment나 StatefulSet의 파드들이 정상적으로 Running 상태인지 확인해 주세요.
3. 새로운 변경사항 푸시 테스트
   Git 저장소에 간단한 변경사항(예: ConfigMap 내용 변경)을 푸시해서 Argo CD가 변경을 감지하고 자동으로 동기화하는지 확인해봅니다. 이 과정이 원활하게 진행된다면 성공적으로 문제를 해결한 거예요!

성공적인 Argo CD 동기화 대시보드: 모든 애플리케이션이 문제없이 배포되고 동기화되어 안정적인 운영 상태를 보여줍니다.

마무리하며: 삽질은 경험이 되고, 경험은 자산이 됩니다.

오늘은 Argo CD 멀티 클러스터 동기화 문제 해결에 대한 저의 경험과 디버깅 팁을 공유해드렸습니다. 솔직히 저도 처음엔 정말 막막해서 밤늦게까지 삽질 좀 했거든요. "왜 안 되는 거지?" 하면서 클러스터 여기저기를 들쑤시고 다녔던 기억이 생생해요. 😂

하지만 이런 삽질 과정이 결국 저의 노하우가 되고, 여러분 같은 동료 인프라 엔지니어분들께 도움이 되는 자산이 된다는 사실을 깨달았습니다. Argo CD는 정말 강력한 툴이지만, 그만큼 복잡한 환경에서는 예상치 못한 문제들이 발생할 수 있어요. 중요한 건 문제를 만났을 때 당황하지 않고, 차근차근 원인을 찾아 해결해나가는 자세라고 생각합니다.

이번 글이 Argo CD 멀티 클러스터 환경에서 고군분투하는 분들께 조금이나마 도움이 되었기를 바랍니다. 다음 글에서는 Argo CD의 Progressive Delivery(점진적 배포) 전략인 Argo Rollouts에 대해 다뤄볼게요. 그때까지 GitOps 즐겁게 운영하시길 바랍니다! 궁금한 점이 있다면 언제든 댓글 남겨주세요! 😊

Argo CD 멀티 클러스터 동기화 문제 해결 체크리스트: RBAC, 네트워크, ApplicationSet 설정, 매니페스트 오류, Argo CD 파드 상태 등 주요 점검 사항을 요약한 인포그래픽입니다.

📚 함께 읽으면 좋은 글

• Kubernetes 스토리지: Longhorn vs Rook-Ceph 성능 벤치마크
• Argo CD 멀티 클러스터 GitOps 베스트 프랙티스 체크리스트
• Argo CD 멀티 클러스터 GitOps 도입 사례: 운영 노하우와 도전 과제
• Proxmox 클러스터 1년 사용 후기: 안정성, 성능, 그리고 예상치 못한 문제들
• Proxmox HA 클러스터 구축 실패 사례와 교훈: 3년차 엔지니어의 회고