Q: What is `kubectl apply --prune`?
kubectl apply --prune makes kubectl apply delete live objects that were previously applied by kubectl but are no longer present in the manifests you pass, so the cluster converges to the files rather than only adding or changing.
Want to master this scenario in a live sandbox? KodeKloud's CKA & CKAD Hands-On Certification Track covers this exact problem with hands-on terminal drills.
🛠️ Production Runbook & Step-by-Step Resolution
Direct Answer: <strong>kubectl apply --prune</strong> makes <code>kubectl apply</code> delete live objects that were previously applied by kubectl but are no longer present in the manifests you pass, so the cluster converges to the files rather than only adding or changing things. It works by comparing against the <code>last-applied-configuration</code> annotation within a label selector or the <code>--all</code> scope. Interviewers ask it because it is powerful and dangerous: a wrong selector can delete workloads, and the feature has long been documented as alpha with an ApplySet-based rewrite in progress. A senior answer explains the mechanics, the guardrails and when to use GitOps pruning instead.
Mental model: how apply --prune decides what to delete
Plain apply never deletes, so removed files leave orphans; prune closes that gap with a bounded comparison.
- Without prune: deleting
service.yamlfrom your repo and re-runningkubectl apply -f .leaves the Service running because kubectl has no record that the file ever existed. - With prune: kubectl lists live objects of the allowed kinds that match your selector and carry the last-applied annotation, then deletes those not in the current input.
- Scope is mandatory: you must give
-l key=valueor--all, otherwise the command refuses, which limits blast radius to that label set. - Status: classic prune is still flagged alpha in kubectl docs. A newer ApplySet design (
--applyset, gated byKUBECTL_APPLYSET=true) exists since about 1.27 but is also alpha, so check your kubectl version. - Comparison:
kubectl delete -fremoves what is in files; prune removes what is not in the files, which is the reverse.
Hands-on: kubectl apply --prune with a label selector
Always label everything you manage, restrict kinds with an allowlist and look at a diff before deleting anything.
# 1) Preview: see which objects would be pruned
kubectl apply -f manifests/ -n prod \
-l app.kubernetes.io/part-of=my-app \
--prune \
--prune-allowlist=core/v1/Service \
--prune-allowlist=apps/v1/Deployment \
--prune-allowlist=core/v1/ConfigMap \
--dry-run=server
# Example output
# deployment.apps/my-app configured (server dry run)
# service/old-api pruned (server dry run)
# 2) Same command without --dry-run to execute
- Label the set: put one unique label such as
app.kubernetes.io/part-of: my-appon every manifest so the selector matches exactly your objects. - Allowlist kinds:
--prune-allowlist=group/version/kind(older name--prune-whitelist, deprecated) limits what may be deleted. Without it a built-in default list of namespaced kinds applies. - Preview first:
--dry-run=serverprintsprunedlines for would-be deletions without acting, andkubectl diffshows changes to existing objects. - Namespace: pass
-n prodexplicitly; pruning is evaluated within the namespace of the manifests.
Verify safely before you prune
Treat prune like a delete command, because it is one, and confirm the selector and the candidate list.
- Inventory live set:
kubectl get all,cm,ingress -n prod -l app.kubernetes.io/part-of=my-appshows exactly what the selector sees today. - Compare to files: every listed object that has no manifest in your directory is a deletion candidate; make sure that is intended.
- Check annotation: only objects with
kubectl.kubernetes.io/last-applied-configurationare prunable; objects created withkubectl createor by controllers are usually not. - Stage first: run the identical command in a non-production namespace or cluster before production, and require review of the dry-run output in CI.
Failure modes and edge cases
Most prune incidents come from broad selectors, incomplete manifests or mixed ownership of objects.
# Argo CD: prune in the Application sync policy
# spec.syncPolicy.automated: { prune: true, selfHeal: true }
# Protect one object from pruning with an annotation
kubectl annotate configmap my-config -n prod argocd.argoproj.io/sync-options=Prune=false
# Flux: Kustomization with prune enabled
# spec: { interval: 5m, path: ./apps/prod, prune: true, sourceRef: { kind: GitRepository, name: apps } }
- Partial input: applying a subset of files with prune deletes everything else under the label. Pass the whole directory every time, or never prune.
- Shared labels: if another team or Helm release uses the same label, you can delete their objects. Use a label unique to your release.
- Cluster-scoped and CRDs: pruning custom resources or cluster-scoped kinds requires allowing them explicitly; deleting a CRD cascades to all its custom resources, so keep CRDs out of the prune set.
- Stateful data: pruned PVCs may delete volumes depending on reclaim policy. Never allowlist
PersistentVolumeClaimcasually.
Production practice: prefer declarative controllers
In automated delivery, prune should be a feature of the deployment tool, with audit trails and approvals.
- Argo CD: enable
syncPolicy.automated.prune: trueor sync with prune, and usePruneLastand per-resourcePrune=falseannotations to protect critical objects. - Flux: set
prune: trueon the Kustomization; Flux tracks inventory itself rather than relying on selectors. - Helm:
helm upgradealready removes resources dropped from the chart, so you do not need kubectl prune for charts. - Guardrails: add RBAC limiting delete rights, namespace-scoped service accounts, and alerts for large delete counts in a single sync.
- kubectl apply --prune deletes live objects, within a label selector, that were applied earlier but are missing from the current manifests.
- I verify by running --dry-run=server first, listing the selector with kubectl get, and confirming the allowlist of kinds.
- I automate this with GitOps tools such as Argo CD or Flux that track inventory, and I avoid raw kubectl prune in production pipelines.
Senior hiring managers and bar raisers evaluate how you prioritize during outages. Avoid these common anti-patterns:
- Pruning with a partial set of files Anything under the selector that is not in the input is deleted, so a single-file apply can remove the rest of the application.
- Using a generic label like app=web The selector can match objects from other releases and delete them even though you never meant to manage them.
- Allowlisting PVCs, CRDs or Namespaces Deleting these can destroy data or cascade to every custom resource or object in the namespace.
- Treating prune as stable and complete The documented alpha status means behaviour and flags have changed; test on your exact kubectl version and read its help output.