Sync Waves and Resource Hooks
What you'll learn: How to precisely control the order your Kubernetes resources deploy and execute special actions before or after syncing.
The Deployment Orchestra Problem
When ArgoCD syncs your application, it deploys all resources at once by default. But what if your database migration must run before your app pods start? Or you need to validate something after deployment? This is where sync waves and resource hooks become essential.
Sync Waves: Ordered Deployment
Sync waves let you assign a numeric phase to each resource using the annotation argocd.argoproj.io/sync-wave. ArgoCD deploys resources in ascending wave order:
apiVersion: v1
kind: ConfigMap
metadata:
name: app-config
annotations:
argocd.argoproj.io/sync-wave: "0" # Deploys first
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: backend
annotations:
argocd.argoproj.io/sync-wave: "1" # Deploys second
Think of it like a concert: Wave 0 tunes instruments, Wave 1 starts the melody, Wave 2 adds harmony. Each wave completes fully before the next begins.
Resource Hooks: Special Actions
Hooks are temporary resources that run at specific sync lifecycle points:
PreSync: Before any wave (migrations, backups)Sync: During regular deploymentPostSync: After all waves (tests, notifications)SyncFail: If sync fails (rollback actions)
apiVersion: batch/v1
kind: Job
metadata:
name: db-migration
annotations:
argocd.argoproj.io/hook: PreSync
argocd.argoproj.io/hook-delete-policy: BeforeHookCreation
Hooks run once and can self-delete. They're perfect for one-time setup tasks that shouldn't persist.
Key Takeaway: Sync waves control resource deployment order numerically, while hooks execute special jobs at specific lifecycle points—together they give you fine-grained control over complex application rollouts.