Sync, hooks and waves¶
Status: AI draft, 2026-11-16. Not yet verified by me. Written from the Argo CD documentation; nothing was run.
In one line¶
A refresh re-reads Git and compares; a sync applies the difference. Sync manually or automatically, with prune to delete what Git no longer has and selfHeal to undo changes made in the cluster. Sync options tune how resources are applied, ignoreDifferences skips fields other controllers own, and hooks (PreSync, Sync, PostSync, SyncFail) plus sync waves order what happens.
The plain idea¶
Argo CD knows what Git says and what the cluster has (Argo CD architecture and Applications). Two questions remain: when does it make the cluster match, and in what order? A database migration must finish before the new pods start; a CRD must exist before the objects that use it; a notification should go out after everything is healthy. Sync policies answer "when"; phases, hooks and waves answer "in what order".
How it works¶
Refresh vs sync¶
| Action | Does |
|---|---|
| Refresh | Re-reads Git and the cluster and recomputes sync status; changes nothing |
| Hard refresh | Same, but also discards the repo server's cached manifests (after a chart or plugin changed without a new commit) |
| Sync | Applies the rendered manifests to the cluster |
Manual vs automated sync¶
syncPolicy:
automated:
enabled: true
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true
- ServerSideApply=true
| Setting | Default | Effect |
|---|---|---|
automated |
Off (manual) | Sync whenever Git changes |
prune |
false |
Delete live resources that were removed from Git |
selfHeal |
false |
Re-sync when the live state is changed in the cluster, not only when Git changes |
automated.enabled: false |
Keep the other settings but pause auto-sync, for example during an incident |
Without prune, removing a file from Git leaves the object running and the app OutOfSync. Without selfHeal, a kubectl edit stays until the next Git change.
Useful sync options¶
| Option | Use |
|---|---|
CreateNamespace=true |
Create the destination namespace if missing |
ServerSideApply=true |
Server-side apply: field ownership, large objects such as CRDs that exceed annotation limits |
Replace=true |
Delete and recreate instead of apply; for objects that cannot be patched (use sparingly) |
PruneLast=true |
Prune after everything else is applied and healthy |
ApplyOutOfSyncOnly=true |
Apply only changed objects, for apps with many resources |
RespectIgnoreDifferences=true |
Also skip ignored fields when syncing, not only when comparing |
Per resource argocd.argoproj.io/sync-options: Prune=false |
Never prune this object |
Per resource argocd.argoproj.io/sync-options: Delete=false |
Keep this object even when the Application is deleted (Deletion, finalizers and safe cleanup) |
ignoreDifferences¶
Some fields are owned by other controllers: an HPA sets spec.replicas, a webhook injects a CA bundle, a mutating admission adds defaults. Without telling Argo CD, the app is forever OutOfSync and self-heal fights the other controller.
spec:
ignoreDifferences:
- group: apps
kind: Deployment
jsonPointers:
- /spec/replicas
- group: admissionregistration.k8s.io
kind: MutatingWebhookConfiguration
jqPathExpressions:
- .webhooks[]?.clientConfig.caBundle
Better still, remove replicas from the manifest when an HPA owns it (Autoscaling).
Phases, hooks and waves¶
flowchart TD
A["PreSync hooks: for example<br/>a database migration Job"] -->|"all succeeded"| B["Sync phase: manifests and Sync hooks,<br/>wave by wave, lowest wave first"]
B -->|"all applied and Healthy"| C["PostSync hooks: smoke tests,<br/>notifications"]
A -->|"any failed"| F["SyncFail hooks:<br/>cleanup, alerts"]
B -->|"failed"| F
- Hooks are resources annotated
argocd.argoproj.io/hook: PreSync(orSync,PostSync,SyncFail,Skip, plusPreDeleteandPostDeletearound deletion). They are usually Jobs. - Hook delete policy
argocd.argoproj.io/hook-delete-policy:HookSucceeded,HookFailedorBeforeHookCreation. - Waves:
argocd.argoproj.io/sync-wave: "-1". Everything is in wave 0 by default; lower waves are applied first, and Argo CD waits for a wave to be healthy before starting the next. Within a phase and wave, order is by kind (namespaces and CRDs before the objects that need them), then name.
apiVersion: batch/v1
kind: Job
metadata:
name: sample-app-migrate
annotations:
argocd.argoproj.io/hook: PreSync
argocd.argoproj.io/hook-delete-policy: BeforeHookCreation
spec:
backoffLimit: 1
template:
spec:
restartPolicy: Never
containers:
- name: migrate
image: registry.example.com/sample-app:1.4.2
command: ["./migrate", "up"]
Helm hooks under Argo CD¶
Argo CD renders Helm charts with helm template, not helm install, so there is no Helm release. It maps Helm hook annotations to its own: pre-install and pre-upgrade become PreSync, post-install and post-upgrade become PostSync, pre-delete becomes PreDelete; pre-rollback is not supported. The mapping is annotation compatibility, not identical behaviour, so test charts with hooks under Argo CD (Releases, hooks and debugging).
A concrete example¶
sample-app's Application, in order:
- Wave
-1: the ConfigMap and ExternalSecret the app needs. - PreSync hook: the migration Job; a failure stops the sync before the new version starts.
- Wave
0: Deployment and Service. - Wave
1: the Ingress, so traffic is routed only once pods are healthy. - PostSync hook: a smoke test Job against the Service.
- SyncFail hook: a Job that posts to the team channel.
ignoreDifferenceson/spec/replicasbecause an HPA scales it.
Why not just...?¶
- ...turn on
pruneandselfHealeverywhere on day one? Prune deletes anything removed from Git, including by a bad merge, and self-heal reverts emergency fixes. Turn them on per app once the repository is trusted, with protections on critical objects. - ...order things with waves alone? Waves wait for health, but a migration should be a hook: a Job whose failure stops the sync.
- ...silence OutOfSync with broad
ignoreDifferences? Real drift then goes unseen. Ignore the exact fields another controller owns.
Commands to know¶
These were not run for this page.
| Command | What it does |
|---|---|
argocd app get sample-app-prod --refresh |
Refresh and show status. |
argocd app get sample-app-prod --hard-refresh |
Refresh without the manifest cache. |
argocd app sync sample-app-prod |
Sync now. |
argocd app sync sample-app-prod --resource apps:Deployment:sample-app |
Sync one resource (selective sync). |
argocd app set sample-app-prod --self-heal |
Turn on self-heal. |
argocd app diff sample-app-prod |
What a sync would change. |
argocd app terminate-op sample-app-prod |
Stop a running sync, for example one stuck on a hook. |
How it breaks¶
| Symptom | Layer | Check | Likely cause |
|---|---|---|---|
| Always OutOfSync on one field | Ownership | Diff | Another controller (HPA, webhook, admission) changes it; ignore that field |
| Sync stuck in PreSync | Hook | Hook Job pods and logs | Migration Job hanging or failing; no backoffLimit or deadline |
| Old hook Job blocks the next sync | Hook cleanup | Delete policy | Missing BeforeHookCreation |
| Removed resource still running | Prune | Sync policy | prune is off (the default) |
| CRD too large to apply | Apply method | Error message about annotations | Use ServerSideApply=true |
| Emergency change reverted | Self-heal | Sync policy | Self-heal on; commit the change or pause auto-sync |
Interview questions¶
1. What is the difference between refresh, hard refresh and sync?
Answer
- Refresh: recompare Git and cluster.
- Hard refresh: the same, without the cached rendered manifests.
- Sync: apply the desired state to the cluster.
2. What do prune and selfHeal do, and what are their defaults?
Answer
prune: delete live objects removed from Git. Off by default.selfHeal: re-sync when the cluster is changed directly. Off by default.- Both make Git authoritative; enable them deliberately.
3. How do you run a database migration before the new version starts?
Answer
- A Job with
argocd.argoproj.io/hook: PreSyncand a delete policy. - If it fails, the sync stops before the Deployment changes.
- Make the migration backward compatible, because a revert will not undo it.
4. What are sync waves?
Answer
- An annotation with an integer; lower waves are applied first, default 0, negatives allowed.
- Argo CD waits for each wave to be healthy before the next.
- Used to order config before workloads, workloads before ingress.
5. An app is always OutOfSync on spec.replicas. Why, and how do you fix it?
Answer
- An HPA changes the replica count; Git has a fixed value.
- Remove
replicasfrom the manifest, or addignoreDifferencesfor that field (andRespectIgnoreDifferences). - Otherwise self-heal fights the HPA.
6. How do Helm hooks behave under Argo CD?
Answer
- Argo CD renders the chart and maps Helm hook annotations to its phases: pre-install and pre-upgrade to PreSync, post-* to PostSync.
pre-rollbackis not supported; there is no Helm release history.- Test charts with hooks under Argo CD rather than assuming Helm semantics.
Try it¶
- Annotate the Kustomize example's resources (Kustomize, and Helm vs Kustomize) with waves so the ConfigMap comes first and the Service last.
- Write a PostSync smoke test Job that runs
wget -qO- http://sample-app/healthzand is deleted when it succeeds. - Decide
pruneandselfHealfor three apps: a stateless web app, a database operator, and the monitoring stack. Justify each.
Zoom out¶
Sync policies decide how strictly Git rules the cluster; hooks and waves bring the ordering that plain declarative YAML lacks. They connect to Helm hooks, Kubernetes Jobs and deployment strategies (Releases, hooks and debugging, Deployment strategies).