Sync Options — 싱크 동작을 세밀하게 조정하는 옵션들

기본 싱크가 모든 상황에 딱 맞는 건 아니에요. 특정 리소스를 프루닝에서 빼야 한다거나, kubectl apply 대신 다른 방식으로 적용해야 하는 경우가 생깁니다. 이 글은 Argo CD가 싱크할 때의 동작을 바꾸는 **싱크 옵션(Sync Options)**을 정리해요.

출처: Argo CD 공식 문서 — Sync Options

본문

싱크 옵션은 두 곳에 설정할 수 있어요. Application 리소스의 spec.syncPolicy.syncOptions 배열에 넣으면 애플리케이션 전체에 적용되고, 개별 리소스의 argocd.argoproj.io/sync-options 애노테이션에 넣으면 그 리소스에만 적용됩니다. 애노테이션에 여러 옵션을 넣을 때는 콤마(,)로 이어 붙이고, 공백은 자동으로 제거돼요.

대표적인 옵션을 하나씩 볼게요.

프루닝을 막고 싶을 때 — `Prune=false`

삭제되면 안 되는 리소스가 프루닝되지 않도록 막아요. 리소스에 붙이면:

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

애플리케이션 레벨 기본값으로도 설정할 수 있어요.

apiVersion: argoproj.io/v1alpha1
kind: Application
spec:
  syncPolicy:
    syncOptions:
      - Prune=false

리소스에 붙인 Prune 옵션은 Application에 정의된 prune 정책보다 항상 우선해요. 대신 Argo CD가 프루닝을 기대하는 리소스라면 앱이 아웃오브싱크로 남을 수 있으니, Compare Options와 함께 쓰는 걸 검토해 보세요.

프루닝 전에 확인을 받고 싶을 때 — `Prune=confirm`

Namespace처럼 중요한 리소스는 확인 없이 지우면 위험해요. Prune=confirm을 붙이면 수동 확인이 있을 때까지 프루닝을 대기시킵니다.

metadata:
  annotations:
    argocd.argoproj.io/sync-options: Prune=confirm

확인은 Argo CD UI의 "Confirm Pruning" 버튼이나 CLI로 할 수 있고, 애플리케이션에 argocd.argoproj.io/deletion-approved: <ISO 타임스탬프> 애노테이션을 직접 붙여도 돼요. 확인 전까지 싱크 연산은 계속 Syncing 상태로 남습니다.

kubectl 검증을 끄고 싶을 때 — `Validate=false`

RawExtension을 쓰는 쿠버네티스 타입(예: ServiceCatalog)은 kubectl apply --validate=false로 적용해야 할 때가 있어요.

metadata:
  annotations:
    argocd.argoproj.io/sync-options: Validate=false

특정 리소스 종류 전체에 걸러내고 싶다면 시스템 레벨 구성의 resource.customizations를 보는 게 낫습니다.

아직 없는 CRD의 dry-run을 건너뛰기 — `SkipDryRunOnMissingResource=true`

클러스터가 아직 모르는 커스텀 리소스를 싱크할 때, CRD 매니페스트가 같은 싱크에 없다면 "the server could not find the requested resource" 오류로 실패해요. 이때 dry-run을 건너뛰도록 하면 됩니다.

metadata:
  annotations:
    argocd.argoproj.io/sync-options: SkipDryRunOnMissingResource=true

CRD가 이미 클러스터에 있으면 dry-run은 계속 실행돼요.

앱 삭제 때 리소스를 남기고 싶을 때 — `Delete=false`

PVC처럼 앱이 삭제된 뒤에도 남겨야 하는 리소스에 붙여요.

metadata:
  annotations:
    argocd.argoproj.io/sync-options: Delete=false

Delete=confirm은 파괴적인 삭제 전에 프루닝과 마찬가지로 수동 확인을 요구합니다.

아웃오브싱크 리소스만 적용 — `ApplyOutOfSyncOnly=true`

객체가 수천 개인 큰 애플리케이션은 싱크마다 전부를 apply 하면 쿠버네티스 API 서버에 부담이 커져요. 이 옵션을 켜면 아웃오브싱크 리소스만 싱크합니다. Selective Sync와 달리 싱크 훅은 여전히 실행되고 히스토리에도 기록돼요.

apiVersion: argoproj.io/v1alpha1
kind: Application
spec:
  syncPolicy:
    syncOptions:
      - ApplyOutOfSyncOnly=true

프루닝 삭제 전파 정책 — `PrunePropagationPolicy`

기본은 foreground 삭제 정책이고, background, foreground, orphan 중에 고를 수 있어요.

spec:
  syncPolicy:
    syncOptions:
      - PrunePropagationPolicy=foreground

프루닝을 마지막 웨이브로 — `PruneLast=true`

다른 리소스가 배포·헬시가 된 뒤, 싱크의 마지막 단계에서 프루닝이 되도록 해요.

spec:
  syncPolicy:
    syncOptions:
      - PruneLast=true

apply 대신 replace/create — `Replace=true`

리소스 스펙이 너무 커서 last-applied-configuration 애노테이션에 못 들어가면 kubectl apply가 어울리지 않아요. 이 옵션을 켜면 kubectl replace 또는 kubectl create를 씁니다. 리소스가 재생성될 수 있어 아웃티지 위험이 있으니 주의해야 해요.

spec:
  syncPolicy:
    syncOptions:
      - Replace=true

삭제 후 재생성 — `Force=true`

잡처럼 싱크마다 새로 실행돼야 하는 리소스는 삭제 후 재생성하도록 Force=true를 써요. 이것도 파괴적이라 주의가 필요합니다.

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

서버 사이드 apply — `ServerSideApply=true`

기본은 클라이언트 사이드 kubectl apply예요. 리소스가 262144바이트 애노테이션 한도를 넘거나, Argo CD가 완전히 관리하지 않는 리소스를 패치해야 하거나, 선언적 필드 관리를 쓰고 싶다면 서버 사이드 apply가 유용해요. 켜면 kubectl apply --server-side --force-conflicts로 적용합니다.

spec:
  syncPolicy:
    syncOptions:
      - ServerSideApply=true

애플리케이션 레벨에서 켰더라도 특정 리소스만 끄고 싶으면 그 리소스에 ServerSideApply=false 애노테이션을 붙이면 돼요.

네임스페이스 자동 생성과 메타데이터 — `CreateNamespace=true`

대상 네임스페이스가 없으면 싱크 시 자동으로 만들게 하려면 CreateNamespace=true를 켜요. 만들 네임스페이스는 반드시 spec.destination.namespace에 명시해야 해요. 거기에 라벨·애노테이션까지 입히고 싶다면 managedNamespaceMetadata로 지정합니다.

Sync Options — 싱크 동작을 세밀하게 조정하는 옵션들