Mastering Argo CD Sync Phases and Waves for Reliable Deployments
Sync phases and waves in Argo CD exist to streamline the deployment process and ensure that resources are applied in a controlled manner. They help you manage dependencies and execution order, which is critical when dealing with complex applications that require specific initialization steps before deployment.
Argo CD operates through several key phases: PreSync, Sync, and PostSync. PreSync hooks run before the application of manifests, allowing you to perform necessary tasks like database migrations. The Sync phase executes after all PreSync hooks have completed successfully, applying the manifests themselves. Finally, PostSync hooks run after the Sync phase, ensuring that any follow-up actions, such as notifications or cleanup tasks, occur only after a successful deployment. You can also control the execution order of resources using the argocd.argoproj.io/sync-wave annotation, which allows you to define the sequence in which resources are applied. If any hook fails at any phase, the entire sync process halts, marking it as failed, which helps maintain the integrity of your deployments.
In production, you need to be aware that hooks do not run during selective sync operations. This limitation can catch you off guard if you're expecting certain preconditions to be met. Additionally, the default hook delete policy is set to delete hooks before new ones are created, which you might want to adjust based on your requirements. Version 2.10 introduced these features, so ensure your Argo CD installation is up to date to utilize them effectively.
Key takeaways
- →Leverage PreSync hooks for critical tasks like database migrations before deployment.
- →Utilize Sync hooks to apply manifests only after successful PreSync execution.
- →Implement PostSync hooks for follow-up actions, ensuring they only run after a successful deployment.
- →Control resource application order using the argocd.argoproj.io/sync-wave annotation.
- →Remember that hooks do not execute during selective sync operations.
Why it matters
In production, managing the order of operations during deployments can prevent downtime and ensure that your applications are stable and reliable. Properly utilizing sync phases and waves can significantly reduce deployment errors.
Code examples
1apiVersion:batch/v1
2kind:Job
3metadata:
4 name: db-migrate
5 annotations:
6 argocd.argoproj.io/hook: PreSync
7 argocd.argoproj.io/hook-delete-policy: HookSucceeded
8 argocd.argoproj.io/sync-wave: '-1'
9spec:
10 ttlSecondsAfterFinished: 360
11 template:
12 spec:
13 containers:
14 - name: postgresql-client
15 image: 'my-postgres-data:11.5'
16 imagePullPolicy: Always
17 env:
18 - name: PGPASSWORD
19 value: admin
20 - name: POSTGRES_HOST
21 value: my_postgresql_db
22 command:
23 - psql
24 - '-h=my_postgresql_db'
25 - '-Upostgres'
26 - '-fpreload.sql'
27 restartPolicy: Never
28 backoffLimit: 11apiVersion:batch/v1
2kind:Job
3metadata:
4 generateName: app-slack-notification-
5 annotations:
6 argocd.argoproj.io/hook: PostSync
7 argocd.argoproj.io/hook-delete-policy: HookSucceeded
8spec:
9 template:
10 spec:
11 containers:
12 - name: slack-notification
13 image: curlimages/curl
14 command:
15 - curl
16 - '-X'
17 - POST
18 - '--data-urlencode'
19 - 'payload={"channel": "#somechannel", "username": "hello", "text":"App Sync succeeded", "icon_emoji": ":ghost:"}'
20 - 'https://hooks.slack.com/services/...'
21 restartPolicy: Never
22 backoffLimit: 2ingress-nginx:
controller:
admissionWebhooks:
annotations:
argocd.argoproj.io/hook: SkipWhen NOT to use this
The official docs don't call out specific anti-patterns here. Use your judgment based on your scale and requirements.
Want the complete reference?
Read official docsDeploy any app in seconds — no infrastructure config, no DevOps overhead. Instant deployments from GitHub, built-in databases, and automatic scaling.
Start deploying free →Securing Your Git Push Pipeline Against CVE-2026-3854
A critical remote code execution vulnerability has been identified in the git push pipeline, and it’s crucial to act fast. This vulnerability exploits how user-supplied git push options are handled, allowing attackers to inject malicious metadata. Here’s what you need to know to secure your pipeline.
Speed Up Your CI/CD with GitHub Actions Caching
Want to shave minutes off your CI/CD pipeline? Caching dependencies in GitHub Actions can drastically reduce build times. Learn how cache hits and misses work to optimize your workflows.
Mastering Deployments with GitHub Actions: What You Need to Know
Deploying with GitHub Actions can streamline your CI/CD pipeline, but it requires a solid understanding of environments and concurrency. Learn how to configure your workflows effectively to avoid common pitfalls.
Get the daily digest
One email. 5 articles. Every morning.
No spam. Unsubscribe anytime.