Using Argo CD Sync Waves to Control Kubernetes Resource Order

When you deploy a Kubernetes application with Argo CD, resources are created in the order they appear in the manifest files. This default behavior can cause race conditions—for example, a Deployment that references a ConfigMap may start before the ConfigMap exists, leading to crashes or stale configuration. Argo CD’s Sync Waves feature lets you declare the desired synchronization order directly on each resource, independent of file ordering.

Understanding Sync Waves

Sync Waves are implemented via the annotation argocd.argoproj.io/sync-wave. The annotation accepts an integer from -999 to 999. Resources with lower numbers are synced before those with higher numbers. If the annotation is omitted, Argo CD places the resource in wave 0, giving a predictable baseline. The feature works alongside health checks and hooks; it only influences when Argo CD sends the apply request to the API server, not how the API server orders the objects.

Worked Example: Sequencing a ConfigMap Before a Deployment

Suppose you have a simple application consisting of a ConfigMap that holds application configuration and a Deployment that consumes it. You want the ConfigMap to be created first.

# configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
  annotations:
    argocd.argoproj.io/sync-wave: "-10"
data:
  LOG_LEVEL: "info"

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: app
  annotations:
    argocd.argoproj.io/sync-wave: "10"
spec:
  replicas: 1
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
      - name: app
        image: myorg/myapp:latest
        envFrom:
        - configMapRef:
            name: app-config

Apply the manifests to the Git repository tracked by Argo CD, then trigger a sync:

# Ensure you have the Argo CD CLI installed and authenticated
argocd app get   # verify the app is healthy
argocd app sync   # start a sync operation

During the sync, Argo CD logs will show the wave numbers being processed. You can verify the order in several ways:

• CLI: Run argocd app get -o wide and look at the HEALTHY status of each resource; the ConfigMap (wave -10) should report Healthy before the Deployment (wave 10).
• UI: Open the Application Details page, select the Resource Tree view, and confirm that the wave numbers displayed next to each resource match the annotations and that the tree expands in ascending wave order.
• Server logs: Examine the Argo CD repo‑server pod logs (e.g., kubectl logs -n argocd deployment/argocd-repo-server) for lines containing "sync wave" – they list the wave numbers as resources are processed.

Trade‑offs and Limitations

Sync Waves are a convenient sequencing tool, but they do not replace native Kubernetes ordering mechanisms such as ownerReferences or podDisruptionBudgets. If you rely solely on wave numbers, the API server may still apply objects concurrently; Argo CD merely staggers the initiation of applies. Misconfiguring wave values (e.g., assigning the same wave to two resources that depend on each other) can create a logical deadlock, causing the sync to stall with a Progressing status. Always verify that the dependency graph is acyclic before assigning waves.

Additionally, the feature only affects the sync operation initiated by Argo CD. Manual kubectl apply or other CI pipelines will ignore the annotation, potentially diverging from the declared order.

Actionable Closing

To adopt Sync Waves in your workflow:

1. Identify resources that have strict ordering requirements (e.g., ConfigMaps/Secrets before workloads, databases before front‑ends).
2. Assign negative wave numbers to prerequisites and positive numbers to dependents, staying within the -999 to 999 range.
3. Commit the annotated manifests to your Git repo and let Argo CD perform a sync.
4. Verify the order using the CLI, UI, or server logs as described above.
5. If a sync appears stuck, inspect the Argo CD application status for wave‑related messages, adjust the annotations, and re‑sync.

By explicitly declaring sync order with Sync Waves, you reduce guesswork and avoid race conditions that can otherwise require custom scripts or complex Helm hooks. Use the feature as a complementary tool alongside native Kubernetes dependency mechanisms for reliable, predictable deployments.