OSDOCS-12422#VolumeAttributesClass TP

modules/storage-persistent-storage-pvc-volumeattributesclass.adoc

@@ -0,0 +1,125 @@
+// Module included in the following assemblies:
+//
+// * storage/understanding-persistent-storage.adoc
+//
+
+:_mod-docs-content-type: CONCEPT 
+[id="storage-persistent-storage-pvc-volumeattributesclass_{context}"]
+= Volume Attributes Classes
+
+Volume Attributes Classes provide a way for administrators to describe "classes" of storage they offer. Different classes might correspond to different quality-of-service levels.
+
+:FeatureName: Volume Attributes Classes
+include::snippets/technology-preview.adoc[leveloffset=+1]
+
+Volume Attributes Classes in {product-title} is available only with AWS Elastic Block Storage (EBS) and Google Cloud Platform (GCP) persistent disk (PD) Container Storage Interface (CSI).
+
+You can apply a Volume Attributes Class to a persistent volume claim (PVC). If a new Volume Attributes Class becomes available in the cluster, a user can update the PVC with the new Volume Attributes Class if needed.
+
+Volume Attributes Classes have parameters that describe volumes belonging to them. If a parameter is omitted, the default is used at volume provisioning. If you apply the PVC with a different Volume Attributes Class with omitted parameters, the default value of the parameters might be used depending on the CSI driver implementation. For more information, see the related CSI driver documentation.
+
+== Limitations
+Volume Attributes Classes has the following limitations:
+
+* Volume modification using Volume Attributes Classes is only possible for hyperdisk-balanced disk types.
+
+* No more than 512 parameters can be defined for a `VolumeAttributesClass`. 
+
+* The total length of the parameter's object, including its keys and values, cannot exceed 256 KiB.
+
+* If you apply a Volume Attributes Class to a PVC, you can change the applied Volume Attributes Class for that PVC, but you cannot delete it from the PVC. To delete the Volume Attributes Class from the PVC, you must delete the PVC, and then re-create the PVC.
+
+* Volume Attributes Class parameters cannot be edited. If you need to change Volume Attributes Class parameters, create a new Volume Attributes Class with the desired parameters, and then apply it to a PVC.
+
+== Enabling Volume Attributes Classes 
+Volume Attributes Classes are not enabled by default.
+
+To enable Volume Attributes Classes, follow the procedure in section _Enabling {product-title} features using FeatureGates_.
+
+== Defining Volume Attributes Classes
+
+The following is an example Volume Attributes Class YAML file.
+
+.`VolumeAttributesClass` definition example
+[source,yaml]
+----
+apiVersion: storage.k8s.io/v1beta1
+kind: VolumeAttributesClass <1>
+metadata:
+  name: silver <2>
+driverName: ebs.csi.aws.com <3>
+parameters:
+  iops: "300"
+  throughput: "125" 
+  type: io2 <4>
+  ...
+----
+<1> Defines object as Volumes Attributes Classes
+<2> Name of the `VolumeAttributesClass`. In this example, it is "silver".
+<3> The provisioner that determines what volume plugin is used for provisioning persistent volumes (PVs). In this example, it is "ebs.csi.aws.com" for AWS EBS.
+<4> Disk type.
+
+== Applying a Volume Attributes Class to a PVC
+In addition to newly created PVCs, you can also update existing bound PVCs with a Volume Attributes Class.
+
+To apply a Volume Attributes Class to a PVC:
+
+* Set the PVC's `volumeAttributesClassName` parameter to the Volume Attributes Class's name:
++
+.PVC definition example specifying a Volume Attributes Class 
++
+[source,yaml]
+----
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: test-pv-claim
+spec:
+  …
+  volumeAttributesClassName: silver <1>
+----
+<1> Specifies using the Volume Attributes Class "silver" for this PVC.
+
+== Deleting Volume Attributes Classes
+You cannot delete a Volume Attributes Class while it is in use by PVCs. 
+
+If you try to delete a Volume Attributes Class while it is still being used by a PVC, the command does not complete until all resources that use the Volume Attributes Class are updated to not use it.
+
+To delete a Volume Attributes Class:
+
+. Search for PVCs that are using Volume Attributes Classes by running the following command:
++
+[source,terminal]
+----
+$ oc get pvc -A -o jsonpath='{range .items[?(@.spec.volumeAttributesClassName=="<vac-name>")]}{.metadata.name}{"\n"}{end}' <1>
+----
+<1> <vac-name> = Volume Attributes Class name
++
+.Sample command output
+[source, terminal]
+----
+$ mypvc
+----
+
+. Delete the Volume Attributes Class name from the PVC’s `volumeAttributesClassName` parameter:
++
+.PVC definition example specifying a Volume Attributes Class
+[source,yaml]
+----
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+name: mypvc
+spec:
+…
+volumeAttributesClassName: silver <1>
+----
+<1> Remove the name of the Volume Attributes Class. In this example, "silver".
+
+. Delete the Volume Attributes Class by running the following command:
++
+[source,terminal]
+----
+$ oc delete vac <vac-name> <1>
+----
+<1> Name of the Volume Attributes Class that you want to delete.

storage/understanding-persistent-storage.adoc

@@ -24,6 +24,16 @@ endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
 
 include::modules/storage-persistent-storage-pvc.adoc[leveloffset=+1]
 
+ifndef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
+include::modules/storage-persistent-storage-pvc-volumeattributesclass.adoc[leveloffset=+2]
+endif::[]
+
+ifndef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
+[role="_additional-resources"]
+.Additional resources
+* xref:../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling-features[Enabling {product-title} features using FeatureGates]
+endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
+
 include::modules/storage-persistent-storage-block-volume.adoc[leveloffset=+1]
 
 // As these volumes have transitioned to being tech preview per plugin,