All jobs

Add Sync Waves to an Argo CD Application So Databases Start Before Services

Yes. An agent reads the manifests Argo CD syncs, puts data stores, services and the front end into ordered sync waves, renders the result and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent clones the repository Argo CD watches and reads what one Application actually applies. In a repository like argoproj/argocd-example-apps, sock-shop/kustomization.yaml lists 29 files under base/: a Deployment and a Service for each of carts, catalogue, orders, payment, shipping, user, queue-master and front-end, the stores behind them (carts-db, orders-db and user-db on mongo, catalogue-db on weaveworksdemos/catalogue-db:0.3.0, session-db on redis:alpine), a rabbitmq:3.6.8-management Deployment with an exporter sidecar, and front-end-ingress.yaml. Not one of them carries an argocd.argoproj.io/sync-wave annotation, so every resource is in wave 0 and Argo CD orders them only by kind and name. The dependencies are in the files anyway: user-dep.yaml sets MONGO_HOST to user-db:27017, queue-master consumes RabbitMQ, and the Java services carry readiness probes with initialDelaySeconds: 180 and liveness probes at 300. The agent also reads apps/templates/applications.yaml, where the app-of-apps chart registers sock-shop with automated sync, prune: true and selfHeal: true, and the repository's own sync-waves/manifests.yaml, which shows the annotation form the maintainers use.

It then assigns waves from those dependencies rather than from a generic rule. Wave 0 keeps the five data stores, RabbitMQ and their Services, so names like user-db resolve before anything dials them. Wave 1 holds the seven backend Deployments and Services. Wave 2 holds front-end-dep.yaml and front-end-svc.yaml, and wave 3 holds the Ingress, which has nothing to route to until the front end is ready. Each annotation is written as argocd.argoproj.io/sync-wave: "1" in metadata.annotations of the base file itself, not through commonAnnotations in the kustomization, because that transformer stamps one value on every resource. A Service is given the same wave as its Deployment, so the pair moves together, and the exporter sidecar in rabbitmq-dep.yaml, which has no probe, is left alone and mentioned in the pull request.

The agent is explicit about what sync waves cost. Argo CD applies a wave, waits for it to be in sync and healthy, pauses the delay set by ARGOCD_SYNC_WAVE_DELAY (2 seconds by default), and only then starts the next wave. A Deployment is healthy once its rollout completes, so with the readiness probes in carts-dep.yaml and orders-dep.yaml waiting 180 seconds before the first check, wave 1 cannot clear in under three minutes, and a store that never becomes healthy in wave 0 blocks every later wave. The pull request says this plainly and leaves the probe values unchanged, because shortening them is a separate decision for the team that owns the Java services. Pruning runs the waves in reverse, so the Ingress goes first on a delete, which is what a reader expects.

Before opening anything it renders the application the way Argo CD will. It runs kustomize build sock-shop and checks with yq that every Deployment, Service and the Ingress now carries the expected wave, runs kubeconform -strict over the output so a mistyped annotation or an indentation slip cannot reach the cluster, and diffs the rendered output against main to prove that the only changes are annotations. It does not touch pre-post-sync/, whose kustomization still uses the deprecated bases: key, and it does not change apps/values.yaml; both are noted as follow-ups.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add Argo CD sync waves to the application in this repository so data stores come up before the services that use them, and the front end and ingress come last. Read the kustomization and every manifest it lists first, work out the real dependencies from environment variables, hostnames and probes, and write a wave table with a reason per resource. Annotate each base manifest directly with argocd.argoproj.io/sync-wave, keeping each Service in the same wave as its Deployment. Do not change images, probes or replica counts. Render the application with kustomize build, check every resource has its wave, validate the output with kubeconform, and open a pull request with the wave table, what each wave waits on, and the rendered diff.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request that changes only the base manifests the kustomization lists, one annotation each, with a description that holds the wave table: resource, wave and the file or variable that justified it, such as MONGO_HOST in user-dep.yaml for putting user after user-db. A second section lists what will make a sync slower, starting with the 180-second readiness delays on the Java services.

The run's record keeps the kustomize build output before and after, the yq check that counted annotations per wave, and the kubeconform -strict pass, so a reviewer can see that the rendered application differs from main only in annotations and that nothing in it fails schema validation.

Before merging, a reviewer confirms the wave order against how the services are really started in production, decides whether the team wants shorter readiness delays now that waves gate on them, and checks the Argo CD Application still has automated sync with prune: true, since pruning order now follows the waves in reverse.

Run it on every Argo CD application

A platform engineer hands this off from the terminal once per application: one POST /o/{org}/sessions with this body and the repository in resources. A team with many Applications in one repository sends one request per path, naming it in input, each with a request_id that is a UUID v5 of the repository and path so a retried request returns the run it already started. The key's webhook_url reports every run the key starts, with the pull request in result.

Each run reads its own Application's manifests and derives waves from them, so a Helm-based Application such as helm-guestbook gets its annotations in the chart templates, and a plain-YAML one like guestbook gets them in the files themselves. The agent never reuses another Application's table.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

Sync waves are only as good as the dependency analysis behind them, and the analysis needs every manifest open at once: the hostnames in environment variables, the ports, the probes and the kustomization that ties them together. The agent reads all of it in its own sandbox, renders the application with the same kustomize a cluster would use, and proves the diff is annotations only before a person spends time on review.

Running it on Rush means the proof travels with the change. The rendered output, the per-wave counts and the schema validation are in the run's record next to the pull request, and the same request can be sent for every Application a team owns, each with its own table, instead of one engineer working through them by hand on a laptop.

Frequently asked questions

Why annotate the base files instead of using a Kustomize transformer?

Because commonAnnotations applies one value to every resource in the kustomization, and waves need different values per resource. A JSON patch per file would work but doubles the places a reader has to look. Writing the annotation into each base manifest keeps the wave next to the resource it orders.

Will this slow down every sync?

Yes, by the time each wave takes to become healthy plus the two-second delay between waves. With readiness probes that wait 180 seconds, the services wave alone takes at least three minutes. The pull request lists the probes behind that so the team can decide whether to shorten them.

What happens if a data store in wave 0 never becomes healthy?

Argo CD does not move to the next wave, and the Application stays out of sync. That is the point of the ordering, but it is also a new way for a sync to stall, so the pull request names it and suggests an alert on Applications that stay in the Progressing state.

Does it also add PreSync or PostSync hooks?

No. Hooks are a phase, and waves order resources inside a phase. The repository's pre-post-sync/ example already shows a hook Job; if a schema migration needs to run before wave 0, that is a separate change the agent mentions but does not make.

Do I need an Argo CD server for the run?

No. The run renders the application with kustomize build and validates it with kubeconform, which need no cluster. The argocd app diff against your live cluster is for the reviewer, and the pull request says what it should show: annotations only.

More Argo CD jobs

More jobs like this: Hand off a long task

Keep reading