Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 37 ยท Sync and Health

Argo CD Sync Options, Phases and Waves: Control the Order

Control how and in what order Argo CD applies resources: sync options like CreateNamespace, ServerSideApply and Replace, sync phases, sync-wave annotations and the default ordering of resource kinds.

Applying a pile of YAML in the wrong order fails in familiar ways: a Deployment needs a Namespace that is not there yet, a custom resource needs its CRD, an application needs its database migration first. Argo CD gives you two tools for this. Sync options change how resources are applied. Phases and waves decide when. This lesson covers both.

The YAML and annotations are real. The runnable code is a stand-in that sorts resources the way the rules below describe; it is a model for learning, not the real engine.

Sync options

Sync options appear on the Application (spec.syncPolicy.syncOptions) or, for some, on a single resource via the annotation argocd.argoproj.io/sync-options.

YAML
spec:
  syncPolicy:
    syncOptions:
      - CreateNamespace=true
      - ServerSideApply=true
      - PruneLast=true
      - ApplyOutOfSyncOnly=true
Option Meaning
CreateNamespace=true Create the destination namespace if it does not exist.
ServerSideApply=true Use server-side apply instead of client-side; handles very large objects and CRDs, and shared field ownership.
Validate=false Skip kubectl validation (for example, resources whose CRD arrives in the same sync).
PruneLast=true Prune only after all other resources are synced and healthy.
PrunePropagationPolicy=foreground How deletes cascade: foreground, background (default) or orphan.
Replace=true Use kubectl replace (or create) instead of apply, for objects that cannot be patched. Destructive.
ApplyOutOfSyncOnly=true Apply only resources that differ, rather than everything; useful for apps with thousands of resources.
RespectIgnoreDifferences=true Do not let a sync overwrite fields listed in ignoreDifferences.
FailOnSharedResource=true Fail if a resource is already managed by another Application.

Per resource:

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

Prune=false keeps the resource when it is removed from Git; Delete=false keeps it even when the Application is deleted. Both protect stateful objects.

Phases

A sync runs through phases: PreSync, then Sync, then PostSync (and SyncFail if it breaks). Ordinary manifests belong to the Sync phase. Hooks (the next-but-one lesson, Hooks and Rollbacks) attach Jobs to the other phases.

Sync waves

Inside a phase, resources are grouped into waves by the annotation argocd.argoproj.io/sync-wave. The value is an integer (default 0, negative values allowed). Argo CD applies wave by wave, lowest first, and waits for each wave's resources to become healthy before it starts the next.

YAML
# wave -1: namespace and config first
apiVersion: v1
kind: Namespace
metadata:
  name: shop
  annotations:
    argocd.argoproj.io/sync-wave: "-1"
---
# wave 0 (default): the database
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: db
---
# wave 1: the application, after the database is healthy
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  annotations:
    argocd.argoproj.io/sync-wave: "1"

There is a short pause between waves (about two seconds by default) to let the controller observe results.

Ordering inside a wave

Within one phase and wave, Argo CD sorts by kind, so common dependencies work without annotations: Namespaces first, then things like ResourceQuota, ServiceAccounts, Secrets and ConfigMaps, then PersistentVolumeClaims, Roles and RoleBindings, Services, workloads (Deployments, StatefulSets, DaemonSets, Jobs) and finally Ingresses and other kinds. Custom resources are applied after built-in kinds, which is why a CRD and its instances in one sync can still be a problem: the CRD must be established before its instances, so give the CRD a lower wave.

flowchart LR
  PreSync["PreSync hooks"] --> W1["Sync wave -1"] --> W0["Sync wave 0"] --> W2["Sync wave 1"] --> Post["PostSync hooks"]

Each arrow waits for health before continuing.

Stand-in: compute the apply order

This model orders resources by phase, wave and kind priority, then name. Add your own resources to test an order before you commit annotations.

JS Stand-in: apply order

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Stand-in: waves wait for health

The second model shows why a failing wave blocks the later ones: wave 1 never starts while the database is unhealthy.

JS Stand-in: waves wait for health

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Practical advice

  • Use CreateNamespace=true instead of a Namespace manifest in simple cases; use a Namespace manifest (wave -1) when you need labels or quotas.
  • Install CRDs in an earlier wave, or in a separate Application, than the resources that use them.
  • Prefer ServerSideApply=true for big CRDs and when multiple controllers share an object.
  • Do not use waves for everything: a Deployment that retries until its dependency is ready is more robust than a perfect order. Use waves for true prerequisites.
  • Avoid Replace=true unless you know why; it can delete and recreate objects.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the default sync wave of a resource without the annotation?

    Resources without the annotation are in wave 0; lower waves go first.
  2. 2. What must happen before Argo CD starts the next wave?

    Argo CD waits for each wave to be healthy before moving on.
  3. 3. Which sync option makes Argo CD prune only after everything else is synced and healthy?

    PruneLast delays deletions until the rest of the sync has succeeded.
  4. 4. Why might you give a CRD a lower wave than its custom resources?

    Applying a custom resource before its CRD is registered fails.

Summary

  • Sync options change how apply works (CreateNamespace, ServerSideApply, PruneLast, Replace and more).
  • Phases are PreSync, Sync and PostSync; waves order resources within a phase.
  • The argocd.argoproj.io/sync-wave annotation takes an integer; the default is 0.
  • Within a wave, built-in kinds are sorted so Namespaces and config come before workloads.
  • Use waves for real prerequisites such as CRDs, namespaces and databases.

Next: Health Checks and Diffing