[k8s] ArgoCD sync 주요 옵션

Sync policy

• manual: 사용자가 Sync 눌러야 배포.

• automated: Git 변경 감지 시 자동 배포.

  • prune: Git에 없는 리소스 삭제
  • selfHeal: 드리프트 시 Git 상태로 복구
  • allowEmpty: 매니페스트 0개여도 성공 처리

spec:
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
      allowEmpty: false

Sync options

• CreateNamespace=true : 대상 ns 없으면 생성
• PrunePropagationPolicy=foreground|background|orphan : 삭제 전파 방식
• PruneLast=true : 항상 prune을 마지막에 수행
• ServerSideApply=true : 서버사이드 apply
  • kubectl apply의 서버사이드 apply(SSA) 로 동기화
• Replace=true : apply 대신 replace (강제 교체)
• ApplyOutOfSyncOnly=true : out-of-sync 리소스만 적용
• RespectIgnoreDifferences=true
  • spec.ignoreDifferences로 무시하겠다고 선언한 필드를 단순히 diff에서만 빼는 게 아니라, sync 시 패치에도 제외
• FailOnSharedResource=true : shared resource 공유 리소스 변화 시 실패 처리
  • true 설정시, 여러 Application이 같은 리소스를 관리하려 할 때 sync 를 fail 처리
  • (기본은 warning 만 출력하고 진행)
• Validate=true|false : 서버 검증 on/off

spec:
  syncPolicy:
    syncOptions:
    - CreateNamespace=true
    - PrunePropagationPolicy=background
    - PruneLast=true
    - ServerSideApply=true

배포 대상 cluster, namespace 지정

• 어느 cluster, namespace 에 배포할지 정의

spec:
  destination:
    server: https://kubernetes.default.svc   # 또는 특정 클러스터 API
    namespace: my-namespace

Retry, backoff

spec:
  syncPolicy:
    retry:
      limit: 5
      backoff:
        duration: 5s     # 최초 대기
        factor: 2        # 지수 증가
        maxDuration: 3m  # 최대 대기

Sync Windows (배포 허용/차단 시간대 지정)

• 운영시간 외 배포 차단(freeze)

apiVersion: argoproj.io/v1alpha1
kind: AppProject
spec:
  syncWindows:
  - kind: allow          # allow | deny
    schedule: "Mon-Fri 09:00-18:00"
    timeZone: "Asia/Seoul"
    applications: ["prod-*"]

Hook & Wave (순서/단계 제어)

• Hook 단계: PreSync → Sync → PostSync → SyncFail
• 삭제 정책: argocd.argoproj.io/hook-delete-policy: HookSucceeded|HookFailed|BeforeHookCreation
• Wave: argocd.argoproj.io/sync-wave: "-1|0|1|2..."
  • 낮은 wave 먼저

metadata:
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
    argocd.argoproj.io/sync-wave: "1"

ApplicationSet (대량/동적 배포)

• clusters, list, git, matrix, pullRequest 등 제너레이터로 여러 Application을 자동 생성/관리.

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
spec:
  generators:
  - clusters: {}
  template:
    metadata: { name: "myapp-{{name}}" }
    spec:
      destination: { server: "{{server}}", namespace: myapp }
      syncPolicy: { automated: { prune: true, selfHeal: true } }

Progressive Delivery (카나리/블루그린)

apiVersion: argoproj.io/v1alpha1
kind: Rollout
spec:
  strategy:
    canary:
      steps:
      - setWeight: 20
      - pause: {duration: 60}
      - setWeight: 50
      - pause: {}
      - setWeight: 100

프로젝트/보안 가드레일(AppProject)

• 허용 리포/경로, 대상 클러스터, 네임스페이스, 리소스 종류 제한
• 리소스 오버라이드(특정 GVK 허용/차단), 동기화 윈도우, 소스 화이트리스트 등

Notifications

• Sync 성공/실패, 드리프트, 헬스 변경을 Slack/Email/Webhook으로 알림
• 트리거/템플릿 커스터마이즈 가능

자주 쓰는 CLI

# 전체/부분 동기화
argocd app sync myapp
argocd app sync myapp --resource apps:Deployment:default/myapp

# 상태/대기
argocd app wait myapp --health --timeout 300

# 드리프트 확인/리프레시
argocd app diff myapp
argocd app refresh myapp

# 이력/롤백
argocd app history myapp
argocd app rollback myapp <REVISION>

• 라이브/캐시 새로고침 후 health check:

argocd app refresh myapp
argocd app wait myapp --health --sync --timeout 300

• rollback, history

argocd app history myapp
argocd app rollback myapp <REVISION>
argocd app sync myapp --revision <git-sha-or-tag>

• 부분/선별 배포(Selective Sync)
  • 특정 리소스만 동기화 가능.

argocd app sync myapp \
  --resource apps:Deployment:default/my-deploy
# or
argocd app sync myapp --prune --async

reference

• ArgoCD Docs - Sync Options