Reclaim policies (Retain, Delete) in Kubernetes - Commands & Configuration

Introduction

When you delete a Kubernetes PersistentVolumeClaim, the reclaim policy decides what happens to the actual storage. It can either keep the storage for manual cleanup or delete it automatically to free space.

When you want to keep data safe even after deleting the claim, for backup or manual recovery.

When you want storage to be cleaned up automatically to avoid leftover unused volumes.

When managing storage lifecycle in a shared cluster with multiple users.

When setting up persistent storage for stateful applications like databases.

When automating cleanup of storage resources in development or testing environments.

Config File - persistent-volume.yaml

persistent-volume.yaml

apiVersion: v1
kind: PersistentVolume
metadata:
  name: example-pv
spec:
  capacity:
    storage: 1Gi
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  hostPath:
    path: /mnt/data
---
apiVersion: v1
kind: PersistentVolume
metadata:
  name: example-pv-delete
spec:
  capacity:
    storage: 1Gi
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Delete
  hostPath:
    path: /mnt/data-delete

This file defines two PersistentVolumes (PVs). Each PV has a persistentVolumeReclaimPolicy key:

• Retain: Keeps the storage after the claim is deleted, so data is safe but manual cleanup is needed.
• Delete: Automatically deletes the storage when the claim is deleted, freeing space immediately.

The hostPath simulates local storage on the node for simplicity.

Commands

Create two PersistentVolumes with different reclaim policies: one retains storage, the other deletes it automatically.

Terminal

kubectl apply -f persistent-volume.yaml

Expected Output

persistentvolume/example-pv created

persistentvolume/example-pv-delete created

Check the status and reclaim policies of the created PersistentVolumes to confirm they are set correctly.

Terminal

kubectl get pv example-pv example-pv-delete -o wide

Expected Output

NAME               CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS      CLAIM   STORAGECLASS   REASON   AGE

example-pv         1Gi        RWO           Retain           Available           <none>                1m

example-pv-delete  1Gi        RWO           Delete           Available           <none>                1m

→

-o wide - Shows detailed information including reclaim policy

Delete the PersistentVolumeClaim to trigger the reclaim policy on the associated PersistentVolume.

Terminal

kubectl delete pvc example-pvc

Expected Output

persistentvolumeclaim "example-pvc" deleted

Check the PersistentVolumes after deleting the claim to see if storage is retained or deleted based on the reclaim policy.

Terminal

kubectl get pv example-pv example-pv-delete

Expected Output

NAME               CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS      CLAIM

example-pv         1Gi        RWO           Retain           Released   

example-pv-delete  1Gi        RWO           Delete           Available  

Key Concept

If you remember nothing else from this pattern, remember: the reclaim policy controls whether storage is kept or deleted when the claim is removed.

Common Mistakes

Setting reclaim policy to Delete but expecting data to remain after claim deletion.

Delete policy removes the storage automatically, so data is lost.

Use Retain policy if you want to keep data after deleting the claim.

Not checking the reclaim policy before deleting PersistentVolumeClaims.

You might accidentally delete important data or leave unused storage behind.

Always verify reclaim policy with 'kubectl get pv' before deleting claims.

Assuming reclaim policy applies to PersistentVolumeClaims instead of PersistentVolumes.

Reclaim policy is set on PersistentVolumes, not claims, so setting it on claims has no effect.

Set reclaim policy in the PersistentVolume spec.

Summary

Create PersistentVolumes with reclaim policies Retain or Delete to control storage cleanup.

Use 'kubectl get pv' to verify reclaim policies and volume status.

Deleting a PersistentVolumeClaim triggers the reclaim policy on its PersistentVolume.