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.
Phases and hooks
Section titled “Phases and hooks”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/v1kind: Jobmetadata: generateName: schema-update- annotations: argocd.argoproj.io/hook: PreSync| Hook | When it runs |
|---|---|
PreSync | Before any manifests are applied. Typical use: database migrations and prerequisite checks |
Sync | After all PreSync hooks succeed, at the same time as the main manifests are applied |
PostSync | After all Sync work has succeeded and every resource is Healthy. Typical use: smoke tests and notifications |
SyncFail | Only when the sync operation fails. Typical use: cleanup and alerts |
PreDelete | Before the Application’s resources are deleted. Runs only when the whole Application is deleted, never during a normal sync, even with pruning |
PostDelete | After all the Application’s resources are deleted. Typical use: removing external resources |
Skip | Tells 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.
Hook cleanup
Section titled “Hook cleanup”Hooks create real objects, so they accumulate unless a deletion policy removes them. Set it with argocd.argoproj.io/hook-delete-policy:
| Policy | Behavior |
|---|---|
BeforeHookCreation | Deletes 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 |
HookSucceeded | Deletes the hook object once it succeeds |
HookFailed | Deletes the hook object after it fails |
metadata: annotations: argocd.argoproj.io/hook: PostSync argocd.argoproj.io/hook-delete-policy: HookSucceededLeaving 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.
Sync waves
Section titled “Sync waves”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:
- phase
- wave, lowest first
- kind, so namespaces come before other resources and custom resources come last
- 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:
| Wave | Resources |
|---|---|
-1 | Namespace |
0 | ServiceAccounts and default configuration |
1 | PersistentVolumeClaim and database workload |
2 | Database Service |
3 | Web application Deployment |
4 | Web 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.
Combining phases and waves
Section titled “Combining phases and waves”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 startsmetadata: annotations: argocd.argoproj.io/hook: PreSync argocd.argoproj.io/sync-wave: "3"---# runs later, despite the lower wave numbermetadata: 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.
| Need | Use |
|---|---|
| Run something before or after the whole deployment | A hook in PreSync or PostSync |
| Order ordinary resources, such as database before web tier | Sync waves on the manifests |
| Order several steps inside one phase | A hook phase plus waves |
| Act only on failure or on deletion | SyncFail, PreDelete, or PostDelete |
Troubleshooting
Section titled “Troubleshooting”| Symptom | Likely cause | Fix |
|---|---|---|
| Sync is stuck on “waiting for completion of hook” | The hook Job or Pod never finishes, or its previous run is still pending deletion | Inspect the hook’s logs and status. If the hook should not run at all, annotate it with hook: Skip |
| Nothing deployed after a failed sync | A PreSync hook failed, which halts the sync by design | Fix the hook, then sync again |
The Application never reaches Healthy | A resource in an early wave is unhealthy, so later waves wait | Fix the first unhealthy resource, or check that its probes are correct |
| A lower wave ran after a higher one | They are in different phases | Wave numbers compare only within a phase |
| Hooks did not run | The sync was a selective sync | Run a full sync |
| Hook objects pile up | No deletion policy removes finished ones | Set hook-delete-policy, or use BeforeHookCreation with a fixed name |
| Later waves start before dependencies are ready | The dependency has no readiness probe | Add readiness probes so health reflects reality |