Skip to content

Add details about secrets for ControllerModifyVolume #631

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
+44 −1
Draft

Add details about secrets for ControllerModifyVolume #631

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions book/src/secrets-and-credentials-storage-class.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`:

Expand All @@ -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
Expand Down Expand Up @@ -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['<ANNOTATION_KEY>']}` (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.
3 changes: 2 additions & 1 deletion book/src/volume-attributes-class.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand All @@ -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.