Automated sync — the convenience and the controls it requires

Automated sync is the mode where the controller applies every diff it detects. The reconcile loop that in manual mode paused at argocd app sync now runs through to kubectl apply. The human is removed; the diff is the apply. The convenience is genuine, but it is conditional on controls that turn a raw automation into a safe automation.

What automated sync changes

The flag and what it does:

argocd app set payment-api \
  --sync-policy automated

The controller now applies any diff it detects on the next reconcile tick. The latency from git push to cluster state drops from “minutes to hours, waiting for an operator” to “the controller’s reconcile interval, typically three minutes”. For non-production fleets this is the operational answer to scale: five hundred Applications with manual sync is five hundred pending operator reviews; five hundred with automated sync is five hundred self-applying diffs.

flowchart LR
    G["git push"] --> R["Render on next tick"]
    R --> D["Diff detected"]
    D --> P{"syncPolicy"}
    P -->|automated| A["Apply immediately"]
    P -->|manual| W["Wait for operator"]
    A --> K["Cluster updated"]
    W --> K

The controls that must accompany automated sync

Automated sync is not safe by itself. The controls that must travel with it:

• Branch protection on the Git source. If anyone can push to the branch the controller watches, automated sync will apply any push. Branch protection (required reviewers, required status checks) is what gates the Git side.
• Drift detection alerts. Automated sync hides drift: the controller applies, the cluster matches, the alert that fired during manual mode goes silent. The team must keep the drift alert independent of the sync mode.
• Sync windows. A team that wants automated sync but only at 02:00 UTC combines the two: automated sync inside the window, manual sync outside it.
• Suspend-on-incident. When an incident opens, the team must be able to suspend automated sync for the affected Application so the on-call engineer’s manual changes are not reverted by the next reconcile.

argocd app set payment-api \
  --sync-policy automated \
  --self-heal

The --self-heal flag adds drift correction: any live-state divergence the controller did not cause is reverted on the next reconcile. Automated sync plus self-heal is the highest-trust pattern; it is also the one with the smallest margin for operator error.

Automated sync per environment

The decision to enable automated sync is not a fleet-wide flag. The pattern that survives production:

• Development. Automated sync, prune on, self-heal on. The cost of an out-of-cycle apply is low; the cost of waiting is high.
• Staging. Automated sync, prune on, self-heal on, sync window to match production. The staging cluster is a dress rehearsal; its policy should match the production policy.
• Production. Manual sync for state-changing workloads; automated sync with a sync window for non-state-changing workloads (configuration, observability, admission policies).

The environments have different blast radii; the policies must match.

The cost of an out-of-cycle apply

Automated sync commits the team to every diff that lands during the reconciliation window. A broken PR that lands at 14:00 UTC will be in production at 14:03 UTC, not at 02:00 UTC the next day. The cost of an out-of-cycle apply is bounded by:

• The size of the diff. Small diffs limit the blast radius.
• The reversibility of the apply. A Helm hook with a PreDelete can revert; a kubectl apply of a CRD cannot.
• The observability of the failure. A diff that fails to apply is louder than a diff that applies silently and breaks production.

The team that enables automated sync accepts these bounds as the price of low latency.

Production discipline

1. Automated sync requires branch protection. The Git side is the new gate; treat it as the production gate.
2. Automated sync is enabled per Application, not per cluster. Clusters have mixed risk; Applications express their own.
3. Automated sync is paired with suspend-on-incident. The on-call engineer must be able to pause reconciliation.
4. Automated sync is paired with a sync window when the workload is time-sensitive. Production changes happen at the window, not whenever the controller reconciles.

Cross-course references

• Git, CI/CD & GitOps for Infrastructure Engineers - Part LXXVII-04 (Sync policies and windows) is the source lesson; Part LXXVI-05 (Promotion models) is where automated sync sits in a promotion pipeline.
• Kubernetes for Production Sysadmins - Part XVI (Operators and Controllers) covers the reconcile loop that automated sync drives.

Quiz