AR
ArgoCD Deployment Strategies
Sync policies, progressive delivery, and rollback patterns
Details
Language / Topic
Argo CDCategory
Deployment
Rules
balanced
- Enable automated sync with self-heal for staging (`automated: { selfHeal: true, prune: true }`) but require manual sync approval for production Applications
- Use sync waves (`argocd.argoproj.io/sync-wave`) to order deployments: CRDs and namespaces first (wave -1), then operators (wave 0), then applications (wave 1+)
- Use PreSync hooks for database migrations and PostSync hooks for smoke tests — hook resources are Jobs that run at the specified phase and are cleaned up automatically
- Pair ArgoCD with Argo Rollouts for progressive delivery: canary deployments with automated metric analysis, blue-green with instant cutover, and automatic rollback on failure
- Roll back by reverting the Git commit — ArgoCD detects the change and syncs to the previous state; use `argocd app rollback` only for emergency overrides
- Enable automated sync with self-heal for non-production environments: `syncPolicy: { automated: { selfHeal: true, prune: true } }` — ArgoCD continuously corrects drift and removes orphaned resources
- For production, use manual sync with `syncPolicy: { automated: null }` — require explicit approval before deploying; use ArgoCD Notifications to alert when apps are out-of-sync
- Use sync waves (`argocd.argoproj.io/sync-wave` annotation) to enforce deployment ordering: namespaces and CRDs at wave -1, operators and controllers at wave 0, application workloads at wave 1+
- Use resource hooks for lifecycle automation: PreSync hooks for database migrations (Job), Sync hooks for sidecar injection, PostSync hooks for smoke tests, and SyncFail hooks for rollback notifications
- Set `argocd.argoproj.io/hook-delete-policy: HookSucceeded` on hook resources to automatically clean up completed Jobs — use `BeforeHookCreation` for Jobs that should be replaced on each sync
- Pair ArgoCD with Argo Rollouts for progressive delivery: replace Deployments with Rollout CRDs to get canary analysis, blue-green cutover, and automatic rollback based on Prometheus metrics
- Configure retry policies: `syncPolicy.retry: { limit: 5, backoff: { duration: "5s", factor: 2, maxDuration: "3m" } }` to handle transient failures during sync without manual intervention
- Enable `ServerSideApply=true` sync option for large Applications or when dealing with field ownership conflicts from controllers like HPA or VPA
- Use `spec.ignoreDifferences` to suppress known drift — e.g., HPA-managed replica counts, webhook-injected annotations, or controller-managed fields that ArgoCD should not overwrite
- Roll back by reverting the Git commit — ArgoCD detects the reverted state and syncs accordingly; the `argocd app rollback` command is an emergency override that creates drift from Git
- Use `Replace=true` sync option cautiously for immutable fields (Job specs, ConfigMap data used as volume mounts) — prefer `ServerSideApply` when possible to avoid full resource replacement
- Configure health checks: ensure Applications report accurate health by adding custom Lua health checks in argocd-cm for CRDs that ArgoCD does not natively understand