From 4235d931300d29883545038c19ce74a68f3a8973 Mon Sep 17 00:00:00 2001 From: Niels de Vos Date: Fri, 14 Nov 2025 14:49:52 +0100 Subject: [PATCH] Add details about secrets for ControllerModifyVolume The secret references for ControllerModifyVolume have been added to the documentation of the StorageClass. There is also an explanation that the external-provisioner adds annotations on the PV so that the external-resizer can use them. --- .../secrets-and-credentials-storage-class.md | 42 +++++++++++++++++++ book/src/volume-attributes-class.md | 3 +- 2 files changed, 44 insertions(+), 1 deletion(-) diff --git a/book/src/secrets-and-credentials-storage-class.md b/book/src/secrets-and-credentials-storage-class.md index 7212aa79..927e94b2 100644 --- a/book/src/secrets-and-credentials-storage-class.md +++ b/book/src/secrets-and-credentials-storage-class.md @@ -8,6 +8,7 @@ The CSI [external-provisioner](external-provisioner.md) sidecar container facili * `ControllerExpandVolumeRequest` * `NodeStageVolumeRequest` * `NodePublishVolumeRequest` +* `ControllerModifyVolumeRequest` CSI `external-provisioner` v1.0.1+ supports the following keys in `StorageClass.parameters`: @@ -24,6 +25,10 @@ CSI `external-provisioner` v1.2.0+ adds support for the following keys in `Stora * `csi.storage.k8s.io/controller-expand-secret-name` * `csi.storage.k8s.io/controller-expand-secret-namespace` +CSI `external-provisioner` v6.1.0+ adds support for the following keys in `StorageClass.parameters`: +* `csi.storage.k8s.io/controller-modify-secret-name` +* `csi.storage.k8s.io/controller-modify-secret-namespace` + Cluster admins can populate the secret fields for the operations listed above with data from Kubernetes `Secret` objects by specifying these keys in the `StorageClass` object. ## Examples @@ -254,3 +259,40 @@ The values of these parameters may be "templates". The `external-provisioner` wi * Replaced with name of the `PersistentVolume` object being provisioned. * `${pvc.namespace}` * Replaced with namespace of the `PersistentVolumeClaim` object that triggered provisioning. + +### Controller Modify (VolumeAttributeClass) Secret + +The CSI `external-provisioner` (v6.1.0+) looks for the following keys in `StorageClass.parameters`: + +* `csi.storage.k8s.io/controller-modify-secret-name` +* `csi.storage.k8s.io/controller-modify-secret-namespace` + +The value of both parameters, together, refer to the name and namespace of the `Secret` object in the Kubernetes API. + +If specified, the CSI `external-provisioner` adds the following annotations to the `PersistentVolume` object to refer to this secret once provisioning is successful: + +* `volume.kubernetes.io/controller-modify-secret-name` +* `volume.kubernetes.io/controller-modify-secret-namespace` + +The `external-resizer` (v2.1.0+), attempts to fetch the secret referenced by the annotations on the `PersistentVolume`, if specified, before starting a volume resize (expand) operation. In case the `PersistentVolume` does not have the annotations, the secret referenced by the `CSIPersistentVolumeSource.ControllerExpandSecretRef` field is used. + +If no such secret exists in the Kubernetes API, or the `external-resizer` is unable to fetch it, the volume modification operation fails. + +If the secret is retrieved successfully, the `external-resizer` passes it to the CSI driver in the `ControllerModifyVolumeRequest.secrets` field. + +The values of these parameters may be "templates". The `external-provisioner` will automatically resolve templates at volume provision time, as detailed below: + +* `csi.storage.k8s.io/controller-modify-secret-name` + * `${pv.name}` + * Replaced with name of the `PersistentVolume` object being provisioned. + * `${pvc.namespace}` + * Replaced with namespace of the `PersistentVolumeClaim` object that triggered provisioning. + * `${pvc.name}` + * Replaced with the name of the `PersistentVolumeClaim` object that triggered provisioning. + * `${pvc.annotations['']}` (e.g. `${pvc.annotations['example.com/key']}`) + * Replaced with the value of the specified annotation from the `PersistentVolumeClaim` object that triggered provisioning +* `csi.storage.k8s.io/controller-modify-secret-namespace` + * `${pv.name}` + * Replaced with name of the `PersistentVolume` object being provisioned. + * `${pvc.namespace}` + * Replaced with namespace of the `PersistentVolumeClaim` object that triggered provisioning. diff --git a/book/src/volume-attributes-class.md b/book/src/volume-attributes-class.md index 3d5fa573..a4a92542 100644 --- a/book/src/volume-attributes-class.md +++ b/book/src/volume-attributes-class.md @@ -6,6 +6,7 @@ Status | Min K8s Version | Max K8s Version | external-provisioner | external-re -------|-----------------|-----------------|-----------------------|------------------------- Alpha | 1.29 | - | v4.0.0 | v1.10.0 Beta | 1.31 | - | v5.1.0 | v1.12.0 +GA | 1.34 | - | v6.0.0 | v2.0.0 ## Overview A `VolumeAttributesClass` is a cluster-scoped resource that can be used to control and change the settings of a `PersistentVolume`. @@ -22,4 +23,4 @@ To take advantage of `VolumeAttibutesClass` feature: * The Kubernetes administrator must create the `VolumeAttributesClass` with the relevant `parameters` for the `driverName` * The user can then patch the `PersistentVolumeClaim` under `spec.volumeAttributesClassName` to select or update the settings he needs for the volume. -> For more information about how to use the feature, visit the [Kubernetes blog](https://kubernetes.io/blog/2024/08/15/kubernetes-1-31-volume-attributes-class/) page. +> For more information about how to use the feature, visit the [Kubernetes documentation](https://kubernetes.io/docs/concepts/storage/volume-attributes-classes/) page.