Skip to content
Documentation Background

Sync phases, hooks, and waves

By default Argo CD applies manifests in a built-in order by resource kind. Real deployments need more control: a database migration before the new version starts, storage before the database, a smoke test after everything is up. Phases give coarse ordering around the main sync, and waves give exact ordering within it.


A hook is a resource that Argo CD runs at a specific point in the sync lifecycle. Assign it to a phase with the argocd.argoproj.io/hook annotation. Hooks can be any Kubernetes kind but are usually a Pod, a Job, or an Argo Workflow. A manifest with no hook annotation belongs to the Sync phase.

apiVersion: batch/v1
kind: Job
metadata:
generateName: schema-update-
annotations:
argocd.argoproj.io/hook: PreSync
HookWhen it runs
PreSyncBefore any manifests are applied. Typical use: database migrations and prerequisite checks
SyncAfter all PreSync hooks succeed, at the same time as the main manifests are applied
PostSyncAfter all Sync work has succeeded and every resource is Healthy. Typical use: smoke tests and notifications
SyncFailOnly when the sync operation fails. Typical use: cleanup and alerts
PreDeleteBefore the Application’s resources are deleted. Runs only when the whole Application is deleted, never during a normal sync, even with pruning
PostDeleteAfter all the Application’s resources are deleted. Typical use: removing external resources
SkipTells Argo CD not to apply the manifest at all

One resource can have several hooks, separated by commas.

flowchart LR
    A["PreSync hooks"] --> B["Sync: apply manifests"]
    B --> C["PostSync hooks"]
    A -.->|"failure"| F["SyncFail hooks"]
    B -.->|"failure"| F
    C -.->|"failure"| F

A sync proceeds phase by phase. If a PreSync hook fails, the sync stops and is marked failed, and the main manifests are never applied. A failing Sync or PostSync hook also marks the whole sync failed. If a SyncFail hook itself fails, Argo CD takes no further action. Hooks do not run during a selective sync. In the web UI, resources running as hooks carry an anchor icon.

PreDelete and PostDelete hooks work during deletion. A failing PreDelete hook blocks the deletion: the Application stays in a deleting state with a DeletionError condition until the hook succeeds or is deleted. A failing PostDelete hook leaves the Application resource in place, also with a DeletionError, even though its managed resources are already gone.

Hooks create real objects, so they accumulate unless a deletion policy removes them. Set it with argocd.argoproj.io/hook-delete-policy:

PolicyBehavior
BeforeHookCreationDeletes any existing hook object before the new one is created. The default when no policy is set. Intended for hooks with a fixed metadata.name
HookSucceededDeletes the hook object once it succeeds
HookFailedDeletes the hook object after it fails
metadata:
annotations:
argocd.argoproj.io/hook: PostSync
argocd.argoproj.io/hook-delete-policy: HookSucceeded

Leaving out HookFailed keeps failed hook Pods around so their logs can be read. A hook with a fixed metadata.name can only run again if the object from the previous run is gone, which is why BeforeHookCreation is the default. The alternative is metadata.generateName, which gives each run a new object, though tools such as Kustomize have limited support for it. Hooks can run on repeated syncs, so write them to be idempotent.

Use Skip when a manifest from a chart should never be applied. A Helm chart that ships a hook Job which cannot complete under Argo CD can be unblocked by annotating that Job with argocd.argoproj.io/hook: Skip.


A sync wave orders resources numerically inside a sync. The annotation value is an integer written as a string:

metadata:
annotations:
argocd.argoproj.io/sync-wave: "1"

Resources and hooks without the annotation are in wave 0. Waves can be negative, which creates a wave that runs before everything else.

Argo CD orders resources by, in this precedence:

  1. phase
  2. wave, lowest first
  3. kind, so namespaces come before other resources and custom resources come last
  4. name

It then finds the first wave that has any out-of-sync or unhealthy resource, applies that wave, waits for its resources to become healthy, and repeats until every phase and wave is in sync and healthy. Between waves there is a 2-second delay (set with the ARGOCD_SYNC_WAVE_DELAY environment variable). It gives other controllers time to react to the change just applied and stops Argo CD from judging health against a stale object.

An example ordering for an application with a database:

WaveResources
-1Namespace
0ServiceAccounts and default configuration
1PersistentVolumeClaim and database workload
2Database Service
3Web application Deployment
4Web application Service

Pruning runs in reverse. Resources in higher waves are pruned first, so dependents go before the things they depend on, and a failure in one wave stops pruning of the lower ones.

Waves advance on health, so they are only as accurate as the health signal. Without readiness probes, a Deployment looks ready as soon as its containers start and the next wave begins too early. See application health. If a resource in an early wave never becomes healthy, the Application cannot reach Healthy either.


Phases outrank waves, and wave numbers only compare inside one phase. A PreSync Job in wave 3 runs before a PostSync Job in wave 1, because the whole PreSync phase finishes before PostSync begins.

# runs first: PreSync completes before PostSync starts
metadata:
annotations:
argocd.argoproj.io/hook: PreSync
argocd.argoproj.io/sync-wave: "3"
---
# runs later, despite the lower wave number
metadata:
annotations:
argocd.argoproj.io/hook: PostSync
argocd.argoproj.io/sync-wave: "1"

Scoping lets one phase hold a multi-step routine. In PreSync, a backup can run at wave 1, a schema migration at wave 2, and a pre-flight check at wave 3, without affecting the order of anything in other phases.

NeedUse
Run something before or after the whole deploymentA hook in PreSync or PostSync
Order ordinary resources, such as database before web tierSync waves on the manifests
Order several steps inside one phaseA hook phase plus waves
Act only on failure or on deletionSyncFail, PreDelete, or PostDelete

SymptomLikely causeFix
Sync is stuck on “waiting for completion of hook”The hook Job or Pod never finishes, or its previous run is still pending deletionInspect the hook’s logs and status. If the hook should not run at all, annotate it with hook: Skip
Nothing deployed after a failed syncA PreSync hook failed, which halts the sync by designFix the hook, then sync again
The Application never reaches HealthyA resource in an early wave is unhealthy, so later waves waitFix the first unhealthy resource, or check that its probes are correct
A lower wave ran after a higher oneThey are in different phasesWave numbers compare only within a phase
Hooks did not runThe sync was a selective syncRun a full sync
Hook objects pile upNo deletion policy removes finished onesSet hook-delete-policy, or use BeforeHookCreation with a fixed name
Later waves start before dependencies are readyThe dependency has no readiness probeAdd readiness probes so health reflects reality