Argo CD Sync Phases and Waves: Ordering Your Deployments

WHY IT EXISTS: Kubernetes applies manifests declaratively, but it doesn't guarantee the order of creation between different resource types. A Deployment might try to start before its required ConfigMap exists, causing startup failures. Sync Phases and Waves solve this by imposing a specific execution order on your GitOps sync.

THE MENTAL MODEL: Think of deploying an application as a multi-stage recipe. Phases are the major steps: 'pre-sync' is for prepping ingredients (like running a database migration), 'sync' is the main cooking process (applying your core manifests), and 'post-sync' is for plating and cleanup (like running integration tests). Waves are the ordered instructions within the main 'sync' phase, ensuring you add the oil (CRDs, Namespaces) before the onions (Deployments, Services).

HOW IT WORKS: You control this behavior with annotations in your Kubernetes YAML files. Phases are controlled by resource hooks (argocd.argoproj.io/hook). You can designate a Job or ArgoWorkflow to run PreSync, Sync, or PostSync. These hooks must complete successfully for the sync to proceed. Waves are controlled by the argocd.argoproj.io/sync-wave annotation, which takes an integer. Argo CD groups resources by their wave number and applies them in ascending order. Resources in a wave are only applied after all resources in the previous wave become healthy. Resources without a wave annotation are in wave 0.

WHEN TO USE IT: Use phases and waves for complex applications with strict startup dependencies. For example: first, run a PreSync Job to migrate a database schema; second, apply CRDs in wave -10; third, apply ConfigMaps and Secrets in wave 0; fourth, apply Deployments in wave 5; and finally, run a PostSync hook to perform smoke tests.

WHEN NOT TO USE IT: Avoid this for simple, stateless applications. Kubernetes' own controllers are often smart enough to handle dependencies. Overusing waves can make deployments brittle and hard to debug, as a failure in an early wave stops everything that follows. Start without waves and add them only when you prove a dependency problem exists.

ONE CANONICAL EXAMPLE: To ensure a PostgreSQL database is ready before your application starts, you could place the StatefulSet for Postgres in wave 1 (argocd.argoproj.io/sync-wave: "1"). Then, place the Deployment for your application, which connects to the database, in wave 2 (argocd.argoproj.io/sync-wave: "2"). Argo CD will wait for the Postgres StatefulSet to report a healthy status before it attempts to apply the application Deployment manifest.