ArgoCD
Topics in this category
App of Apps Applications GitOps Principles Multi-cluster RBAC Sync & Health Sync Waves & Hooks
ArgoCD

Sync & Health

29 question(s)

What is a sync in ArgoCD?

Beginner
A sync is the operation where ArgoCD applies the desired state from Git to the cluster so the live state matches. It computes the diff, orders resources (by waves/hooks), applies them, and reports success or failure. Syncs can be manual or automated, full or selective, and can run with options like prune and dry-run.
argocd app sync my-app
argocd app sync my-app --prune --dry-run
Real-world example Merging a change and clicking Sync applies the new manifests, moving the app from OutOfSync to Synced.

Common follow-ups: What triggers a sync? | What does a dry-run sync do?

Applications Sync Waves & Hooks Sync & Health

What are the possible sync statuses of an Application?

Beginner
Sync status reflects whether live matches Git: Synced (live equals desired), OutOfSync (differences exist), and Unknown (comparison couldn't be made, e.g., repo unreachable). It's separate from health status, which reflects whether resources are actually working.
Real-world example After editing a manifest in Git, the app shows OutOfSync until the next sync makes it Synced again.

Common follow-ups: How does sync status differ from health? | What causes Unknown status?

Applications GitOps Principles Sync & Health

What are the health statuses ArgoCD reports?

Beginner
Health statuses describe resource operational state: Healthy (working as intended), Progressing (still coming up), Degraded (failed, e.g., crash-looping pods), Suspended (paused, like a suspended CronJob), Missing (not present), and Unknown. ArgoCD aggregates per-resource health into an overall Application health.
Real-world example A Deployment with crash-looping pods shows Degraded, turning the whole Application health red until fixed.

Common follow-ups: How is app health aggregated? | What does Progressing mean?

Applications Sync Waves & Hooks Sync & Health

How does ArgoCD determine the health of a resource?

Intermediate
ArgoCD has built-in health assessments for standard resources (Deployments ready replicas, Services, Ingress with load balancer, PVCs bound, etc.). For custom resources, it uses configurable Lua health check scripts. Health reflects operational readiness, distinct from whether the resource matches Git (sync).
# argocd-cm custom health for a CRD (Lua)
resource.customizations.health.example.com_MyKind: |
  hs = {}
  if obj.status.phase == "Running" then hs.status = "Healthy" end
  return hs
Real-world example A custom operator CRD gets a Lua health script so ArgoCD can report it Healthy only when its status is Ready.

Common follow-ups: Why do CRDs need custom health checks? | What determines Deployment health?

Applications Sync Waves & Hooks Sync & Health

What is the difference between sync status and health status?

Intermediate
Sync status answers 'does the live cluster match Git?' (Synced/OutOfSync), while health status answers 'are the resources actually working?' (Healthy/Degraded/etc.). An app can be Synced but Degraded (matches Git but pods crash) or Healthy but OutOfSync (working but Git changed). Both are needed for a full picture.
Real-world example A newly merged bad image leaves the app Synced (matches Git) yet Degraded because the pods crash-loop.

Common follow-ups: Can an app be Synced and Degraded? | Which status triggers auto-sync?

Applications GitOps Principles Sync & Health

What are sync options and give common examples?

Intermediate
Sync options modify apply behavior, set via the Application or resource annotations. Common ones: Prune=false (don't delete), Validate=false (skip schema validation), CreateNamespace=true (auto-create target namespace), ApplyOutOfSyncOnly=true (only apply changed resources), ServerSideApply=true, and Replace=true (use replace instead of apply).
syncPolicy:
  syncOptions:
    - CreateNamespace=true
    - ApplyOutOfSyncOnly=true
    - ServerSideApply=true
Real-world example CreateNamespace=true lets an app provision its own namespace on first sync without a separate manifest.

Common follow-ups: What does ServerSideApply solve? | When use Replace=true?

Applications Sync Waves & Hooks Sync & Health

What is a selective sync and when is it useful?

Intermediate
A selective sync applies only specific resources within an Application rather than all of them. It's useful for large apps to push a single changed resource quickly, or to work around a problematic resource. In the UI or CLI you choose which resources to sync; note it can leave the app partially applied.
argocd app sync my-app --resource apps:Deployment:web
Real-world example During an incident, an engineer selectively syncs just the fixed Deployment instead of the whole large application.

Common follow-ups: What's the risk of selective sync? | How do you target one resource?

Applications Sync Waves & Hooks Sync & Health

How does ServerSideApply help with large or conflicting resources?

Advanced
Server-Side Apply (SSA) lets Kubernetes merge changes field-by-field with ownership tracking, avoiding the last-applied-configuration annotation size limits (e.g., large CRDs) and reducing conflicts when multiple controllers manage different fields. ArgoCD can use SSA per-sync or per-resource to apply big CRDs and coexist with other field managers.
metadata:
  annotations:
    argocd.argoproj.io/sync-options: ServerSideApply=true
Real-world example A very large CRD that failed client-side apply due to annotation size limits applies cleanly with ServerSideApply.

Common follow-ups: What limit does SSA avoid? | How does SSA handle field ownership?

Applications Sync Waves & Hooks Sync & Health

How do you configure automated sync with retry and backoff?

Intermediate
Under syncPolicy you can set retry with limit and backoff (duration, factor, maxDuration) so failed syncs retry with exponential backoff instead of immediately failing. This handles transient errors (e.g., a dependency not yet ready) gracefully during automated reconciliation.
syncPolicy:
  automated: { selfHeal: true }
  retry:
    limit: 5
    backoff:
      duration: 5s
      factor: 2
      maxDuration: 3m
Real-world example A sync that fails because a CRD isn't installed yet retries with backoff and succeeds once the CRD appears.

Common follow-ups: Why use backoff on retries? | What fields configure retry?

Applications Sync Waves & Hooks Sync & Health

How do you handle CRDs and their custom resources syncing in the right order?

Advanced
CRDs must exist before their custom resources apply. Use sync waves to install CRDs first (lower wave), or the SkipDryRunOnMissingResource sync option so ArgoCD doesn't fail validation when the CRD isn't yet present. For operators, install the operator/CRDs in an earlier wave or a separate app before workloads that use them.
metadata:
  annotations:
    argocd.argoproj.io/sync-options: SkipDryRunOnMissingResource=true
    argocd.argoproj.io/sync-wave: "-1"   # CRDs first
Real-world example CRDs are placed in wave -1 so custom resources in wave 0 don't fail with 'no matches for kind' during sync.

Common follow-ups: Why can a CR fail to apply before its CRD? | What does SkipDryRunOnMissingResource do?

Sync Waves & Hooks Applications Sync & Health