Argo CD Sync Waves: Order Your GitOps Deployments Without Chaos

Problem: The Race Condition in GitOps Deployments

When Argo CD pushes an application to a cluster, it applies all resources in parallel by default. If a Deployment references a ConfigMap or a Custom Resource that hasn’t been created yet, the pod starts with a missing configuration, leading to restarts, spikes in error logs, or even a failed rollout. In complex applications that span multiple namespaces or rely on CRDs, these race conditions become hard to diagnose and can break automated CI/CD pipelines.

Thesis: Use Sync Waves to Enforce Declarative Ordering

Argo CD’s Sync Waves feature lets you group resources into numbered stages. Resources with a lower wave number are applied before those with a higher number, guaranteeing that dependencies are satisfied before their dependents are created. This keeps your GitOps workflow fully declarative while eliminating manual ordering hacks.

1. What Are Sync Waves?

• Introduced in Argo CD 1.8 and available in all newer releases.
• Implemented via the app.kubernetes.io/sync-wave annotation on any Kubernetes manifest that supports annotations.
• Argo CD respects the wave numbers during both automatic syncs and manual argocd app sync commands.
• Waves are orthogonal to health checks, hooks, and progressive delivery; you can combine them for granular control.

2. How to Configure Sync Waves

There are two common ways to set the wave number:

1. Annotation on the manifest

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: my-config
     annotations:
       app.kubernetes.io/sync-wave: "1"
   data:
     key: value
   

2. Helm values integration

   If you’re deploying with Helm, add the following to values.yaml and reference it in your templates:

   syncWave: 2
   

   Then in your template:

   metadata:
     annotations:
       app.kubernetes.io/sync-wave: "{{ .Values.syncWave }}"
   

Remember that the annotation value must be a string; Argo CD parses it as an integer. Wave numbers can be negative, zero, or positive; lower numbers run first.

3. Concrete Example: ConfigMap → Deployment

Let’s walk through a minimal Argo CD application that creates a ConfigMap followed by a Deployment that mounts it. We’ll see that the ConfigMap is applied first, preventing the Deployment from starting without its data.

Repository Layout

/app
 ├─ configmap.yaml
 └─ deployment.yaml

Contents of configmap.yaml:

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-app-config
  annotations:
    app.kubernetes.io/sync-wave: "1"
data:
  LOG_LEVEL: info

Contents of deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  annotations:
    app.kubernetes.io/sync-wave: "2"
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: app
          image: myrepo/myapp:latest
          envFrom:
            - configMapRef:
                name: my-app-config

Deploying with Argo CD

1. Create the application:

   argocd app create my-app \
     --repo https://github.com/example/repo.git \
     --path app \
     --dest-namespace default \
     --dest-server https://kubernetes.default.svc
   

2. Synchronize:

   argocd app sync my-app
   

3. Check the sync history to confirm wave order:

   argocd app history my-app
   

4. Verify resource state:

   kubectl get configmap my-app-config -o yaml
   kubectl get deployment my-app -o yaml
   

In the Argo CD UI, the ConfigMap will appear as the first resource in the sync tree, followed by the Deployment. The CLI logs will also show the ConfigMap being applied before the Deployment.

4. Trade‑Offs & Limitations

• Unsupported resource types: Some CRDs or built‑in resources may ignore annotations. For those, you’ll need Helm hooks or custom ordering logic.
• Complex dependencies: If a resource in wave 2 inadvertently references another resource in wave 2 that hasn’t been created yet, the order still won’t help. Design wave boundaries carefully.
• Maintainability: Over‑splitting into many waves can clutter the manifest and make the deployment pipeline harder to read. Aim for logical stages (e.g., CRDs, namespace objects, then workloads).
• Negative wave numbers: While allowed, they can be confusing if mixed with positive numbers. Stick to positive integers for clarity.

Conclusion: Add Sync Waves to Your GitOps Playbook

Sync Waves give you a declarative, version‑controlled way to enforce deployment order without resorting to side‑car scripts or manual interventions. They integrate seamlessly with Helm, Kustomize, and the Argo CD UI, making debugging straightforward. To get started:

1. Audit your application for ordering dependencies.
2. Annotate each resource with an appropriate app.kubernetes.io/sync-wave value.
3. Deploy and verify the order using argocd app history and kubectl get.
4. Iterate—add or merge waves only when a new dependency surface appears.

By treating sync waves as a first‑class citizen in your GitOps workflow, you’ll reduce runtime errors, speed up rollouts, and keep your Kubernetes manifests clean and maintainable.