What prune is — Git desired state deletes cluster actual

Prune is the controller’s contract that the cluster matches Git even when Git shrinks. When a manifest leaves the chart, the controller deletes the corresponding cluster resource. The deletion is committed to Git; the audit trail is clean; the change is reproducible from a single source of truth. The same property that makes prune an audit story - it deletes unconditionally on a diff that removes the resource - is what makes an unintended prune the largest blast radius in GitOps.

The prune contract

The controller reconciles desired state from Git with actual state in the cluster. A resource present in the previous apply inventory but absent from the new render is the prune set. With prune enabled, the controller deletes each resource in the prune set.

argocd app sync "$APP_NAME" --prune

The --prune flag is a per-sync override. The Application’s standing configuration is spec.syncPolicy.automated.prune, set with the --auto-prune flag on argocd app set:

argocd app set "$APP_NAME" --auto-prune

The flag means “prune resources the controller owns on every automated sync”. Individual resources opt out with the argocd.argoproj.io/sync-options: Prune=false annotation.

What prune deletes and what it does not

The boundary of prune is ownership. A resource is owned by a controller when the controller’s inventory tracks it. Argo CD’s inventory is the set of resources it has applied under the Application; Flux’s inventory is the set carrying the kustomize.toolkit.fluxcd.io/name label.

flowchart LR
    A["Git previous render"] --> C["Diff against new render"]
    B["Git new render"] --> C
    C --> D{"In previous, not in new?"}
    D -->|yes| E["Prune candidate"]
    D -->|no| F["No action"]
    E --> G{"Controller owns it?"}
    G -->|yes| H["DELETE from cluster"]
    G -->|no| I["Leave in cluster — orphan"]
    H --> J["Cluster matches Git"]
    F --> J
    I --> J

The right branch of the diagram is the orphan path: the resource stays because no controller claims it. The left branch is the prune path: the controller deletes a resource it owns. The audit trail records both; only the delete is a cluster-side effect.

The production consequence of a renamed manifest

A rename is the most dangerous operation in prune-enabled GitOps. The controller diffs the new render against the previous render, sees a ConfigMap/payment-config absent and a ConfigMap/payments-config present, and concludes: delete the old, create the new. The deletion is silent and fast. The team that wrote the rename discovers the outage when the consumer of the old ConfigMap fails.

Production discipline

1. Prune is enabled per Application, never cluster-wide. Automated prune (spec.syncPolicy.automated.prune) is an Application-level setting; defaulting it cluster-wide is the configuration error that turns a typo into a production-wide outage.
2. Every removal is a PR with a deletion-aware reviewer. A reviewer who knows prune is enabled reads the diff as a delete.
3. The first prune-enabled sync is paired with a namespace backup. Recovery from an unintended delete is the backup; prevention is the audit.
4. Prune=false is the escape hatch for what must not be deleted. Set it per-Application with argocd app set --sync-option Prune=false, or per-resource with the argocd.argoproj.io/sync-options: Prune=false annotation.

Cross-course references

• Git, CI/CD & GitOps for Infrastructure Engineers - Part LXXIX-04 (Prune and the blast radius) is the foundation this lesson deepens; Part LXXV (Drift) is the complementary failure mode where the cluster diverges from Git.
• Kubernetes for Production Sysadmins - Part VII (Workloads) is the resource class prune operates on; Part XVI (Operators and Controllers) covers the reconcile loop prune extends.

Quiz