From 12c0c8d1bb3e434a40bab0881056c6acd76b3b4f Mon Sep 17 00:00:00 2001 From: ArvindParekh Date: Fri, 20 Feb 2026 01:06:50 -0500 Subject: [PATCH 1/3] kep-5541: placeholder docs pr From 9f55548652c67e8c8bbf44049b28d7b02646a7e9 Mon Sep 17 00:00:00 2001 From: ArvindParekh Date: Sun, 29 Mar 2026 09:23:56 -0400 Subject: [PATCH 2/3] update: add feature gate reference --- .../PersistentVolumeClaimUnusedSinceTime.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 content/en/docs/reference/command-line-tools-reference/feature-gates/PersistentVolumeClaimUnusedSinceTime.md diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates/PersistentVolumeClaimUnusedSinceTime.md b/content/en/docs/reference/command-line-tools-reference/feature-gates/PersistentVolumeClaimUnusedSinceTime.md new file mode 100644 index 0000000000000..bb5f5f4ab4051 --- /dev/null +++ b/content/en/docs/reference/command-line-tools-reference/feature-gates/PersistentVolumeClaimUnusedSinceTime.md @@ -0,0 +1,16 @@ +--- +title: PersistentVolumeClaimUnusedSinceTime +content_type: feature_gate +_build: + list: never + render: false + +stages: + - stage: alpha + defaultValue: false + fromVersion: "1.36" +--- +When enabled, the PVC protection controller adds an `Unused` condition to +PersistentVolumeClaims that tracks whether the PVC is currently referenced by +any non-terminal Pod. The condition's `lastTransitionTime` records when the PVC +last transitioned between being in use and being unused. From dbfcc24e6bb28914f5e0d240dbf180af3fb5d572 Mon Sep 17 00:00:00 2001 From: ArvindParekh Date: Tue, 31 Mar 2026 19:58:45 -0400 Subject: [PATCH 3/3] update(docs): add docs outline --- .../concepts/storage/persistent-volumes.md | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/content/en/docs/concepts/storage/persistent-volumes.md b/content/en/docs/concepts/storage/persistent-volumes.md index 365fe05864726..4cb67b5fe53ed 100644 --- a/content/en/docs/concepts/storage/persistent-volumes.md +++ b/content/en/docs/concepts/storage/persistent-volumes.md @@ -937,6 +937,42 @@ there is no default causes PVCs without `storageClassName` created at that time to not have any default, but due to the retroactive default StorageClass assignment this way of changing defaults is safe. +### Unused PVC tracking + +{{< feature-state feature_gate_name="PersistentVolumeClaimUnusedSinceTime" >}} + +When enabled, the PVC protection controller adds an `Unused` +[condition](/docs/concepts/workloads/pods/pod-lifecycle/#pod-conditions) to each +PersistentVolumeClaim to indicate whether it is currently referenced by any +non-terminal Pod. + +The condition has two states: + +`Unused` with status `"True"` (reason `NoPodsUsingPVC`) +: No non-terminal Pod references this PVC. The `lastTransitionTime` records when + the PVC became unused. + +`Unused` with status `"False"` (reason `PodUsingPVC`) +: At least one non-terminal Pod currently references this PVC. The + `lastTransitionTime` records when the PVC started being used. + +A Pod is considered non-terminal if its phase is not `Succeeded` or `Failed`. +This means that a Pending Pod (even one that has not yet been scheduled) counts +as using the PVC. + +The `lastTransitionTime` of the `Unused` condition can be used by cluster +administrators, monitoring tools, and external controllers to identify PVCs that +have been unused for a long time. For example, to find all PVCs that have been +unused for more than 30 days, you could query for PVCs where the `Unused` +condition has `status: "True"` and `lastTransitionTime` is older than 30 days. + +{{< note >}} +The unused duration indicated by this condition may be shorter than the actual +unused time because of processing delays in the controller or because the +feature was enabled after the PVC was already unused. The condition is not +updated when a PVC has `deletionTimestamp` set (that is, PVCs that are being deleted). +{{< /note >}} + ## Claims As Volumes Pods access storage by using the claim as a volume. Claims must exist in the