⚙️ Argo CD 마스터 가이드: syncPolicy와 syncOptions 심층 분석

안녕하세요! Argo CD를 사용하면서 "왜 내 리소스는 자동으로 삭제되지 않지?"라거나 "특정 순서대로 배포하고 싶은데 방법이 없을까?"라는 고민을 해보셨나요? 그 모든 해답은 애플리케이션 매니페스트의 spec.syncPolicy 섹션에 있습니다.

오늘은 배포의 정교함을 완성하는 다양한 동기화 옵션과 정책들을 상세히 알아보겠습니다. 🛠️

 

---

1. 🔍 spec.syncPolicy 핵심 속성 정리

syncPolicy는 Argo CD가 Git의 '희망 상태'와 클러스터의 '현재 상태'를 어떻게 맞출지 정의하는 최상위 정책입니다.

① automated (자동 동기화)

Git의 변경 사항을 감지하여 자동으로 클러스터에 반영합니다.

• prune: Git에서 삭제된 리소스를 클러스터에서도 삭제할지 여부 (기본값: false). 🗑️
• selfHeal: 클러스터 리소스를 수동으로 수정했을 때, 다시 Git 상태로 복구할지 여부 (기본값: false). 🏥

② retry (재시도 전략)

동기화 실패 시 재시도 횟수와 간격을 설정합니다.

• limit: 최대 재시도 횟수.
• backoff: 재시도 간격 (지수 백오프 지원). 🔁

---

2. ⚡ 핵심 syncOptions 상세 가이드

syncOptions는 동기화 과정에서 사용할 구체적인 기술 옵션들을 리스트 형태로 제공합니다.

✅ ApplyOutOfSyncOnly=true (성능 최적화)

기본적으로 Argo CD는 동기화 시 앱의 모든 리소스를 다시 apply 합니다. 하지만 리소스가 많다면 이는 큰 낭비입니다.

• 역할: 상태가 OutOfSync(동기화되지 않음)인 리소스만 골라서 업데이트를 수행합니다.
• 장점: API 서버 부하를 줄이고 동기화 속도를 비약적으로 높입니다. ⚡

✅ Replace=true (강제 갱신 전략)

Kubernetes의 특정 리소스는 kubectl apply를 통한 수정이 불가능한 경우가 있습니다. (예: Immutable 필드 변경)

• 역할: apply 대신 replace 또는 delete 후 create 방식을 사용하여 리소스를 강제로 갱신합니다.
• 주의: 리소스가 잠시 삭제될 수 있으므로 서비스 중단에 유의해야 합니다. 🛠️

✅ PrunePropagationPolicy=foreground (안전한 삭제)

리소스를 삭제할 때 자식 리소스(Pod 등)를 어떻게 처리할지 결정합니다.

• Foreground: 부모(Deployment 등)를 삭제하기 전, 자식 리소스들을 먼저 확실히 정리합니다. 가장 안전한 방식입니다. 🛡️
• Background (기본): 부모를 먼저 삭제하고 자식은 나중에 가비지 컬렉터가 처리합니다.

✅ CreateNamespace=true

대상 네임스페이스가 클러스터에 없을 경우, Argo CD가 자동으로 생성해 줍니다. 🏗️

---

3. 🌊 배포 순서의 마법: Sync Waves

애플리케이션을 배포할 때 "DB가 먼저 뜨고 나서 WAS가 떠야 해"와 같은 순서가 필요할 때 사용합니다. 이는 syncOptions가 아닌 개별 리소스의 Annotation으로 설정합니다.

• 동작 원리: 낮은 숫자(예: -5)부터 높은 숫자(예: 10) 순서대로 리소스를 배포합니다.
• 이점: 의존성이 복잡한 마이크로서비스 환경에서 배포 안정성을 보장합니다. 🌊

---

4. 💻 실전 코드: 전체 설정 예시

위의 모든 내용을 종합한 Argo CD Application 매니페스트입니다. 주석을 통해 각 설정의 의미를 다시 확인해 보세요.

YAML

 

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: master-ops-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: 'https://github.com/my-org/manifests.git'
    targetRevision: main
    path: apps/my-service
  destination:
    server: 'https://kubernetes.default.svc'
    namespace: production

  # 1. 동기화 정책 설정 🔄
  syncPolicy:
    automated:
      prune: true      # 삭제 자동 반영
      selfHeal: true   # 수동 수정 복구
    
    # 2. 세부 동기화 옵션 리스트 ⚙️
    syncOptions:
      - ApplyOutOfSyncOnly=true        # 변경된 리소스만 골라서 업데이트
      - Replace=true                   # 수정 불가 리소스 재생성
      - PrunePropagationPolicy=foreground # 자식 리소스부터 순차 삭제
      - CreateNamespace=true           # 네임스페이스 자동 생성
      - ServerSideApply=true           # 대규모 매니페스트 처리 최적화
      - FailOnSharedResource=true      # 리소스 중복 관리 방지 🚫

    # 3. 실패 시 재시도 전략 🔁
    retry:
      limit: 5
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m

---
# 4. 개별 리소스(예: ConfigMap)에서 Sync Wave 사용 예시
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
  annotations:
    # 가장 먼저 배포되도록 설정 (낮은 숫자일수록 빠름) 🌊
    argocd.argoproj.io/sync-wave: "-10"
data:
  config: "setting"

---

5. 💡 추가로 알아두면 좋은 syncOptions

• Validate=false: kubectl apply --validate=false와 동일하게 리소스 스키마 검증을 건너뜁니다.
• SkipDryRunOnMissingResource=true: CRD가 아직 설치되지 않은 상태에서 해당 커스텀 리소스를 배포할 때 발생하는 Dry-run 에러를 방지합니다.
• RespectIgnoreDifferences=true: spec.ignoreDifferences 설정을 동기화 판단 기준에 엄격히 적용합니다.

---

📝 요약 테이블

속성 / 옵션	주요 역할	비유
prune	Git 삭제 시 클러스터 삭제	미니멀리즘 (안 쓰는 물건 정리)
selfHeal	수동 수정 자동 복구	항상성 유지 (원래대로 되돌리기)
ApplyOutOfSyncOnly	변경분만 업데이트	필요한 부분만 수리하기
Replace	리소스 재생성	고칠 수 없으면 새로 사기
Sync Waves	리소스 배포 순서 제어	도미노처럼 순서대로 세우기

---

💡 마치며

Argo CD의 syncPolicy는 단순히 '자동화'를 넘어 '어떻게 하면 더 안전하고 빠르게 배포할 것인가'에 대한 답을 제공합니다. 특히 대규모 환경일수록 ApplyOutOfSyncOnly나 Sync Waves 같은 옵션들은 선택이 아닌 필수입니다. 🎯

오늘 가이드가 여러분의 안정적인 인프라 운영에 큰 도움이 되기를 바랍니다!

---