Controlling Resource Apply Order in Argo CD Using Sync Wave

Desired outcome

\n

You want Argo CD to apply Kubernetes manifests in a deterministic order so that dependencies (for example, a CustomResourceDefinition before the custom resources that use it) are always created first during a sync.

\n

Prerequisites

\n

\n
• A running Argo CD cluster (version 2.x or newer).
\n
• kubectl configured to manage the Argo CD namespace (typically argocd) with sufficient permissions to read and edit Application resources.
\n
• An existing Argo CD Application whose source repository you can edit (e.g., a Git repo containing the manifests you wish to order).
\n
• Basic familiarity with Kubernetes YAML manifests and Git workflow.
\n

\n

Procedure

\n

\n
1. Identify the manifests that need ordering. For each manifest, decide a relative integer weight: lower numbers are applied first. A common pattern is to assign negative numbers to CRDs, zero to core resources, and positive numbers to dependent workloads.
\n
2. Add or modify the annotation argocd.argoproj.io/sync-wave on each manifest. Example:\n

   # crd.yaml (applied first)\napiVersion: apiextensions.k8s.io/v1\nkind: CustomResourceDefinition\nmetadata:\n  name: myresources.example.com\n  annotations:\n    argocd.argoproj.io/sync-wave: \"-10\"\nspec:\n  group: example.com\n  versions:\n    - name: v1\n      served: true\n      storage: true\n      schema:\n        openAPIV3Schema:\n          type: object\n  scope: Namespaced\n  names:\n    plural: myresources\n    kind: MyResource\n

   \n

   # myresource.yaml (applied after the CRD)\napiVersion: example.com/v1\nkind: MyResource\nmetadata:\n  name: myresource-sample\n  annotations:\n    argocd.argoproj.io/sync-wave: \"0\"\nspec:\n  # …\n

   \n

   # deployment.yaml (applied last)\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: myapp\n  annotations:\n    argocd.argoproj.io/sync-wave: \"20\"\nspec:\n  replicas: 1\n  selector:\n    matchLabels:\n      app: myapp\n  template:\n    metadata:\n      labels:\n        app: myapp\n    spec:\n      containers:\n        - name: app\n          image: myapp:latest\n

   \n
\n
3. Commit the updated manifests to the Git repository that the Application points to.
\n
4. Argo CD will automatically detect the change and start a sync. You can also trigger a sync manually from the UI or CLI:\n

   # Run from your workstation where kubectl is configured\nkubectl -n argocd sync application my-app\n

   \n
\n

\n

Expected checks

\n

\n
• After the sync completes, verify the Application status shows Synced:\n

  kubectl get application my-app -n argocd -o yaml | grep sync.status\n

  \n
\n
• Inspect the ordered list of resources in the Argo CD UI: open the Application → Resources tab. Resources with lower sync‑wave numbers appear higher in the list.
\n
• For a specific resource, confirm the annotation is present and that no Failed events followed the sync:\n

  kubectl describe customresourcedefinition myresources.example.com -n \n

  \nLook for the line Annotations: argocd.argoproj.io/sync-wave: -10 and ensure the Events section ends with a Normal Applied event.\n
\n

\n

Recovery options (if sync fails)

\n

If an incorrect sync‑wave value causes a resource to be created before its dependency (e.g., a custom resource before its CRD), Argo CD will report a sync error.

\n

\n
1. Revert the problematic annotation to a safer value (often moving the resource to a higher wave number). Edit the manifest in Git, commit, and push.
\n
2. Trigger a re-sync:\n

   kubectl -n argocd sync application my-app\n

   \n
3. If the stuck resource cannot be deleted by Argo CD due to a dependency loop, you may need to manually remove it (with kubectl delete) and let Argo CD recreate it after the annotation is corrected. Exercise caution: manual deletion bypasses Argo CD’s reconciliation loop and should be followed by a immediate re‑sync.\n
\n

\n

Limitations and verification

\n

\n
• Sync Wave only influences ordering within a single Application. It does not affect the order between separate Applications or resources managed by external controllers (e.g., Operators).
\n
• Use small integer values (typically -100 to 100). Extremely large or non‑integer values can be ignored or cause unexpected behavior.
\n
• Avoid circular dependencies; if two resources reference each other, setting sync-wave will not resolve the deadlock and may cause the sync to hang.
\n
• Practical verification: after each sync, run\n

  kubectl get application my-app -n argocd -o yaml -o jsonpath='{.status.sync.status}'\n

  \n

  and confirm it returns Synced. Additionally, you can query the resource events as shown above to ensure no Failed events appear after the sync.\n

\n

\n