🐙 Argo CD 마스터 가이드: AppProject의 함정과 4가지 핵심 기능 파헤치기

쿠버네티스 운영의 핵심 도구인 Argo CD를 사용하다 보면 매니페스트 배포 그 이상의 세밀한 제어가 필요한 순간들이 옵니다.

오늘은 질문 주셨던 AppProject의 Destination 규칙에 대한 오해를 바로잡고, Argo CD의 고급 기능들인 workloadRef, sourceRepos, ignoreDifferences, 그리고 Slack 알림 설정까지 실무에서 바로 써먹을 수 있도록 아주 깊이 있게 정리해 보겠습니다! 🚀

 

안녕하세요! 오늘은 Argo CD를 사용하면서 한 번쯤은 마주하게 되는 복잡한 설정들을 완벽하게 정리해 보려 합니다. 특히 질문 주신 "어떤 Destination 설정이 유효한가?"에 대한 정답부터 시작해 보겠습니다.

---

0. 잠깐! AppProject Destination 규칙의 진실 🧐

질문하신 내용에서 혼란을 겪으셨던 부분부터 짚고 넘어갈게요. Argo CD의 AppProject에서 destinations를 정의할 때 가장 중요한 원칙은 와일드카드(*)의 사용 범위입니다.

• Server URL: https://team1-*과 같은 부분 일치 와일드카드는 지원하지 않습니다. 보통 *(모든 서버) 또는 정확한 URL을 적어야 합니다.
• Namespace: *(모든 네임스페이스)는 가능하지만, !kube-system*과 같은 부정형(!)이나 복잡한 정규표현식 패턴은 기본적으로 Destination 필드에서 지원되지 않습니다.

따라서 namespace: "!kube-system*"이 포함된 설정이 **Invalid(유효하지 않음)**한 설정이 됩니다. (Argo CD는 명시적으로 허용된 리스트만 관리하는 화이트리스트 방식이기 때문입니다.)

---

1. workloadRef: 아르고가 리소스를 추적하는 똑똑한 방법 🔍

workloadRef는 Argo CD Application의 status 필드에서 볼 수 있는 기능으로, 애플리케이션이 관리하는 리소스들 중 어떤 것이 '메인 워크로드'인지 참조하는 기능입니다.

• 왜 쓰나요? 커스텀 리소스(CRD)를 사용할 때 Argo CD가 어떤 것이 실제 배포된 서비스의 상태를 나타내는 지표인지 알 수 있게 도와줍니다.
• 작동 방식: 주로 Rollouts와 같은 리소스와 연동될 때, 해당 Application이 어떤 Deployment나 Rollout을 대표하는지 명시합니다.

---

2. spec.sourceRepos: 보안의 시작, 허용 목록 관리 🛡️

AppProject 수준에서 설정하는 sourceRepos는 보안상 매우 중요합니다.

• 기능: 해당 프로젝트에 속한 Application들이 어떤 Git 저장소에서 소스를 가져올 수 있는지 제한합니다.
• 실무 팁: *를 사용하면 편리하지만, 팀별로 프로젝트를 나눌 때는 반드시 특정 조직의 Repo 주소만 허용하도록 화이트리스트를 관리해야 합니다.

📝 AppProject 설정 예시

YAML

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: team-alpha-project
  namespace: argocd
spec:
  # 이 프로젝트의 앱들은 아래 주소의 Repo만 사용할 수 있습니다.
  sourceRepos:
  - 'https://github.com/my-org/team-alpha-apps.git'
  - 'https://github.com/my-org/shared-charts.git'
  
  destinations:
  - namespace: 'alpha-*' # 와일드카드 사용 가능
    server: 'https://kubernetes.default.svc'

---

3. ignoreDifferences: "의도된 차이" 무시하기 🙈

쿠버네티스 리소스 중에는 배포 후 시스템에 의해 자동으로 값이 변하는 필드들이 있습니다. Argo CD는 이를 'OutOfSync'로 간주하는데, 이를 방지하는 것이 ignoreDifferences입니다.

• 주요 대상: * HPA에 의해 조절되는 Deployment의 replicas
  • Admission Controller에 의해 삽입되는 sidecar 컨테이너나 annotations
  • Service의 external-ip 등

📝 Application 설정 예시

YAML

 

spec:
  ignoreDifferences:
  - group: apps
    kind: Deployment
    jsonPointers:
    - /spec/replicas # HPA가 관리하므로 Git과 달라도 무시함
  - group: ""
    kind: Service
    name: my-service
    jsonPointers:
    - /metadata/annotations/last-updated # 특정 어노테이션 무시

---

4. Notifications: Slack으로 배포 결과 받기 📢

notifications.argoproj.io/subscribe.on-sync-succeeded.slack 어노테이션을 사용하면 배포 성공 시 즉시 슬랙 알림을 보낼 수 있습니다.

• 작동 원리: Argo CD Notifications 컨트롤러가 Application의 상태를 감시하다가 Sync Succeeded 이벤트가 발생하면 설정된 채널로 메시지를 쏩니다.

📝 실전 적용 (Application YAML)

YAML

 

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: production-api
  annotations:
    # 성공 시 'dev-alerts' 채널로 슬랙 알림 발송
    notifications.argoproj.io/subscribe.on-sync-succeeded.slack: dev-alerts
    # 실패 시에도 받고 싶다면?
    notifications.argoproj.io/subscribe.on-sync-failed.slack: dev-alerts
spec:
  project: default
  # ... 이하 생략

---

5. 요약 및 실무 체크리스트 🏁

기능	핵심 요약	주의 사항
AppProject Dest.	서버/네임스페이스 허용 목록 관리	부정형(!) 사용 불가, 서버 URL 부분 와일드카드 불가
workloadRef	리소스 간의 참조 관계 명시	커스텀 컨트롤러 제작 시 유용
sourceRepos	사용 가능한 Git Repo 제한	보안을 위해 최소 권한 원칙 준수
ignoreDifferences	불필요한 OutOfSync 방지	jsonPointers 경로를 정확히 작성할 것
Slack Noti.	실시간 배포 현황 공유	Argo CD 내에 Slack Token 설정이 선행되어야 함

---

Argo CD는 단순히 배포 도구를 넘어 클러스터의 상태를 관리하는 강력한 거버넌스 도구입니다. 오늘 배운 기능들을 조합하면 더욱 안전하고 편리한 GitOps 환경을 구축하실 수 있을 거예요! 🛠️