From 8ccd0cc3b20bb65662c4a37d3437e5bbed54f788 Mon Sep 17 00:00:00 2001
From: Sunny Song <sunnycat@google.com>
Date: Thu, 12 Oct 2023 17:28:43 -0700
Subject: [PATCH] Add Documentation for VolumeAttributesClass KEP-3751

---
 .../storage/volume-attributes-classes.md      | 119 ++++++++++++++++++
 1 file changed, 119 insertions(+)
 create mode 100644 content/en/docs/concepts/storage/volume-attributes-classes.md

diff --git a/content/en/docs/concepts/storage/volume-attributes-classes.md b/content/en/docs/concepts/storage/volume-attributes-classes.md
new file mode 100644
index 0000000000..2972964050
--- /dev/null
+++ b/content/en/docs/concepts/storage/volume-attributes-classes.md
@@ -0,0 +1,119 @@
+---
+reviewers:
+- msau42
+- xing-yang
+title: Volume Attributes Classes
+content_type: concept
+weight: 40
+---
+<!-- overview -->
+
+This page assumes that you are familiar with [StorageClasses](/docs/concepts/storage/storage-classes/),
+[volumes](/docs/concepts/storage/volumes/) and [PersistentVolumes](/docs/concepts/storage/persistent-volumes/)
+in Kubernetes.
+
+<!-- body -->
+
+## Introduction
+
+A VolumeAttributesClass provides a way for administrators to describe the mutable
+"classes" of storage they offer. Different classes might map to different quality-of-service levels.
+Kubernetes itself is unopinionated about what these classes represent.
+
+
+## The VolumeAttributesClass Resource
+
+Each VolumeAttributesClass contains the `driverName` and `parameters`, which are used when a PersistentVolume belonging to the class needs to be dynamically provisioned or modified.
+
+The name of a VolumeAttributesClass object is significant and is how users can request a particular class.
+Administrators set the name and other parameters of a class when first creating VolumeAttributesClass objects.
+While the name of a VolumeAttributesClass object in a PersistentVolumeClaim is mutable, the parameters in an existing class are immutable.
+
+
+```yaml
+apiVersion: storage.k8s.io/v1alpha1
+kind: VolumeAttributesClass
+metadata:
+  name: silver
+driverName: pd.csi.storage.gke.io
+parameters:
+  provisioned-iops: "3000"
+  provisioned-throughput: "50" 
+```
+
+
+### Provisioner
+
+Each VolumeAttributes has a provisioner that determines what volume plugin is used for provisioning PVs. This field must be specified. 
+
+The feature support for VolumeAttributesClass is implemented in [kubernetes-csi/external-provisioner](https://github.com/kubernetes-csi/external-provisioner).
+
+You are not restricted to specifying the [kubernetes-csi/external-provisioner](https://github.com/kubernetes-csi/external-provisioner). You can also run and specify external provisioners,
+which are independent programs that follow a specification defined by Kubernetes.
+Authors of external provisioners have full discretion over where their code lives, how
+the provisioner is shipped, how it needs to be run, what volume plugin it uses (including Flex), etc. 
+
+
+### Resizer
+
+Each VolumeAttributes has a resizer that determines what volume plugin is used for modifying PVs. This field must be specified. 
+
+The modifying volume feature support for VolumeAttributesClass is implemented in [kubernetes-csi/external-resizer](https://github.com/kubernetes-csi/external-resizer).
+
+For example the existing PVC is using VolumeAttributesClass silver:
+
+
+```yaml
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: test-pv-claim
+spec:
+  …
+  volumeAttributesClassName: gold
+  …
+```
+
+
+A new VolumeAttributesClass gold is available in the cluster:
+
+
+```yaml
+apiVersion: storage.k8s.io/v1alpha1
+kind: VolumeAttributesClass
+metadata:
+  name: gold
+driverName: pd.csi.storage.gke.io
+parameters:
+  iops: "4000"
+  throughput: "60"
+```
+
+
+The end user can update the PVC with the new VolumeAttributesClass gold and apply:
+
+
+```yaml
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: test-pv-claim
+spec:
+  …
+  volumeAttributesClassName: gold
+  …
+```
+
+
+## Parameters
+
+Volume Classes have parameters that describe volumes belonging to them. Different parameters may be accepted
+depending on the provisioner or the resizer. For example, the value `4000`, for the parameter `iops`,
+and the parameter `throughput` are specific to GCE PD. 
+When a parameter is omitted, the default is used at volume provisioning.
+If a user apply the PVC with a different VolumeAttributesClass with omitted parameters, the default value of
+the parameters may be used depends on the CSI driver implementation.
+Please refer to the related CSI driver documentation for more details.
+
+There can be at most 512 parameters defined for a VolumeAttributesClass.
+The total length of the parameters object including its keys and values cannot exceed 256 KiB.
\ No newline at end of file