Controlling Deployment Order: Sync Waves

The Order Problem

Sometimes, you cannot apply all your Kubernetes manifests simultaneously. Consider these real scenarios:

• A database schema migration Job must complete before the new version of the backend API starts, or the API will crash on startup with a schema mismatch.
• A Namespace must exist before you can deploy resources into it.
• A CustomResourceDefinition (CRD) must be registered before you can create instances of that custom resource.

If you run kubectl apply -f ., Kubernetes applies resources in alphabetical order by filename — which is rarely the order you need.

Sync Waves

GitOps tools solve this with Sync Waves. You add a single annotation — argocd.argoproj.io/sync-wave, set to a number — to each Kubernetes manifest to assign it to a numbered wave. The operator processes waves in ascending order, waiting for all resources in a wave to reach a healthy state before starting the next wave: a migration Job at wave -1, the application Deployment at wave 0 (the default when no annotation is present), and a post-deploy smoke-test Job at wave 1.

The operator processes wave -1 first. It waits for the migration Job to complete (status: Succeeded) before moving to wave 0. It waits for the Deployment to become fully available before moving to wave 1. If any wave fails, the sync stops — preventing a broken deployment from progressing further.

Flux equivalent: Flux achieves ordering through dependencies between Kustomization resources using the dependsOn field, rather than per-resource annotations. The concept is the same; the implementation differs.