Epic Goal*

Provide a CLI option to display filesystem usage of PVC. The user should be able to run a simple command to see PVC usage instead of constructing custom queries or navigating to the web console.

We already have options like `oc adm top pod` for example here, and it seems natural to add an extension like `oc adm top pvc` to show PVC's with a usage field.

The web console queries for capacity using `kubelet_volume_stats_used_bytes{persistentvolumeclaim='${name}',namespace='${namespace}'}`. The CLI could use that same metric, or it could follow PV -> PVC -> Pod -> Node relationships and query for node stats:

$ oc get pv pvc-1f937219-fe3e-4967-b33c-f05654ab4907
NAME                                       CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS   CLAIM             STORAGECLASS      VOLUMEATTRIBUTESCLASS   REASON   AGE
pvc-1f937219-fe3e-4967-b33c-f05654ab4907   1Gi        RWO            Delete           Bound    default/csi-pvc   csi-hostpath-sc   <unset> 

$ oc describe pvc csi-pvc | grep 'Used By'
Used By:       my-csi-app

$ oc describe pod/my-csi-app | grep '^Node:'
Node:             crc/192.168.126.11

$ oc get --raw /api/v1/nodes/crc/proxy/stats/summary | jq '.pods[] | select(.podRef.name == "my-csi-app") | .volume[] | select(.pvcRef) | select(.pvcRef.name == "csi-pvc")'
{
  "time": "2024-08-01T22:06:54Z",
  "availableBytes": 6309351424,
  "capacityBytes": 32680947712,
  "usedBytes": 26371596288,
  "inodesFree": 12332405,
  "inodes": 12483176,
  "inodesUsed": 150771,
  "name": "my-csi-volume",
  "pvcRef": {
    "name": "csi-pvc",
    "namespace": "default"
  }
}

 
Why is this important? (mandatory)

We have customer requests for this, and it's a common question (how to see used space of a PVC). It's available via the web console but we should also have a way to get this through the CLI too.

 
Scenarios (mandatory) 

Provide details for user scenarios including actions to be performed, platform specifications, and user personas.  

1. As an OCP project user, I want to see a list of all PVC's in my namespace and their space consumption so I know if my application has enough storage space.
2. As an OCP cluster admin, I want to see a list of all PVC's on the cluster and their space consumption so I know if any components are running out of storage space.

 
Dependencies (internal and external) (mandatory)

What items must be delivered by other teams/groups to enable delivery of this epic. 

Contributing Teams(and contacts) (mandatory) 

Our expectation is that teams would modify the list below to fit the epic. Some epics may not need all the default groups but what is included here should accurately reflect who will be involved in delivering the epic.

• Development - 
• Documentation -
• QE - 
• PX - 
• Others -

Acceptance Criteria (optional)

Provide some (testable) examples of how we will know if we have achieved the epic goal.  

Drawbacks or Risk (optional)

Reasons we should consider NOT doing this such as: limited audience for the feature, feature will be superseded by other work that is planned, resulting feature will introduce substantial administrative complexity or user confusion, etc.

Done - Checklist (mandatory)

The following points apply to all epics and are what the OpenShift team believes are the minimum set of criteria that epics should meet for us to consider them potentially shippable. We request that epic owners modify this list to reflect the work to be completed in order to produce something that is potentially shippable.

• CI Testing -  Basic e2e automationTests are merged and completing successfully
• Documentation - Content development is complete.
• QE - Test scenarios are written and executed successfully.
• Technical Enablement - Slides are complete (if requested by PLM)
• Engineering Stories Merged
• All associated work items with the Epic are closed
• Epic status should be “Release Pending”