Argo CD Sync Wave: Cross‑Namespace Ordering Guarantee Unresolved

Goal: Zero‑Downtime Migration with Sync Wave

When migrating a small application, the argocd.argoproj.io/sync-wave annotation is often used to orchestrate resource updates so that new components are deployed before old ones are terminated. The intended workflow is to assign lower wave numbers to resources that should appear first, wait until those resources report Healthy, and then apply resources in higher waves.

Current Understanding

Argo CD evaluates wave numbers per namespace during a sync. All resources with the same wave number in a given namespace are applied concurrently, and the controller blocks until every resource in that wave reports a healthy status before moving to the next wave. This behavior is documented in the Argo CD 2.12+ release notes and the official Sync Wave guide.

However, the implementation does not explicitly state whether the ordering is enforced across namespaces. In practice, a sync operation may include resources from multiple namespaces, each with identical wave numbers, and the controller appears to apply them in parallel without cross‑namespace sequencing. This leads to uncertainty when a migration spans several namespaces and the application requires a strict order of operations.

Key Constraint

There is no documented guarantee that wave ordering is respected when resources share the same wave number but reside in different namespaces. This missing constraint poses a risk for zero‑downtime migrations that rely on a global ordering of resource updates.

Unresolved Questions

• Is wave ordering enforced across namespaces, or does Argo CD treat each namespace independently during a sync?
• If cross‑namespace ordering is not guaranteed, what mechanisms (e.g., hooks, custom annotations) can be combined with Sync Wave to achieve a deterministic global order?
• Does the health assessment for resources in different namespaces interfere with wave progression if one namespace’s resources remain unhealthy while another’s become healthy?