StatefulSet PVC retention: separate scale-down from deletion

Last updated: 1 Oct 20266 min read

tutorial

A StatefulSet can define separate claim-retention behavior when the set is deleted and when it scales down. The default Retain behavior preserves claims created from volume claim templates; choosing Delete for either transition makes those claims eligible for deletion under that event. Claim deletion then interacts with the bound PV's reclaim policy, so a Pod count change can lead to a storage-asset consequence far beyond scheduling.

Operational decision

A three-replica receipt index is temporarily scaled to two replicas. Before changing the count, map each ordinal to its claim, volume ID, data generation, and restore point. In a test cluster with the required feature support, use the fragment below to retain claims during both scale-down and set deletion. Scale from three to two and confirm the third claim remains and is not mounted by another Pod. Scale back to three and verify that the ordinal recovers its expected data, not a newly empty volume. Then test a deliberate Delete policy in a disposable set and observe both the PVC deletion and the PV reclaim behavior. If the database rebalances or discards shards on scale-down, coordinate that application operation before touching replica count. A retained claim consumes storage and may hold a zone constraint, but it preserves a fast path back only if the data format remains compatible.

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: receipt-index
  namespace: checkout
spec:
  persistentVolumeClaimRetentionPolicy:
    whenDeleted: Retain
    whenScaled: Retain

Cost and verification

Retaining an ordinal's claim costs storage even while its Pod is absent. Deleting it can lower cost but requires a recovery copy and may extend scale-up time. The fragment is the policy portion of a StatefulSet and needs the full selector, template, service name, and claim template before application. Measure orphaned ordinal claims, reuse success, data-generation match, and provider assets after deletion. Verify cluster version and feature availability rather than assuming every older control plane honors the field.

Common Mistakes

Do not equate scaling down a StatefulSet with safe data deletion.
Do not ignore the PV reclaim policy beneath a deleted PVC.
Do not assume a retained claim contains a compatible shard after application upgrades.

Connected lessons

Practice and check

devops

operations