kube-state-metrics/docs/metrics/storage/persistentvolumeclaim-metrics.md

PersistentVolumeClaim Metrics

Metric name	Metric type	Description	Unit (where applicable)	Labels/tags	Status
kube_persistentvolumeclaim_annotations	Gauge	Kubernetes annotations converted to Prometheus labels controlled via --metric-annotations-allowlist		persistentvolumeclaim=<persistentvolumeclaim-name> namespace=<persistentvolumeclaim-namespace> annotation_PERSISTENTVOLUMECLAIM_ANNOTATION=<PERSISTENTVOLUMECLAIM_ANNOATION>	EXPERIMENTAL
kube_persistentvolumeclaim_access_mode	Gauge			access_mode=<persistentvolumeclaim-access-mode> namespace=<persistentvolumeclaim-namespace> persistentvolumeclaim=<persistentvolumeclaim-name>	STABLE
kube_persistentvolumeclaim_info	Gauge			namespace=<persistentvolumeclaim-namespace> persistentvolumeclaim=<persistentvolumeclaim-name> storageclass=<persistentvolumeclaim-storageclassname> volumename=<volumename> volumemode=<volumemode>	STABLE
kube_persistentvolumeclaim_labels	Gauge	Kubernetes labels converted to Prometheus labels controlled via --metric-labels-allowlist		persistentvolumeclaim=<persistentvolumeclaim-name> namespace=<persistentvolumeclaim-namespace> label_PERSISTENTVOLUMECLAIM_LABEL=<PERSISTENTVOLUMECLAIM_LABEL>	STABLE
kube_persistentvolumeclaim_resource_requests_storage_bytes	Gauge			namespace=<persistentvolumeclaim-namespace> persistentvolumeclaim=<persistentvolumeclaim-name>	STABLE
kube_persistentvolumeclaim_status_condition	Gauge			namespace =<persistentvolumeclaim-namespace> persistentvolumeclaim=<persistentvolumeclaim-name> type=<persistentvolumeclaim-condition-type> status=<true\false\unknown>	EXPERIMENTAL
kube_persistentvolumeclaim_status_phase	Gauge			namespace=<persistentvolumeclaim-namespace> persistentvolumeclaim=<persistentvolumeclaim-name> phase=<Pending\Bound\Lost>	STABLE
kube_persistentvolumeclaim_created	Gauge	Unix creation timestamp	seconds	namespace=<persistentvolumeclaim-namespace> persistentvolumeclaim=<persistentvolumeclaim-name>	EXPERIMENTAL
kube_persistentvolumeclaim_deletion_timestamp	Gauge	Unix deletion timestamp	seconds	namespace=<persistentvolumeclaim-namespace> persistentvolumeclaim=<persistentvolumeclaim-name>	EXPERIMENTAL

Note:

• An empty string will be used if PVC has no storage class.

Useful metrics queries

How to retrieve non-standard PVC state

It is not straightforward to get the PVC states for certain cases like "Terminating" since it is not stored behind a field in the PersistentVolumeClaim.Status.

So to mimic the logic used by the kubectl command line, you will need to compose multiple metrics.

Here is an example of a Prometheus rule that can be used to alert on a PVC that has been in the Terminating state for more than 5m.

groups:
- name: PVC state
  rules:
  - alert: PVCBlockedInTerminatingState
    expr: kube_persistentvolumeclaim_deletion_timestamp * on(namespace, persistentvolumeclaim) group_left() (kube_persistentvolumeclaim_status_phase{phase="Bound"} == 1) > 0
    for: 5m
    labels:
      severity: warning
    annotations:
      summary: PVC {{$labels.namespace}}/{{$labels.persistentvolumeclaim}} blocked in Terminating state.