Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 37 ยท Sync and Health

Argo CD Sync Hooks and Rollbacks: Migrations, Smoke Tests, Recovery

Run Jobs before, during and after a sync with Argo CD resource hooks (PreSync, PostSync, SyncFail), choose a delete policy, and roll back safely with Git reverts or argocd app rollback.

Not every deployment step is "apply this YAML". A database migration must finish before the new application version starts. A smoke test should run after it is up. A failed sync might need a notification. Argo CD handles these with resource hooks: ordinary Kubernetes resources (usually Jobs) annotated to run at a point in the sync. This lesson also covers the other half of delivery safety: getting back to a good state when a release goes wrong.

The manifests are real Argo CD syntax but read-only here. The runnable blocks are stand-ins: a hook runner simulation and a history/rollback model.

Hook types

Hook When it runs
PreSync Before the main sync starts (migrations, backups).
Sync During the sync, together with normal resources, ordered by wave.
PostSync After the sync finished and the app is healthy (smoke tests, notifications).
SyncFail If the sync fails (cleanup, alerts).
PostDelete After the Application and its resources are deleted.

A hook is just a manifest with annotations:

YAML
apiVersion: batch/v1
kind: Job
metadata:
  generateName: shop-migrate-
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
  backoffLimit: 0
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: migrate
          image: registry.example.com/shop/migrate:1.8.2
          command: ["./migrate", "up"]

Argo CD creates the Job, waits for it to complete and only then continues. If the Job fails, the sync fails and the new version is not applied. That is exactly what you want for a migration.

Delete policies

argocd.argoproj.io/hook-delete-policy controls cleanup:

  • HookSucceeded: delete after it succeeds.
  • HookFailed: delete after it fails.
  • BeforeHookCreation (default): delete the previous instance just before creating a new one, so the last run stays visible for debugging.

Use generateName (not a fixed name) together with HookSucceeded, or a fixed name with BeforeHookCreation.

Hooks and waves

Hooks of the same type can be ordered with argocd.argoproj.io/sync-wave, for example a backup Job in wave -1 and a migration in wave 0, both PreSync.

Smoke test after deploy

YAML
apiVersion: batch/v1
kind: Job
metadata:
  generateName: shop-smoke-
  annotations:
    argocd.argoproj.io/hook: PostSync
    argocd.argoproj.io/hook-delete-policy: BeforeHookCreation
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: check
          image: curlimages/curl:8.10.1
          command: ["curl", "--fail", "--silent", "http://web.shop.svc/healthz"]

If the check fails, the Application shows a failed sync with the hook's logs available in the UI. (Remember a PostSync failure does not undo the sync that already happened; use progressive delivery such as Argo Rollouts for automatic rollback on failed analysis.)

Stand-in: simulate a hook-driven sync

This model runs PreSync, Sync and PostSync steps in order and stops at the first failure, jumping to SyncFail hooks.

JS Stand-in: hook runner

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Rollbacks

Argo CD records each sync in status.history (up to revisionHistoryLimit, default 10). Two ways to go back:

  1. The GitOps way: revert in Git. Create a revert commit, merge it, and Argo CD syncs the earlier state. History stays honest and every environment reading that branch agrees.
  2. The emergency way: argocd app rollback.
Terminal
argocd app history shop
argocd app rollback shop 7

This re-applies the manifests of history ID 7 immediately. It has a catch: rollback requires automated sync to be off (otherwise the next reconcile would instantly re-apply Git's current state), and afterwards the Application is OutOfSync with Git until you fix Git. Treat it as a fast brake, then make Git match.

Rolling back the Deployment does not roll back database changes made by a migration hook. Design migrations to be backward compatible (expand, then contract) so the old version still works against the new schema.

Stand-in: history and rollback

This model tracks sync history and shows how an emergency rollback leaves the app OutOfSync until Git is fixed.

JS Stand-in: history and rollback

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Good practices

  • Make hooks idempotent: they may run again on every sync.
  • Give hook Jobs backoffLimit: 0 or a small value, and a ttlSecondsAfterFinished or delete policy so they do not pile up.
  • Keep PreSync hooks short; a long migration holds up every sync.
  • Never put secrets in hook scripts; use Secrets.
  • After an emergency rollback, fix Git immediately.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A PreSync migration Job fails. What happens to the sync?

    Argo CD waits for PreSync hooks to succeed before applying the main resources.
  2. 2. Which delete policy keeps the previous hook run for debugging until the next sync?

    BeforeHookCreation, the default, deletes the old hook only right before creating a new one.
  3. 3. Why must automated sync be disabled before argocd app rollback?

    Automated sync would undo the rollback because Git still holds the newer version.
  4. 4. What is the durable way to undo a bad release?

    Git is the source of truth; a revert commit keeps all environments and history consistent.

Summary

  • Hooks are annotated resources (usually Jobs) that run at PreSync, Sync, PostSync, SyncFail or PostDelete.
  • A failing PreSync hook stops the sync; use it for migrations and backups.
  • Delete policies (HookSucceeded, HookFailed, BeforeHookCreation) control cleanup.
  • Roll back by reverting Git; argocd app rollback is an emergency brake that needs auto-sync off.
  • Make hooks idempotent and migrations backward compatible.

Next: Helm Charts in Argo CD