Merge pull request #90971 from lpettyjo/OSDOCS-12099

OSDOCS-12099#Add CLI cmd for PVC usage

Author: lpettyjo

modules/storage-persistent-storage-pvc.adoc

@@ -113,3 +113,84 @@ spec:
 <1> Path to mount the volume inside the pod.
 <2> Name of the volume to mount. Do not mount to the container root, `/`, or any path that is the same in the host and the container. This can corrupt your host system if the container is sufficiently privileged, such as the host `/dev/pts` files. It is safe to mount the host by using `/host`.
 <3> Name of the PVC, that exists in the same namespace, to use.
+
+[id="pvc-cli-command-usage_{context}"]
+== Viewing PVC usage statistics
+
+You can view usage statistics for persistent volume claims (PVCs).
+
+:FeatureName: PVC usage statistics command
+include::snippets/technology-preview.adoc[leveloffset=+1]
+
+=== User permissions required to view PVC usage statistics
+To view PVC usage statistics, you must have the necessary privileges.
+
+To log on with the necessary privileges:
+
+* If you have admin privileges, log on as an admin.
+
+* If you do _not_ have admin privileges:
+
+. Create and add cluster roles to the user by running the following commands:
++
+[source,terminal]
+----
+$ oc create clusterrole routes-view --verb=get,list --resource=routes
+$ oc admin policy add-cluster-role-to-user routes-view <user-name> <1>
+$ oc admin policy add-cluster-role-to-user cluster-monitoring-view <user-name> <1>
+----
+<1> The user's name.
+
+=== Viewing PVC usage statistics
+
+* To view statistics across a cluster, run the following command:
++
+[source, terminal]
+----
+$ oc adm top pvc -A
+----
++
+.Example command output
+[source, terminal]
+----
+NAMESPACE     NAME         USAGE(%)
+namespace-1   data-etcd-1  3.82%
+namespace-1   data-etcd-0  3.81%
+namespace-1   data-etcd-2  3.81% 
+namespace-2   mypvc-fs-gp3 0.00%    
+default       mypvc-fs     98.36% 
+----
+
+* To view PVC usage statistics for a specified namespace, run the following command:
++
+[source, terminal]
+----
+$ oc adm top pvc -n <namespace-name> <1>
+----
+<1> Where `<namespace-name>` is the name of the specified namespace. 
++
+.Example command output
+[source, terminal]
+----
+NAMESPACE     NAME        USAGE(%) 
+namespace-1   data-etcd-2 3.81% <1>
+namespace-1   data-etcd-0 3.81%
+namespace-1   data-etcd-1 3.82%  
+----
+<1> In this example, the specified namespace is `namespace-1`.
+
+* To view usage statistics for a specified PVC and for a specified namespace, run the following command:
++
+[source, terminal]
+----
+$ oc adm top pvc <pvc-name> -n <namespace-name> <1>
+----
+<1> Where `<pvc-name>` is the name of specified PVC and `<namespace-name>` is the name of the specified namespace. 
++
+.Example command output
+[source, terminal]
+----
+NAMESPACE   NAME        USAGE(%)
+namespace-1 data-etcd-0 3.81% <1>
+----
+<1> In this example, the specified namespace is `namespace-1` and the specified PVC is `data-etcd-0`.