Demo Sync Hook 2

This guide continues the Sync Hooks demo and shows how to enforce ordering between jobs and deployments in Argo CD using hook annotations (PreSync, Sync, PostSync), sync waves, and hook-delete-policy. This prevents jobs such as database migrations from running in parallel with deployments and ensures predictable lifecycle and cleanup of hook resources. Why use hooks?

Ensure a DB migration runs before application Deployments.
Run notifications or cleanup only after a successful sync.
Control whether hook resources are retained or removed.

Key annotation keys (Argo CD hooks)

Annotation	Purpose	Example
`argocd.argoproj.io/hook`	Defines hook phase: `PreSync`, `Sync`, `PostSync`	`argocd.argoproj.io/hook: PreSync`
`argocd.argoproj.io/hook-delete-policy`	Controls cleanup: `HookSucceeded`, `HookFailed`, `BeforeHookCreation`	`argocd.argoproj.io/hook-delete-policy: HookSucceeded`
`argocd.argoproj.io/sync-wave`	Numeric ordering when using sync waves	`argocd.argoproj.io/sync-wave: "5"`

For more details see the Argo CD hooks docs:

Open the Git repository and navigate to the synchronization/hooks folder to add the manifests and annotations.

A dark-themed Gitea repository page showing the kk-org/gitops-argocd-capa project with the "synchronization" folder open, listing subfolders like hooks, waves, and waves-demo. The left sidebar shows the repo file tree and the main pane shows recent file commits.

Step 1 — Add a PreSync DB migration Job

Purpose: run a migration before any application resources are created.
Desired lifecycle: the job should be removed after it succeeds.

Example manifest (db-migration-job.yaml):

# db-migration-job.yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: db-migration-job
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
  template:
    spec:
      containers:
        - name: db-migration
          image: alpine:3.12
          command: ["/bin/sh", "-c", "echo 'Running Database Migration...' && sleep 15 && echo 'Database Migration Complete.'"]
      restartPolicy: Never
  backoffLimit: 2

Step 2 — Add a PostSync notification Job (optional)

Purpose: send a notification after a successful sync.
Recommended cleanup: delete after success so notifications don’t persist.

Example manifest (slack-notification-job.yaml):

# slack-notification-job.yaml
apiVersion: batch/v1
kind: Job
metadata:
  generateName: app-slack-notification-
  annotations:
    argocd.argoproj.io/hook: PostSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
  template:
    spec:
      containers:
        - name: slack-notification
          image: curlimages/curl
          command:
            - /bin/sh
            - -c
            - >
              curl -X POST --data-urlencode 'payload={"channel":"#somechannel","username":"hello","text":"App Sync succeeded","icon_emoji":":ghost:","attachments":[{"text":"https://hooks.slack.com/services/..."}]}' https://hooks.slack.com/services/...
      restartPolicy: Never
  backoffLimit: 2

A screenshot of an Argo CD documentation page titled "Hook lifecycle and cleanup," showing a table of hook-delete policies and a section called "How sync waves work?" with left-side navigation and a right-hand table of contents.

Step 3 — Optional PostSync cleanup job

Purpose: run remedial cleanup when a sync completes (e.g., remove temp resources).
Example policy: delete only on failure to preserve artifacts for troubleshooting.

Example manifest (cleanup-job.yaml):

# cleanup-job.yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: cleanup-job
  annotations:
    argocd.argoproj.io/hook: PostSync
    argocd.argoproj.io/hook-delete-policy: HookFailed
spec:
  template:
    spec:
      containers:
        - name: cleanup
          image: alpine:3.12
          command: ["/bin/sh", "-c", "echo 'Running Cleanup Job...' && sleep 10 && echo 'Cleanup Complete.'"]
      restartPolicy: Never
  backoffLimit: 2

Commit and push these manifests to your Git repo.

A dark-themed Gitea web interface showing a "Commit Changes" form with fields for a commit message and description, options to commit to the main branch or create a new branch, and blue "Commit Changes" and red "Cancel" buttons. The footer displays "Powered by Gitea" and version information.

Hook phases act like guardrails: a PreSync hook must succeed before Sync proceeds; a failing PreSync stops the synchronization and prevents deployments.

How phases work

Happy path: PreSync → Sync → PostSync
If Sync fails, PostSync is typically not executed unless you configure alternative lifecycle behaviors.

Step 4 — Create the Argo CD Application Create the application pointing to the folder with your hooks:

argocd app create sync-hooks-2 \
  --repo http://host.docker.internal:5000/kk-org/gitops-argocd-capa \
  --path ./synchronization/hooks \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace sync-hooks-2 \
  --project default \
  --revision HEAD \
  --sync-policy auto

If the destination namespace does not exist, create it:

kubectl create namespace sync-hooks-2

If the app shows OutOfSync or Missing, it may indicate the namespace was absent or a previous sync is in progress. You can terminate a stuck sync and start a fresh manual sync.

A screenshot of the Argo CD web UI showing the "sync-hooks-2" application marked OutOfSync and Missing, with a right-hand synchronize panel displaying sync options and checkboxes.

What to expect during a sync

Argo CD creates the PreSync DB migration Job (hook icon shown).
Argo CD waits for the Job to finish successfully.
If the Job succeeds, Argo CD proceeds to create normal resources (Deployment, Service, etc.) — the Sync phase.
If the Sync succeeds, PostSync hooks (cleanup, notifications) execute as configured.
hook-delete-policy determines whether Jobs remain after success/failure.

During the demo:

The migration job was created and completed.
Deployments were created in the Sync phase.
A cleanup job ran afterwards and, due to the delete policy, the DB migration job was deleted.

A screenshot of the Argo CD web UI showing the "sync-hooks-2" application with a Healthy app health and Synced status. The main pane displays a resource tree/diagram with deployable resources like nginx and a cleanup-job and their pods.

Recommended patterns

Pattern	When to use	Notes
PreSync job + HookSucceeded	DB migrations or schema changes that must happen before deployments	Clean up after success to avoid clutter
PostSync job + HookSucceeded	Notifications (Slack, PagerDuty)	Use generateName for unique jobs
PostSync job + HookFailed	Cleanup only when sync fails	Preserve logs for debugging by keeping failed hooks

Summary

Use argocd.argoproj.io/hook: PreSync to force jobs to run before your main sync.
Use argocd.argoproj.io/hook: PostSync for notifications/cleanup after successful syncs.
Use argocd.argoproj.io/hook-delete-policy to control retention of hook resources.
Optionally use argocd.argoproj.io/sync-wave for finer-grained numeric ordering across many resources.

Links and References

Argo CD Hooks — https://argo-cd.readthedocs.io/en/stable/user-guide/hooks/
Argo CD Sync Waves — https://argo-cd.readthedocs.io/en/stable/user-guide/sync-waves/
Argo CD CLI docs — https://argo-cd.readthedocs.io/en/stable/user-guide/commands/

ArgoCD

Argo Workflow

Argo Rollouts

Argo Events

Introduction

Watch Video