Manual sync — the default, the audit, and the discipline of waiting

When an Application is created with no syncPolicy, the controller treats it as manual. The reconcile loop runs, the controller renders the manifests, computes the diff, updates status.sync.status to OutOfSync, and stops. Nothing is applied to the cluster until an operator runs argocd app sync NAME. Manual sync is the default because the controller has no opinion about whether a given diff is safe; the human does.

What manual sync means

In manual mode the controller is a detector, not an actor. It performs every step of reconciliation up to and including the apply, then halts:

flowchart LR
    A["Git commit"] --> R["Render manifests"]
    R --> D["Compare to live state"]
    D -->|"diff empty"| S["Synced"]
    D -->|"diff present"| O["OutOfSync"]
    O --> H["Wait for argocd app sync NAME"]
    H --> AP["Apply diff"]
    AP --> S

The operator sees the diff before the apply. The command:

argocd app diff payment-api

prints the same diff the controller computed. The operator reads it. If the diff is correct, the operator runs:

argocd app sync payment-api

The apply then proceeds, and status.sync.status returns to Synced.

The audit before the apply

A manual sync is not a delay; it is an audit step. The operator asks four questions before invoking argocd app sync:

1. Is the diff what the commit promised? The render and the live state are both visible in the diff; an unexpected resource is a render surprise.
2. Is the diff scoped to one concern? A diff that touches unrelated resources is a PR that bundled unrelated changes; the PR review should have caught it, but the sync is the last line of defence.
3. Are the resources safe to apply now? Some resources are destructive on apply (a ConfigMap overwrite can drop a custom resource definition’s last-applied configuration). The audit gates those.
4. Is there a rollback plan? A sync that cannot be rolled back is a sync that needs an explicit decision.

Why manual sync is still the right answer for some Applications

The argument for manual sync is not “humans are smarter than controllers”. The argument is that the cost of an unscheduled apply is higher than the cost of waiting for the operator. The cases where that is true:

• Workloads with side effects on apply. A CronJob whose first run deletes data is an apply that must be timed. Manual sync lets the team choose the moment.
• Workloads under active incident response. A controller applying a diff during an incident is a controller competing with the on-call engineer for the cluster’s state. Manual sync pauses the competition.
• Workloads whose diff is hard to review. A Helm chart with thirty templates produces a diff the operator cannot read in five minutes. Manual sync with a longer review window is correct; automated sync removes the window.

Manual sync in a busy fleet

The objection to manual sync at scale is real: a team with five hundred Applications cannot review every diff. The response is not “automate everything”; the response is to segment the fleet by risk. Manual sync for the workloads that justify it; automated sync for the workloads whose diff is well understood. The decision is per-Application, not per-cluster, and it changes over time as the chart matures.

Production discipline

1. Manual sync is the default for any Application whose diff has not been audited in its current shape. The first three syncs of a new chart are learning syncs.
2. The diff is the audit. An operator invoking argocd app sync without reading argocd app diff is signing a contract they have not read.
3. Manual sync is a per-Application decision. Clusters do not have a “manual fleet” or an “automated fleet”; Applications do.
4. Manual sync during an incident is a feature, not a delay. The controller waits; the on-call engineer owns the apply.

Cross-course references

• Git, CI/CD & GitOps for Infrastructure Engineers - Part LXXVII-04 (Sync policies and windows) introduces the policy this lesson deepens; Part LXXV (Drift) is the failure mode manual sync gates against.
• Kubernetes for Production Sysadmins - Part XVI (Operators and Controllers) covers the reconcile loop that manual sync interrupts at the apply step.

Quiz