Prune policy decision framework — when to allow prune, when to forbid it

The decision framework for prune is per-Application, not cluster-wide. Three questions produce the policy:

1. Is the workload ephemeral? A workload whose resources are created and destroyed as part of normal operation is a candidate for prune. The lifecycle is short, the inventory is well-defined, and the deletion is intended.
2. Does the inventory contain shared resources? A resource consumed by another Application, an admission webhook, or a runtime outside the GitOps flow is a candidate for not pruning. The prune of one Application can delete a resource another depends on.
3. Does the inventory contain persistent state? A PVC, a database, or a stateful workload whose data outlives the Pod is a candidate for not pruning. The deletion is destructive; the data is not recoverable from a Git commit.

flowchart TD
    A["New Application"] --> B{"Workload ephemeral?"}
    B -->|yes| C{"Inventory shared?"}
    B -->|no| X["Prune forbidden"]
    C -->|no| D{"Persistent state?"}
    C -->|yes| X
    D -->|no| Y["Prune allowed"]
    D -->|yes| X

The left branch is the safer default. The right branch is the exception that requires an audit and a backup.

When to allow prune

Prune is allowed for workload classes whose lifecycle is short, whose inventory is well-bounded, and whose deletion is part of normal operation:

• Preview and feature-branch environments. A PR environment whose lifetime is the PR’s lifetime; the deletion is the closing of the PR.
• Stateless microservices. A Deployment whose ConfigMaps and Secrets are owned exclusively by the Application.
• CI runners and ephemeral workloads. A workload destroyed when the job ends.

For these classes, prune is enabled with:

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

The flag sets spec.syncPolicy.automated.prune: every automated sync deletes what the render no longer contains. Enable it only after the ownership audit confirms the inventory is exclusive to the Application.

When to forbid prune

Prune is forbidden for workload classes whose deletion is destructive or whose inventory crosses Application boundaries:

• Shared resources. A ConfigMap or Secret consumed by another Application, an admission webhook, or a runtime outside the GitOps flow.
• Persistent volumes and stateful workloads. A PVC whose data outlives the Pod; a database whose contents are not in Git. The deletion is irreversible.
• Cluster-scoped resources. A ClusterRole, a CustomResourceDefinition, or a namespace itself.

For these classes, prune is disabled with:

argocd app set "$APP_NAME" --sync-option Prune=false

The standing configuration is Prune=false. The per-resource annotation argocd.argoproj.io/sync-options: Prune=false is the alternative when the Application should be prune-enabled in general but a single resource must never be deleted.

The ownership audit

Before enabling prune, the team audits the inventory:

1. List every resource the Application’s render produces. argocd app manifests "$APP_NAME" is the source.
2. For each resource, identify every consumer outside the Application. A kubectl get with label selectors reveals them.
3. For each shared resource, decide whether the consumer’s lifecycle matches the Application’s. A consumer that should outlive is a reason to forbid prune.
4. For each persistent resource, identify the recovery path. A PVC with no Velero backup is a reason to forbid prune.

The audit is the prevention; the audit produces the policy.

The standing configuration

The per-Application standing configuration:

# Allow prune on a preview environment
argocd app set "$PREVIEW_APP" --auto-prune

# Forbid prune on a shared resource Application
argocd app set "$SHARED_APP" --sync-option Prune=false

# Allow prune on a stateless microservice
argocd app set "$MICROSERVICE_APP" --auto-prune

The configuration is auditable as a CLI command in the team’s runbook, or — better — a Git commit in an argocd-apps repository that declares the policy alongside the Application.

Production discipline

1. Prune is enabled per Application, never cluster-wide. The cluster-wide default is Prune=false.
2. The ownership audit is paired with the first prune-enabled sync. Audit, backup, sandbox, sync. The order matters.
3. Persistent state is never prune-eligible. PVCs and stateful workloads have lifecycles that exceed the Application’s; their deletion is not a Git operation.
4. The decision framework is documented per Application. A runbook records which Applications have prune enabled and why.

Cross-course references

• Git, CI/CD & GitOps for Infrastructure Engineers - Part LXXIX-04 (Prune and the blast radius) is the discipline this lesson formalises; Part LXXX-05 (Incident) is the failure mode the framework prevents.
• Kubernetes for Production Sysadmins - Part VII (Workloads) is the resource class; Part XXI is the namespace backup.

Quiz