![\"One](\"/06dcd021349d0f4493326f5209826c13/sync-waves.svg\")
The first time a database migration ran at the same time as the pods that depended on it, I learned what “declarative” actually costs you. ArgoCD takes the manifests in your Git repo and drives the cluster toward them. That is the whole point of GitOps: Git holds the desired state, and a controller makes the cluster match it. But by default ArgoCD does not care what order the pieces arrive in. It computes the diff between Git and the cluster and applies everything at once. Your Deployment, your ConfigMap, and your migration Job all ship in the same breath.
Most of the time that is fine, because Kubernetes is eventually consistent and controllers retry. A pod that starts before its ConfigMap exists will crash-loop for a few seconds and then come up. But retrying cannot fix some orderings. Suppose the schema migration has not run yet. The new pods connect to an old database and fail their readiness probe, and if you are unlucky, the old pods are already gone. Now you have downtime that no retry loop can fix, because the thing that needed to happen first never happened.
\nThis post is for people running services on Kubernetes through ArgoCD who have hit an ordering problem and learned that “it usually works” is not the same as “it works.” I will cover the two mechanisms Argo gives you (sync waves and resource hooks), how they interact, and the failure modes that cost me the most time to diagnose.
\nAn ArgoCD sync has structure even before you add anything. Every sync runs in three phases: PreSync, then Sync, then PostSync. By default all of your resources live in the Sync phase, so the phases look like a single step. Inside a phase, resources are grouped into sync waves, and every resource sits in wave 0 unless you say otherwise.
So the default is one phase, one wave, everything together. You can change two things: which wave a resource is in, and which phase. Those are the only knobs, and both are just annotations.
\n
A sync wave is an integer annotation on a resource. This one puts a Deployment in wave 1:
apiVersion: apps/v1\nkind: Deployment\nmetadata:\n name: workflow-console\n annotations:\n argocd.argoproj.io/sync-wave: \"1\"Argo processes waves from the lowest number to the highest. Negative numbers are allowed and run before wave 0. That lets you slot work ahead of every resource without an annotation, without editing all the other manifests. Resources in the same wave are applied together; the ordering only exists between waves.
Here is what makes waves useful rather than cosmetic: Argo waits for every resource in a wave to become Healthy before it starts the next wave. Health is a real assessment, not “the API accepted the manifest.” A Deployment is Healthy when its pods are actually up and passing readiness. A Job is Healthy when it has completed. So take a rollout like this:
ConfigMap and Secret the app reads on bootDeploymentService and Ingress that route traffic to itThe config exists and is settled before any pod starts, and traffic is wired up only after the pods report Ready. That is exactly the order you would follow by hand, except now it is declarative and happens the same way every time.
\nOne detail will surprise you if you do not know it. Argo adds a deliberate delay between waves: two seconds by default, tunable through the ARGOCD_SYNC_WAVE_DELAY environment variable on the application controller. The delay gives other controllers a moment to react to what just landed. On a rollout with many waves it adds up, and it is the honest answer to “why did a sync that changed nothing still take twenty seconds?”
Waves order resources that are supposed to stay in the cluster. A migration is different. You want it to run at a specific point, succeed, and then get out of the way. That is what resource hooks are for. A hook annotation moves a resource into the PreSync or PostSync phase. Here, the migration Job runs as a PreSync hook and is cleaned up once it succeeds:
apiVersion: batch/v1\nkind: Job\nmetadata:\n name: db-migrate\n annotations:\n argocd.argoproj.io/hook: PreSync\n argocd.argoproj.io/hook-delete-policy: HookSucceeded\nspec:\n template:\n spec:\n restartPolicy: Never\n containers:\n - name: migrate\n image: registry.internal/workflow-console:{{ .Values.tag }}\n command: [\"alembic\", \"upgrade\", \"head\"]A PreSync hook runs, and must succeed, before the Sync phase begins. So the migration finishes while the old code is still serving traffic, and then the new pods roll out into a schema that already matches them. A PostSync hook runs after every Sync-phase resource is Healthy. That is where a smoke test belongs: the check that hits a real endpoint and fails the sync if the new version is not actually serving.
hook-delete-policy is the part people forget. Without it, every sync leaves another completed Job object lying around, until someone wonders why the namespace is full of db-migrate-xxxxx. HookSucceeded deletes the Job once it finishes cleanly. Just as usefully, it keeps the Job around when it fails, so you can read the logs.
Waves work inside hook phases too. A PreSync hook with sync-wave: "-1" runs before a PreSync hook with wave 0. That is how you order two setup steps that both need to finish before anything else starts.
A wave that never goes Healthy stalls the whole sync. This is the failure mode that reads as a hang. Say a wave-1 Deployment has a bad readiness probe, or an image that will not pull. It never becomes Healthy, so Argo never advances to wave 2, and the sync sits in Progressing until it times out. The application looks stuck for no visible reason. The reason is always in the specific resource Argo is waiting on. So the first move is to find which wave is in flight and look at that resource’s health, not the Application’s top-level status.
A hook with no clear success condition. ArgoCD decides a Job hook is done from the Job’s own completion status. If the migration container exits 0 before the migration has actually committed, Argo reads that as success and rolls the pods forward anyway. The hook is only as trustworthy as the exit code of the thing inside it. Test this deliberately: a migration that half-applies and returns zero makes for a much worse day than one that fails loudly.
Putting a Namespace or CRD in the wrong wave. A custom resource needs its CustomResourceDefinition (CRD) to exist before the API server will accept it. If both land in wave 0, the sync can fail on the first apply, because the CRD’s type is not registered yet. CRDs and namespaces belong in an early negative wave. This is the most common reason a fresh install fails on the first sync but works on the second, and it is easy to miss because the retry hides it.
Assuming waves give you cross-Application ordering. They do not. Waves order resources within a single Application. If your database and your app are separate Applications, a wave number in one says nothing about the other. That ordering problem needs a different tool, sync windows or an app-of-apps structure. Reaching for waves there quietly does nothing.
I over-used waves early on. After getting burned once, the instinct is to annotate everything, and you end up with a ten-wave rollout where three waves would do. Each extra wave pays the inter-wave delay, and each one is another place the sync can stall. Waves are for the orderings that genuinely cannot recover on their own:
\nFor everything else, let Kubernetes retry. The controllers are good at it, and a rollout with fewer ordering constraints has fewer ways to hang.
\nThe other thing I would tell my earlier self: a stalled wave is only mysterious if you cannot see it. The health status Argo is blocking on is also worth watching over time. Pushing it into a dashboard turns “the sync is stuck” into “wave 1 has been Progressing for four minutes on a failing readiness probe.” I wrote about building that kind of view in OpenSearch dashboards for workflow monitoring.
\nThis is how I roll out the WMCore and Unified operations services that schedule Monte Carlo production and data reconstruction for the CMS experiment across the Worldwide LHC Computing Grid. Moving those services onto Kubernetes and ArgoCD is what made safe updates and fast rollbacks possible in the first place. Sync waves are the reason a deploy that touches config, a schema, and a service comes up in an order I can reason about, instead of one I have to hope for. GitOps guarantees that the cluster matches Git. Sync waves and hooks let you also decide the order it gets there.
\nDiagram by M. Hassan Ahmed, made for this post.
","frontmatter":{"title":"ArgoCD Sync Waves: Ordering a Kubernetes Rollout","date":"2026-07-03T00:00:00.000Z","description":"ArgoCD applies your whole app at once, so a migration races the pods that need it. How sync waves and hooks order a Kubernetes rollout, and where they stall.","thumbnail":{"childImageSharp":{"fluid":{"base64":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAALCAIAAADwazoUAAAACXBIWXMAAAsSAAALEgHS3X78AAABvElEQVQoz4VRbW/TMBDON5bEr01iO05jJ06ctHlrt45uHUPakBAwBOL//xquRdM+IIT06HT33HN+znbAzemM8p7o92b47K+/N7tvENv9i1u+9oef3eFHNX0Zjr9y/0SLIyhfR05BRHVIFE3tSja1vx53H4b5oR/vttOpH+628wmYpr9dbj7qamKyxUn9DuuQFjEtApS2RGy5nlk+Yulj5ZBqYlHH0iHdIojyzETSceXyoilKJ1W1EjbiNsBiZMUhtScs96Qccd0i26KqxbWnmwGScwmou7x2rVkv3vS1WWsT0TLAaZOtJ2lmnm9iZrjqlF2gzMoJr2phZlFCdwE+5hVTG2EXUOLERbA2FX3p77vds6wPVHTC7v3y5MZH3dzyfGv6h3Z5roZHaXfQVfVNt/+UN0ci+ojoIGKGqQHOjrmhiUVsHXGH5YyynskOFCHJQ6xx1nG9oFUD7xSRHPjLMLc4dWmxjRMfr1oAVTNTU0iKGKSJhxchcoqYvcKapM5VjgsPBvBHQYjlFQCJEKuLj74kCuK5RXK4FywV/hFgmWQGzEMM65yH1SvkX7iQKHvLsbpCb8oAPP8H+a/Wb3tdQtPhRG8pAAAAAElFTkSuQmCC","aspectRatio":1.899441340782123,"src":"/static/072a9d5ad2239659e3f54544e74b3960/40a76/hero.png","srcSet":"/static/072a9d5ad2239659e3f54544e74b3960/c972b/hero.png 340w,\n/static/072a9d5ad2239659e3f54544e74b3960/27625/hero.png 680w,\n/static/072a9d5ad2239659e3f54544e74b3960/40a76/hero.png 1360w,\n/static/072a9d5ad2239659e3f54544e74b3960/ed396/hero.png 2000w","sizes":"(max-width: 1360px) 100vw, 1360px"}}}}}},"pageContext":{"slug":"/2026-07-03-argocd-sync-waves-ordering-rollout/","previous":"blog/2026-06-29-incremental-rag-indexing/","next":"blog/2026-07-02-hybrid-search-rag-bm25-vectors/"}},"staticQueryHashes":["32046230"]}