Using Argo CD Sync Waves to Order ConfigMap Before Deployment

Desired outcome

Ensure that a ConfigMap (or Secret) is fully applied to the cluster before any Pod that depends on it starts, preventing race conditions during application rollout.

Prerequisites

• Argo CD v2.0 or later installed and accessible via argocd CLI or UI.
• kubectl configured to target the same cluster.
• Permission to create or update an Argo CD Application and to apply Kubernetes manifests in the target namespace.
• A Git repository (or local directory) containing the manifests you want to manage.

Procedure

1. Prepare the manifests

   Add the argocd.argoproj.io/sync-wave annotation to each resource. Lower numbers sync first.

   # configmap.yaml
   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: app-config
     annotations:
       argocd.argoproj.io/sync-wave: "-5"
   data:
     key: value
   ---
   # 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: myapp:latest
           envFrom:
           - configMapRef:
               name: app-config
   

2. Create or update the Argo CD Application

   If the Application does not exist, create it pointing to the directory containing the manifests.

   argocd app create ordering-demo \
     --repo https://github.com/example/repo.git \
     --path manifests \
     --dest-server https://kubernetes.default.svc \
     --dest-namespace default \
     --sync-policy automated
   

   To apply a global wave shift without editing manifests, edit the Application’s syncPolicy.syncOptions:

   argocd app patch ordering-demo --patch '{"spec":{"syncPolicy":{"syncOptions":["SyncWave=-10"]}}}' --type merge
   

   This subtracts 10 from every wave value, useful for testing.

3. Trigger a sync

   Run a manual sync or rely on the automated policy.

   argocd app sync ordering-demo
   

4. Verify the ordering
   • In the Argo CD UI, open the Application → Resources tab. Each resource shows its wave number; confirm the ConfigMap appears with a lower number than the Deployment.
   • Check the sync log for the sequence: argocd app get ordering-demo -o yaml under status.operationState.phase and history entries.
   • Observe the Pod logs: the container should start only after the ConfigMap is present. You can add a temporary sleep or echo command to the container to verify that it does not start until the ConfigMap is mounted.

Expected checks

• ConfigMap wave < Deployment wave (e.g., -5 vs 10).
• UI timeline shows ConfigMap synced before Deployment.
• Pod’s READY condition becomes true only after the ConfigMap is present.

Recovery options (if ordering causes disruption)

Because sync waves only influence Argo CD’s sequencing, you can revert changes without touching the cluster state:

1. Remove or adjust the sync-wave annotations in the manifests and re‑sync.
2. If you used a global syncPolicy.syncOptions shift, set it back to an empty list or remove the patch:

argocd app patch ordering-demo --patch '{"spec":{"syncPolicy":{"syncOptions":[]}}}' --type merge

3. If a sync has already applied resources in an undesired order, you can manually delete and recreate the offending resource (e.g., the Deployment) to force a re‑apply with the corrected order.

Limitations and cautions

• Missing sync-wave defaults to wave 0; mixing annotated and unannotated resources can produce unexpected ordering.
• Extremely large values (outside -100 … 100) may cause overflow in Argo CD versions < v2.0; stay within this range.
• Sync waves do not override Kubernetes native ordering such as ownerReferences or controller‑driven creation; they only affect Argo CD’s internal sequencing.
• Changing wave values after an application is already synced may cause Argo CD to attempt re‑ordering on the next sync, potentially leading to disruptive updates. Test changes in a staging environment first.
• The feature relies on the Argo CD controller correctly parsing annotations; a malfunctioning controller (e.g., due to a custom plugin bug) could ignore wave ordering.

Practical way to confirm the result

After a successful sync, run:

kubectl get configmap app-config -o yaml
kubectl get deployment app -o yaml
kubectl describe pod -l app=myapp

Verify that the ConfigMap’s data section is present and that the Pod’s containers have the environment variables sourced from it before they report Ready.