Split View: ArgoCD Sync 엔진 분석: 동기화 메커니즘의 모든 것

Pending --> Running --> Succeeded
                |
                +--> Failed --> (Retry or Manual)

PreSync --> Sync --> PostSync
              |
              +--> SyncFail (Sync 실패 시에만)

apiVersion: batch/v1
kind: Job
metadata:
  name: db-migration
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
  template:
    spec:
      containers:
        - name: migrate
          image: myapp/migration:latest
          command: ['./migrate', 'up']
      restartPolicy: Never

1. 모든 Sync Phase 리소스를 Wave 순서로 정렬
2. 각 Wave 그룹별로:
   a. 리소스 타입 순서에 따라 적용
   b. 각 리소스에 대해 kubectl apply 동등 작업 수행
   c. 해당 Wave의 모든 리소스가 Healthy가 될 때까지 대기
3. 다음 Wave로 진행

apiVersion: batch/v1
kind: Job
metadata:
  name: notification
  annotations:
    argocd.argoproj.io/hook: PostSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
  template:
    spec:
      containers:
        - name: notify
          image: curlimages/curl:latest
          command:
            - curl
            - -X
            - POST
            - https://hooks.slack.com/services/XXX
            - -d
            - '{"text":"Deployment successful"}'
      restartPolicy: Never

apiVersion: batch/v1
kind: Job
metadata:
  name: failure-notification
  annotations:
    argocd.argoproj.io/hook: SyncFail
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
  template:
    spec:
      containers:
        - name: notify-failure
          image: curlimages/curl:latest
          command:
            - curl
            - -X
            - POST
            - https://hooks.slack.com/services/XXX
            - -d
            - '{"text":"Deployment FAILED"}'
      restartPolicy: Never

metadata:
  annotations:
    # Hook 유형 지정
    argocd.argoproj.io/hook: PreSync|Sync|PostSync|SyncFail|Skip
    # Hook 리소스 삭제 정책
    argocd.argoproj.io/hook-delete-policy: HookSucceeded|HookFailed|BeforeHookCreation

1. Application Controller가 Sync 시작
2. 현재 Phase에 해당하는 Hook 리소스 식별
3. Hook 리소스를 Wave 순서로 정렬
4. 각 Hook 리소스를 클러스터에 적용 (Job, Pod 등)
5. Hook이 완료(성공/실패)될 때까지 대기
6. 성공 시 다음 단계 진행, 실패 시 Sync 중단 또는 SyncFail Phase로 전환
7. Delete Policy에 따라 Hook 리소스 정리

# Wave -1: 인프라 리소스 (먼저 생성)
apiVersion: v1
kind: Namespace
metadata:
  name: my-app
  annotations:
    argocd.argoproj.io/sync-wave: '-1'

---
# Wave 0: 설정 리소스 (기본값)
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
  annotations:
    argocd.argoproj.io/sync-wave: '0'

---
# Wave 1: 애플리케이션 리소스
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  annotations:
    argocd.argoproj.io/sync-wave: '1'

---
# Wave 2: 외부 접근 리소스
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-app-ingress
  annotations:
    argocd.argoproj.io/sync-wave: '2'

1. 모든 리소스를 Wave 번호로 그룹화
2. 가장 낮은 Wave부터 순서대로 실행
3. 각 Wave 내에서는 리소스 타입 기본 순서 적용
4. 현재 Wave의 모든 리소스가 Healthy가 될 때까지 대기
5. 다음 Wave로 진행
6. 어느 Wave에서든 실패 시 전체 Sync 중단

Phase 1: 네임스페이스와 기본 설정
  1. Namespace
  2. NetworkPolicy
  3. ResourceQuota
  4. LimitRange
  5. PodSecurityPolicy
  6. ServiceAccount
  7. Secret
  8. SecretList
  9. ConfigMap

Phase 2: RBAC
  10. ClusterRole
  11. ClusterRoleBinding
  12. Role
  13. RoleBinding

Phase 3: CRD
  14. CustomResourceDefinition

Phase 4: 스토리지와 볼륨
  15. PersistentVolume
  16. PersistentVolumeClaim
  17. StorageClass

Phase 5: 서비스
  18. Service
  19. Endpoints

Phase 6: 워크로드
  20. DaemonSet
  21. Deployment
  22. ReplicaSet
  23. StatefulSet
  24. Job
  25. CronJob

Phase 7: 라우팅
  26. Ingress
  27. IngressClass
  28. APIService

metadata:
  annotations:
    argocd.argoproj.io/tracking-id: 'my-app:apps/Deployment:default/nginx'

metadata:
  labels:
    app.kubernetes.io/instance: my-app

APP_NAME:GROUP/KIND:NAMESPACE/NAME

예시:
  my-app:apps/Deployment:default/nginx
  my-app:/Service:default/nginx-svc
  my-app:networking.k8s.io/Ingress:default/nginx-ingress

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  application.resourceTrackingMethod: annotation # annotation | label | annotation+label

1. Desired State: Git에서 생성된 매니페스트 (목표 상태)
2. Live State: 클러스터에서 실행 중인 실제 상태
3. Last Applied: 마지막으로 적용된 설정 (annotation에 기록)

// Diff 수행 로직 (간소화)
func diff(desired, live *unstructured.Unstructured) (*DiffResult, error) {
    // 1. 정규화
    normalizedDesired := normalize(desired)
    normalizedLive := normalize(live)

    // 2. 무시 필드 제거
    removeIgnoredFields(normalizedDesired)
    removeIgnoredFields(normalizedLive)

    // 3. 구조적 비교
    result := structuredMergeDiff(normalizedDesired, normalizedLive)

    return result, nil
}

# Application 리소스에서 설정
spec:
  ignoreDifferences:
    - group: apps
      kind: Deployment
      jsonPointers:
        - /spec/replicas # HPA가 관리하는 replica 수 무시
    - group: ''
      kind: ConfigMap
      jqPathExpressions:
        - .data.generated-field # 자동 생성 필드 무시

data:
  resource.customizations.ignoreDifferences.all: |
    managedFieldsManagers:
      - kube-controller-manager
      - kube-scheduler

Healthy: 모든 replica가 Ready이고 업데이트 완료
Progressing: 롤아웃이 진행 중 (새 ReplicaSet 생성 중)
Degraded: replica가 Ready 상태에 도달하지 못함

Healthy: 모든 replica가 Ready이고 currentRevision == updateRevision
Progressing: 업데이트가 진행 중
Degraded: replica가 Ready가 아님

Healthy: Running 상태이고 모든 컨테이너가 Ready
Progressing: Pending 또는 ContainerCreating 상태
Degraded: CrashLoopBackOff, ImagePullBackOff 등

Healthy: Endpoints가 존재하고 하나 이상의 Ready 주소가 있음
Progressing: LoadBalancer 타입에서 외부 IP 할당 대기 중

Healthy: LoadBalancer 주소가 할당됨
Progressing: 주소 할당 대기 중

Healthy: 성공적으로 완료됨 (Completed)
Progressing: 실행 중 (Active)
Degraded: 실패 (Failed)

# argocd-cm ConfigMap
data:
  resource.customizations.health.cert-manager.io_Certificate: |
    hs = {}
    if obj.status ~= nil then
      if obj.status.conditions ~= nil then
        for _, condition in ipairs(obj.status.conditions) do
          if condition.type == "Ready" then
            if condition.status == "True" then
              hs.status = "Healthy"
              hs.message = "Certificate is ready"
            else
              hs.status = "Degraded"
              hs.message = condition.message
            end
            return hs
          end
        end
      end
    end
    hs.status = "Progressing"
    hs.message = "Waiting for certificate"
    return hs

1. Git 매니페스트에서 모든 리소스 목록 생성
2. 클러스터에서 ArgoCD가 관리하는 리소스 조회 (tracking label/annotation)
3. 클러스터에 존재하지만 Git에 없는 리소스 식별 (= Prune 대상)
4. 삭제 정책에 따라 리소스 삭제

- 소유 리소스를 재귀적으로 삭제
- Deployment를 삭제하면 ReplicaSet과 Pod도 함께 삭제
- Kubernetes의 garbage collection 메커니즘 사용

- 소유 리소스가 먼저 삭제된 후 부모 리소스 삭제
- 순서가 보장되어야 하는 경우 사용
- finalizer를 통한 순서 제어

# 리소스에 Prune 방지 어노테이션 추가
metadata:
  annotations:
    argocd.argoproj.io/sync-options: Prune=false

# Application 수준에서 Prune 비활성화
spec:
  syncPolicy:
    automated:
      prune: false # 자동 Prune 비활성화

# AppProject에서 Orphan 리소스 모니터링 활성화
spec:
  orphanedResources:
    warn: true # 경고만 표시
    # ignore:   # 무시할 리소스 패턴
    #   - group: ""
    #     kind: ConfigMap
    #     name: "auto-*"

spec:
  syncPolicy:
    automated:
      selfHeal: true
    retry:
      limit: 5 # 최대 재시도 횟수
      backoff:
        duration: 5s # 초기 대기 시간
        factor: 2 # 대기 시간 증가 배수
        maxDuration: 3m # 최대 대기 시간

재시도 1: 5초 후
재시도 2: 10초 후 (5s * 2)
재시도 3: 20초 후 (10s * 2)
재시도 4: 40초 후 (20s * 2)
재시도 5: 80초 후 (40s * 2) -> 최대 3분으로 제한

spec:
  syncPolicy:
    automated:
      prune: true # Git에서 삭제된 리소스 자동 정리
      selfHeal: true # 수동 변경 자동 교정
      allowEmpty: false # 빈 매니페스트 허용 여부
    syncOptions:
      - CreateNamespace=true # 네임스페이스 자동 생성
      - PrunePropagationPolicy=foreground # 삭제 전파 정책
      - PruneLast=true # 다른 리소스 동기화 후 Prune
      - Replace=false # apply 대신 replace 사용 여부
      - ServerSideApply=true # Server-Side Apply 사용
      - ApplyOutOfSyncOnly=true # OutOfSync 리소스만 적용
      - Validate=true # 매니페스트 유효성 검사
      - RespectIgnoreDifferences=true # ignoreDifferences 설정 존중

metadata:
  annotations:
    argocd.argoproj.io/sync-options: Prune=false,Replace=true

장점:
  - 필드 소유권(Field Ownership) 추적
  - 여러 컨트롤러 간 충돌 방지
  - 더 정확한 3-way merge
  - 대규모 리소스에서 성능 향상

설정:
  syncOptions:
    - ServerSideApply=true

spec:
  syncWindows:
    # 평일 업무시간에만 Sync 허용
    - kind: allow
      schedule: '0 9 * * 1-5' # 월-금 09:00
      duration: 9h # 9시간 동안
      applications:
        - '*'
      namespaces:
        - 'production'
    # 주말에는 Sync 금지
    - kind: deny
      schedule: '0 0 * * 0,6' # 토,일 00:00
      duration: 24h
      applications:
        - '*'
    # 수동 Sync만 허용하는 시간대
    - kind: allow
      schedule: '0 18 * * 1-5' # 월-금 18:00
      duration: 15h
      manualSync: true
      applications:
        - 'critical-*'

1. deny가 allow보다 우선
2. 동일 우선순위면 더 구체적인 규칙이 우선
3. manualSync=true면 수동 Sync만 허용

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: production-app
spec:
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      - PruneLast=true
      - ServerSideApply=true
      - ApplyOutOfSyncOnly=true
    retry:
      limit: 3
      backoff:
        duration: 10s
        factor: 2
        maxDuration: 5m
  ignoreDifferences:
    - group: apps
      kind: Deployment
      jsonPointers:
        - /spec/replicas # HPA 관리
    - group: autoscaling
      kind: HorizontalPodAutoscaler
      jqPathExpressions:
        - .status

# Wave -2: PreSync - DB 백업
apiVersion: batch/v1
kind: Job
metadata:
  name: db-backup
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: BeforeHookCreation
    argocd.argoproj.io/sync-wave: '-2'
spec:
  template:
    spec:
      containers:
        - name: backup
          image: backup-tool:latest
          command: ['./backup.sh']
      restartPolicy: Never

---
# Wave -1: PreSync - DB 마이그레이션
apiVersion: batch/v1
kind: Job
metadata:
  name: db-migrate
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: BeforeHookCreation
    argocd.argoproj.io/sync-wave: '-1'
spec:
  template:
    spec:
      containers:
        - name: migrate
          image: myapp/migration:v2
          command: ['./migrate', 'up']
      restartPolicy: Never

---
# Wave 0: Sync - 메인 애플리케이션
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
  annotations:
    argocd.argoproj.io/sync-wave: '0'
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
        - name: app
          image: myapp:v2

---
# Wave 1: PostSync - 스모크 테스트
apiVersion: batch/v1
kind: Job
metadata:
  name: smoke-test
  annotations:
    argocd.argoproj.io/hook: PostSync
    argocd.argoproj.io/hook-delete-policy: BeforeHookCreation
    argocd.argoproj.io/sync-wave: '1'
spec:
  template:
    spec:
      containers:
        - name: test
          image: curlimages/curl:latest
          command: ['curl', '-f', 'http://myapp:8080/health']
      restartPolicy: Never