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 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.