What are Argo CD sync waves and how do they order a sync?

Argo CD sync waves are an ordering mechanism within a single sync. Argo CD sorts every resource in an application by four keys, in this order: phase (PreSync, Sync, PostSync), then wave, then kind, then name. It applies the lowest wave, waits until every resource in that wave reports healthy, and only then moves to the next wave. That wait is the whole point. A Deployment in a later wave cannot start while the Job before it is still running or has failed.

You set a wave with the argocd.argoproj.io/sync-wave annotation. The value is a string containing an integer, such as "-1" or "5", because annotation values in Kubernetes are always strings. Resources without the annotation default to wave 0. Negative values are allowed, so prerequisites can sort ahead of the default without renumbering everything else. Inside a wave, the kind ordering still applies, which is why a Namespace is created before other objects in the same wave.

A typical layout:

Sync phase
  wave -2   Namespace, ServiceAccount
  wave -1   ConfigMaps, Secrets
  wave  0   db-migrate Job
  wave  1   Deployments
PostSync phase
  smoke-test Job

Waves only order resources within a phase. Every PreSync hook runs before the first Sync-phase wave. If you turned db-migrate into a PreSync hook, it would run before the wave -2 Namespace and Secrets exist. Section 3 shows how to handle that.

apiVersion: v1
kind: Namespace
metadata:
  name: shop
  annotations:
    argocd.argoproj.io/sync-wave: "-2"   # quoted: annotation values are strings
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: shop-config
  namespace: shop
  annotations:
    argocd.argoproj.io/sync-wave: "-1"
data:
  DB_HOST: postgres.shop.svc.cluster.local
---
apiVersion: batch/v1
kind: Job
metadata:
  name: db-migrate
  namespace: shop
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: shop-api
  namespace: shop
  annotations:
    argocd.argoproj.io/sync-wave: "1"

Sync-wave annotations that order a Namespace, a ConfigMap, a default-wave migration Job and a Deployment within a single Argo CD sync.

How do Argo CD hooks differ from sync waves?

A hook changes when a resource is applied. A wave only changes where it falls inside a phase. You set a hook with the argocd.argoproj.io/hook annotation:

  • PreSync runs before any Sync-phase resource is applied. This is the usual home for migrations.
  • Sync runs alongside the normal manifests, after PreSync finishes.
  • PostSync runs only after the sync succeeds and every resource reports healthy. It suits smoke tests and notifications.
  • SyncFail runs only when the sync fails, which makes it the place for cleanup or alerting.
  • Skip tells Argo CD not to apply the manifest at all.

Hooks also differ from regular resources in how often they run. A regular manifest is applied only when it drifts from Git. A hook is created again on every sync, even when nothing changed, so a migration hook must be safe to rerun. Argo CD waits for the hook to finish, for example for a Job to succeed, before it moves on. Hooks don't count toward the application's sync status. You control their cleanup with argocd.argoproj.io/hook-delete-policy, not with pruning.

The two annotations work together because waves apply inside each phase. You can give three PreSync Jobs waves 0, 1 and 2, for example a schema check, the migration, and a cache warm-up. Argo CD then runs them in that order, and each one must complete before the next starts.

Hook Sync wave
Purpose Choose the phase a resource runs in Order resources within a phase
Lifecycle Recreated on every sync Applied only when out of sync
Tracking Waits for completion; excluded from sync status Waits for health; counted in sync status
Deletion Set by hook-delete-policy Pruned when removed from Git, if pruning is enabled
apiVersion: batch/v1
kind: Job
metadata:
  name: db-migrate
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/sync-wave: "0"
    # Hooks are recreated on every sync; delete the old Job first
    argocd.argoproj.io/hook-delete-policy: BeforeHookCreation
spec:
  backoffLimit: 1
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: migrate
          image: registry.example.com/shop/api:1.4.2
          # Must be idempotent: it runs again even when nothing changed
          command: ["./bin/migrate", "up"]
---
apiVersion: batch/v1
kind: Job
metadata:
  name: cache-warmup
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/sync-wave: "1"
    # Remove the Job once it succeeds; a failed Job stays for debugging
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: warmup
          image: registry.example.com/shop/api:1.4.2
          command: ["./bin/warm-cache"]

Two PreSync hook Jobs ordered by sync waves, so the migration finishes before the cache warm-up runs, with hook-delete-policy controlling how each Job is cleaned up.

How does a sync with hooks and waves work, step by step?

When a sync starts, whether triggered automatically by a new Git commit or manually from the CLI or UI, Argo CD runs a fixed sequence:

  1. Render and compare. Argo CD renders the manifests from Git (plain YAML, Kustomize or Helm) and compares them with the live objects in the cluster. Regular resources that differ are marked for apply. Every hook is selected, whether or not it changed.
  2. Sort. Each selected resource is placed by phase, then wave, then kind, then name, as described in the first section.
  3. Validate. Argo CD performs a dry run of the manifests, so a malformed object fails the sync before anything is applied.
  4. Run PreSync. Argo CD applies PreSync hooks wave by wave, lowest wave first. It waits for each wave's hooks to complete, for example a Job to succeed, before starting the next wave.
  5. Run Sync. Argo CD applies regular manifests and Sync hooks wave by wave. After each wave it waits until every resource in that wave reports Healthy.
  6. Run PostSync. Once all Sync-phase resources are applied and healthy, Argo CD runs PostSync hooks.
  7. Handle failure. If any step fails, Argo CD stops. It does not apply later waves or phases, marks the operation as failed, and runs any SyncFail hooks.

For a migration this produces a predictable chain. The schema change runs and must succeed. Only then does the new Deployment roll out, and that rollout must become healthy before anything that depends on it is applied. The ordering lives in annotations on the manifests, so it is versioned and reviewed in Git alongside the code it protects.

How do you build a PreSync migration Job?

A migration hook is an ordinary Kubernetes Job with two annotations: argocd.argoproj.io/hook: PreSync and argocd.argoproj.io/hook-delete-policy. The manifest below adds a few settings so that a failed migration stops the rollout.

  • backoffLimit: Keep this low, such as 1 or 2. A migration that fails once usually fails again, and repeated retries against a half-migrated schema can cause damage.
  • activeDeadlineSeconds: Caps the total runtime. Without it, a migration blocked on a table lock holds the sync in Running indefinitely.
  • restartPolicy: Never: Keeps each failed attempt as its own pod, so its logs survive.
  • Image tag: Use the same tag as the Deployment, so the migration code matches the application code that will run against the new schema.

A Job's pod template is immutable, so a sync that applies a changed image to an existing Job fails. Recreate the Job on every sync instead. BeforeHookCreation deletes the previous Job before Argo CD creates the new one. Alternatively, set generateName so each sync creates a Job with a new name.

The delete policies trade debuggability against clutter:

  • HookSucceeded removes successful Jobs, which keeps the cluster clean.
  • HookFailed removes failed Jobs, which also removes the logs you need to diagnose the failure.
  • BeforeHookCreation on its own keeps the last run until the next sync.

A common pairing is BeforeHookCreation,HookSucceeded: it keeps failed Jobs for inspection and cleans up successful ones.

On a first deploy, a PreSync Job cannot read a ConfigMap or Secret that is only created in the Sync phase, so it fails on the missing reference. There are two fixes:

  • Annotate those resources as PreSync hooks at an earlier wave, such as -1.
  • Drop the hook annotation and run the migration in the Sync phase at a wave ahead of the Deployment, after its dependencies.
apiVersion: v1
kind: ConfigMap
metadata:
  name: orders-db-config
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/sync-wave: "-1"
    argocd.argoproj.io/hook-delete-policy: BeforeHookCreation
data:
  DB_HOST: postgres.orders.svc.cluster.local
---
apiVersion: batch/v1
kind: Job
metadata:
  name: orders-db-migrate
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/sync-wave: "0"
    # Delete the old Job before each sync (Job specs are immutable) and
    # remove successful runs; failed Jobs stay so their logs can be read.
    argocd.argoproj.io/hook-delete-policy: BeforeHookCreation,HookSucceeded
spec:
  backoffLimit: 1               # one retry at most; don't hammer a half-migrated schema
  activeDeadlineSeconds: 600    # fail instead of hanging on a table lock
  template:
    spec:
      restartPolicy: Never      # each failed attempt keeps its own pod and logs
      containers:
        - name: migrate
          # Same tag as the Deployment, so migration code matches app code
          image: registry.example.com/orders-api:1.8.3
          command: ["./bin/migrate", "up"]
          envFrom:
            - configMapRef:
                name: orders-db-config
            - secretRef:
                name: orders-db-credentials  # must also exist before PreSync

This example shows a PreSync migration Job with a low retry limit, a runtime deadline, the application's image tag, and a delete policy that keeps failed runs, plus a ConfigMap hook at wave -1 so the Job can read its configuration on the first deploy.

Why health checks decide when the next wave starts

Argo CD moves to the next wave only when every resource in the current wave reports Healthy. What "Healthy" means depends on the resource kind. A Job is healthy when it completes successfully. A Deployment is healthy when its rollout finishes, meaning the updated replicas exist and are available. Availability comes from the readiness probe, so the probe is what actually gates the next wave.

Make readiness mean ready

A probe that returns 200 as soon as the HTTP server binds will pass before the process has connected to the database, warmed caches, or confirmed that the schema matches what the code expects. Argo CD sees the rollout as complete and starts the next wave, so a dependent service or a follow-up data job runs against a backend that cannot serve yet. Point the readiness endpoint at the dependencies the pod needs in order to handle traffic. Keep liveness separate and shallow, so that a slow database marks pods unready instead of restarting them.

Custom resources

Argo CD has built-in health checks for many common CRDs, but not all of them. Without an assessment, a resource can count as healthy the moment it is applied, which lets later waves start too early. A badly written custom Lua check has the opposite risk: if it never returns Healthy, later waves never start. Before you rely on a CRD as a gate, confirm it reports real health.

App-of-apps

Sync waves on child Application resources act as a gate only if Argo CD assesses the health of child Applications. That is not guaranteed by default. Check your health configuration, or keep tightly coupled resources in one Application.

Every extra wave also adds a health wait to every sync, so use only as many waves as your dependencies require.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: orders-api
  annotations:
    # Wave 1 starts after the wave 0 migration Job completes.
    # Wave 2 starts only after this rollout reports Healthy.
    argocd.argoproj.io/sync-wave: "1"
spec:
  replicas: 3
  selector:
    matchLabels:
      app: orders-api
  template:
    metadata:
      labels:
        app: orders-api
    spec:
      containers:
        - name: api
          image: registry.example.com/orders-api:1.4.2
          ports:
            - containerPort: 8080
          # Readiness gates the rollout, and the rollout gates the next wave.
          # /readyz should return 200 only after the DB connection works and
          # the schema version matches what this build expects.
          readinessProbe:
            httpGet:
              path: /readyz
              port: 8080
            periodSeconds: 5
            failureThreshold: 3
          # Liveness stays shallow (process is responsive), so a slow database
          # marks pods unready instead of triggering restarts.
          livenessProbe:
            httpGet:
              path: /healthz
              port: 8080
            periodSeconds: 10
            failureThreshold: 6

A wave-1 Deployment whose readiness probe checks real dependencies. This keeps Argo CD from starting wave 2 until the pods can serve, and the shallow liveness probe avoids restarts when the database is slow.

How do you keep migrations safe during rolling updates and failures?

During a rolling update, old pods keep serving traffic while new pods start. The PreSync migration finishes before any new pod exists, so for a period the old code runs against the new schema. Every migration therefore has to be backward compatible, which is what the expand/contract pattern gives you. In one release, add the new column or table, nullable or with a default. In the same or a later release, switch the code to the new structure. Drop the old structure only in a later release, once no running version reads it. Renaming a column in a single step breaks the old pods immediately.

Argo CD may run the hook again after a retry, a manual resync, or a Job that was deleted and recreated. The migration tool must take a lock, such as an advisory lock or a lock table, and record which steps it has applied. That way a concurrent or repeated run either waits or does nothing.

If a hook or wave fails, the sync stops and later waves are not applied. Run argocd app get <app> to see which resource failed and the operation's message. Then read the Job with kubectl logs job/<job-name> -n <namespace> and kubectl describe job <job-name> -n <namespace>. A Job annotated with argocd.argoproj.io/hook: SyncFail runs only when the sync fails. Use it to send an alert or release a stuck lock.

Reverting Git rolls back manifests, not data. If a migration dropped or rewrote data, the previous image may fail against the schema it now finds, and the rollback itself can cause an outage. Recovery then means restoring from backup or running a forward fix.

When should you avoid running migrations as Argo CD hooks?

A PreSync hook runs on every sync operation, not only on syncs that carry a schema change. Automated syncs triggered by an unrelated manifest edit, self-heal syncs that correct drift, and manual syncs with nothing to apply all run the migration Job again. If your migration tool tracks applied versions, the cost is a pod start, a database connection, and a few seconds of delay per sync. If any migration is not idempotent, such as a raw ALTER TABLE or a data backfill without a guard, the second run fails or corrupts data. Even well-behaved migrations add lock checks and connection churn against a production database every time someone edits a ConfigMap.

Hooks and waves provide ordering, not orchestration. Argo CD will not branch on a migration's output, retry one step while holding the others, or confirm that the running application works with the new schema before it moves on. A Job that exits zero counts as success, even if the application then fails at runtime.

Long migrations cause a different problem. Each release waits for the migration to finish. A large backfill can exceed the Job's activeDeadlineSeconds or your sync timeout and leave the schema half-applied. While the sync operation is running, no other change to that Application can sync, so an urgent config fix has to wait for the backfill.

This approach suits teams whose migrations are short, idempotent, and backward-compatible, and who deploy each service as a single Application that owns its own schema.

Who should use sync waves for database migrations?

Sync-wave migrations fit best when all of the following are true:

  • You already deploy with Argo CD. Adding annotations to existing manifests is a small change. Adopting Argo CD just to order migrations is a much larger one.
  • One Application owns one schema. The service and its database migrations live in the same repository or Application, so a single sync covers both. If several Applications write to a shared database, no single sync can order their migrations, and you need coordination outside Argo CD.
  • Migrations are short and versioned. Your migration tool records applied versions and takes a lock, so the per-sync rerun is a cheap no-op. Migrations finish well within the Job deadline.
  • The team practises expand/contract. Developers write backward-compatible schema changes and reviewers check for them, because Argo CD will not catch an incompatible change.
  • You run several environments from the same manifests. Staging, production and ephemeral preview environments all get the same ordering without per-environment scripts.

The main readers are application teams that own a service end to end and platform engineers who define deployment conventions for those teams. Teams with long-running data backfills, migrations that need a manual approval step, or databases shared across many services should run migrations through a dedicated process. Use the comparison in the next section to choose one.

What are the alternatives to sync-wave migrations, and what do they cost?

If those conditions don't hold, the migration has to run somewhere else, and each placement moves the cost to a different team or system.

Approach Replica races Deploy state lives Failure visibility Release speed tied to migration time Operational effort
PreSync hook or wave Job None: one Job runs before pods roll Git (manifests and annotations) Sync status and Job logs in Argo CD Yes, the sync blocks until the Job finishes Learning hook phases, delete policies, retry behaviour
Migration at app startup Every replica tries to migrate, so you need a database lock Git, but the ordering is hidden in application code Crash-looping pods, with the cause buried in app logs Yes, per pod: a slow migration can fail readiness probes Lock and timeout handling in every service
Separate pipeline step None, if the pipeline is serialized Outside Git, in CI run history CI job output only. Argo CD doesn't know it happened Partly: the migration can run ahead of the deploy Two systems to keep in step, plus manual reruns

Hooks and waves remove the runbook step of "run the migration, confirm it, then merge the deploy." No one has to sequence it by hand. The ongoing costs are debugging hook semantics when a Job misbehaves and enforcing expand/contract in code review. No tool does that review for you.

Illustrative estimate (assumed numbers, not a benchmark).

The yearly saving is:

hours saved = schema deploys per week × minutes of manual sequencing per deploy × weeks ÷ 60

Assumed inputs:

  • 4 schema-changing deploys per week
  • 20 minutes of manual sequencing per deploy
  • 50 working weeks

That gives 4 × 20 × 50 ÷ 60 ≈ 67 hours per year.

Assumed ongoing costs:

  • 1 hour per month debugging hooks = 12 hours
  • 30 minutes per week reviewing expand/contract = 25 hours

That totals 37 hours, so the net saving is about 30 hours per year. With fewer schema changes, the net saving drops toward zero.

How can sync waves save engineering time?

The estimate above covers only the most visible saving, the manual sequencing. Sync waves also save time in several other ways:

  • No human in the ordering loop. Without encoded ordering, someone has to run the migration, check that it succeeded, and then release the deploy. With waves, merging the commit starts the whole chain, and nobody waits on a terminal to trigger the next step.
  • Fewer ordering failures to clean up. A Deployment cannot roll out before its migration succeeds, and a migration cannot run before its ConfigMap exists, provided the waves are set correctly. That removes a class of incidents in which new pods start against an old schema and someone has to diagnose and roll them back.
  • One place to look when something breaks. A failed migration stops the sync. The failing resource appears in argocd app get, and the Job's pod and logs remain in the cluster if the delete policy keeps failed runs. Engineers don't have to correlate CI logs with cluster state to work out what ran.
  • New environments order themselves. A fresh cluster, namespace or preview environment syncs from the same manifests and gets the same ordering. You don't need a bootstrap script or a written sequence of steps.
  • Less custom pipeline code. The ordering logic is a few annotations in Git rather than scripts in a CI system that each team maintains separately.

These savings depend on the conditions in the section on who should use this approach. If migrations are not idempotent, run long, or touch a shared database, the time goes into debugging reruns and blocked syncs instead, and a separate migration process is usually cheaper.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to argo cd sync waves, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.