Merge branch 'kubernetes-csi:master' into snapshot-metadata-sidecar-alpha

Author: carlbraganza

.github/workflows/pull.yml

@@ -26,7 +26,7 @@ jobs:
 
       # Publish generated site as artifact. Unfortunately viewing it requires
       # downloading a .zip and uncompressing that (https://github.com/actions/upload-artifact/issues/14#issuecomment-620728238)
-      - uses: actions/upload-artifact@v2
+      - uses: actions/upload-artifact@v4
         with:
           name: html-docs
           path: docs

book/src/SUMMARY.md

@@ -26,6 +26,7 @@
         - [Secrets & Credentials](secrets-and-credentials.md)
             - [StorageClass Secrets](secrets-and-credentials-storage-class.md)
             - [VolumeSnapshotClass Secrets](secrets-and-credentials-volume-snapshot-class.md)
+            - [VolumeGroupSnapshotClass Secrets](secrets-and-credentials-volume-group-snapshot-class.md)
         - [Topology](topology.md)
         - [Raw Block Volume](raw-block.md)
         - [Skip Attach](skip-attach.md)

book/src/drivers.md

@@ -65,10 +65,11 @@ Name | CSI Driver Name | Compatible with CSI Version(s) | Description | Persiste
 [HPE](https://github.com/hpe-storage/csi-driver) | `csi.hpe.com` | v1.3 | A [multi-platform](https://scod.hpedev.io/csi_driver) Container Storage Interface (CSI) driver. Supports [HPE Alletra](https://hpe.com/storage/alletra), [Nimble Storage](https://hpe.com/storage/nimble), [Primera](https://hpe.com/storage/primera) and [3PAR](https://hpe.com/storage/3par) | Persistent and Ephemeral | Read/Write Multiple Pods | Yes | Raw Block, Snapshot, Expansion, Cloning
 [HPE ClusterStor Lustre CSI](https://github.com/HewlettPackard/lustre-csi-driver) | `lustre-csi.hpe.com` | v1.5 | A Container Storage Interface (CSI) Driver for HPE Cray ClusterStor Lustre Storage | Persistent | Read/Write Multiple Pods | No |
 [HPE Ezmeral (MapR)](https://github.com/mapr/mapr-csi) | `com.mapr.csi-kdf` | v1.3 | A Container Storage Interface (CSI) Driver for HPE Ezmeral Data Fabric | Persistent | Read/Write Multiple Pods | Yes | Raw Block, Snapshot, Expansion, Cloning
+[HPE GreenLake for File Storage CSI Driver](https://scod.hpedev.io/filex_csi_driver) | `filex.csi.hpe.com` | v1.2 | A Container Storage Interface (CSI) Driver for [HPE GreenLake for File Storage](https://www.hpe.com/us/en/hpe-greenlake-file-storage.html). | Persistent and Ephemeral | Read/Write Multiple Pods | Yes | Snapshot, Expansion, Cloning
 [Huawei Storage CSI](https://github.com/Huawei/eSDK_K8S_Plugin) | `csi.huawei.com` | v1.0, v1.1, v1.2 | A Container Storage Interface (CSI) Driver for FusionStorage, OceanStor 100D, OceanStor Pacific, OceanStor Dorado V3, OceanStor Dorado V6, OceanStor V3, OceanStor V5 | Persistent | Read/Write Multiple Pod | Yes | Snapshot, Expansion, Cloning
 [HwameiStor](https://github.com/hwameistor/hwameistor) | `lvm.hwameistor.io disk.hwameistor.io ` | v1.3 | A Container Storage Interface (CSI) Driver for Local Storage | Persistent | Read/Write Single Pod | Yes | Raw Block, Expansion
 [HyperV CSI](https://github.com/Zetanova/hyperv-csi-driver) | `eu.zetanova.csi.hyperv` | v1.0, v1.1 | A Container Storage Interface (CSI) driver to manage hyperv hosts | Persistent | Read/Write Multiple Pods | Yes |
-[IBM Block Storage](https://github.com/ibm/ibm-block-csi-driver) | `block.csi.ibm.com` | [v1.0, v1.5] | A Container Storage Interface (CSI) [Driver](https://www.ibm.com/docs/en/stg-block-csi-driver) for IBM Spectrum Virtualize Family, IBM FlashSystem A9000 and A9000R, IBM DS8000 Family 8.x and higher. | Persistent | Read/Write Single Pod | Yes | Raw Block, Snapshot, Expansion, Cloning, Topology
+[IBM Block Storage](https://github.com/ibm/ibm-block-csi-driver) | `block.csi.ibm.com` | [v1.0, v1.5] | A Container Storage Interface (CSI) [Driver](https://www.ibm.com/docs/en/stg-block-csi-driver) for IBM Spectrum Virtualize Family, IBM DS8000 Family 8.x and higher. | Persistent | Read/Write Multiple Pod | Yes | Raw Block, Snapshot, Expansion, Cloning, Topology
 [IBM Storage Scale](https://github.com/IBM/ibm-spectrum-scale-csi) | `spectrumscale.csi.ibm.com` | v1.5 | A Container Storage Interface (CSI) [Driver](https://www.ibm.com/docs/en/spectrum-scale-csi) for the IBM Storage Scale File System | Persistent | Read/Write Multiple Pod | Yes | Snapshot, Expansion, Cloning
 [IBM Cloud Block Storage VPC CSI Driver](https://github.com/kubernetes-sigs/ibm-vpc-block-csi-driver) | `vpc.block.csi.ibm.io` | v1.5 | A Container Storage Interface (CSI) [Driver](https://cloud.ibm.com/docs/containers?topic=containers-vpc-block) for IBM Cloud Kubernetes Service and Red Hat OpenShift on IBM Cloud | Persistent | Read/Write Single Pod | Yes | Raw Block, Expansion, Snapshot 
 [Infinidat](https://github.com/Infinidat/infinibox-csi-driver) | `infinibox-csi-driver` | v1.0, v1.8 | A Container Storage Interface (CSI) Driver for Infinidat [InfiniBox](https://infinidat.com/en/products-technology/infinibox) | Persistent | Read/Write Multiple Pods | Yes | Raw Block, Snapshot, Expansion, Cloning, Topology

book/src/group-snapshot-restore-feature.md

@@ -4,7 +4,8 @@
 
 Status | Min K8s Version | Max K8s Version | snapshot-controller Version | snapshot-validation-webhook Version | CSI external-snapshotter sidecar Version | external-provisioner Version
 --|--|--|--|--|--|--
-Alpha  | 1.27 | - | 7.0+ | 7.0+ | 7.0+ | 4.0+
+Alpha  | 1.27 | 1.32 | 7.0+ | 7.0+ | 7.0+ | 4.0+
+Beta  | 1.32 | - | 8.2+ | 8.2+ | 8.2+ | 5.1+
 
 **IMPORTANT**: The validation logic for VolumeGroupSnapshots and VolumeGroupSnapshotContents has been replaced by CEL validation rules. The validating webhook is now only being used for VolumeGroupSnapshotClasses to ensure that there's at most one default class per CSI Driver. The validation webhook is deprecated and will be removed in the next release
 
@@ -131,35 +132,34 @@ kubectl label pvc hpvc hpvc-2 app.kubernetes.io/name=postgresql
 
 Create a _VolumeGroupSnapshotClass_:
 ```
-kubectl create -f groupsnapshotclass-v1alpha1.yaml
+kubectl create -f groupsnapshotclass-v1beta1.yaml
 ```
 
 Create a _VolumeGroupSnapshot_:
 ```
-kubectl create -f groupsnapshot-v1alpha1.yaml
+kubectl create -f groupsnapshot-v1beta1.yaml
+```
+
+Once the _VolumeGroupSnapshot_ is ready, list the _VolumeSnapshot_ whose owner is the _VolumeGroupSnapshot_:
+
+```
+kubectl get volumegroupsnapshot
+NAME                     READYTOUSE   VOLUMEGROUPSNAPSHOTCLASS      VOLUMEGROUPSNAPSHOTCONTENT                              CREATIONTIME   AGE
+new-groupsnapshot-demo   true         csi-hostpath-groupsnapclass   groupsnapcontent-fb7a1c20-54d3-444c-a604-b3ff0f4a8801   4m57s          5m26s
 ```
 
-Once the _VolumeGroupSnapshot_ is ready, the `pvcVolumeSnapshotRefList` status field will contain the names of the generated _VolumeSnapshot_ objects:
 ```
-kubectl get volumegroupsnapshot new-groupsnapshot-demo  -o yaml | sed -n '/pvcVolumeSnapshotRefList/,$p'
+kubectl get volumesnapshot -o=jsonpath='{range .items[?(@.metadata.ownerReferences[0].name=="new-groupsnapshot-demo")]}{.metadata.name}{"\n"}{end}'
 
-  pvcVolumeSnapshotRefList:
-  - persistentVolumeClaimRef:
-      name: hpvc
-    volumeSnapshotRef:
-      name: snapshot-4bcc4a322a473abf32babe3df5779d14349542b1f0eb6f9dab0466a85c59cd42-2024-06-19-12.35.17
-  - persistentVolumeClaimRef:
-      name: hpvc-2
-    volumeSnapshotRef:
-      name: snapshot-62bd0be591e1e10c22d51748cd4a53c0ae8bf52fabb482bee7bc51f8ff9d9589-2024-06-19-12.35.17
-  readyToUse: true
+  snapshot-4dc1c53a29538b36e85003503a4bcac5dbde4cff59e81f1e3bb80b6c18c3fd03
+  snapshot-fbfe59eff570171765df664280910c3bf1a4d56e233a5364cd8cb0152a35965b
 ```
 
 Create a _PVC_ from a _VolumeSnapshot_ that is part of the group snapshot:
 ```
 # In the command below, the volume snapshot name should be chosen from
 # the ones listed in the output of the previous command
-sed 's/new-snapshot-demo-v1/snapshot-4bcc4a322a473abf32babe3df5779d14349542b1f0eb6f9dab0466a85c59cd42-2024-06-19-12.35.17/' restore.yaml | kubectl create -f -
+sed 's/new-snapshot-demo-v1/snapshot-4dc1c53a29538b36e85003503a4bcac5dbde4cff59e81f1e3bb80b6c18c3fd03/' restore.yaml | kubectl create -f -
 ```
 
 ## Examples

book/src/secrets-and-credentials-volume-group-snapshot-class.md

@@ -0,0 +1,83 @@
+# VolumeGroupSnapshotClass Secrets
+
+The CSI [external-snapshotter](external-snapshotter.md) sidecar container facilitates the handling of secrets for the following operations:
+* `CreateGroupSnapshotRequest`
+* `DeleteGroupSnapshotRequest`
+* `GetGroupSnapshotRequest`
+
+CSI `external-snapshotter` v8.1.0+ supports the following keys in `VolumeGroupSnapshotClass.parameters`:
+
+* `csi.storage.k8s.io/group-snapshotter-secret-name`
+* `csi.storage.k8s.io/group-snapshotter-secret-namespace`
+
+With CSI `external-snapshotter` v8.2.0 the following additional `VolumeGroupSnapshotClass.parameters` were added specifically for `GetGroupSnapshotRequest` operations:
+
+* `csi.storage.k8s.io/group-snapshotter-get-secret-name`
+* `csi.storage.k8s.io/group-snapshotter-get-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 `VolumeGroupSnapshotClass` object.
+
+## Operations
+Details for each secret supported by the external-snapshotter can be found below.
+
+### Create/Delete VolumeGroupSnapshot Secret
+
+CSI `external-snapshotter` v8.1.0+ looks for the following keys in `VolumeGroupSnapshotClass.parameters` for `CreateGroupSnapshotRequest` and `DeleteGroupSnapshotRequest` operations:
+
+* `csi.storage.k8s.io/group-snapshotter-secret-name`
+* `csi.storage.k8s.io/group-snapshotter-secret-namespace`
+
+The values of both of these parameters, together, refer to the name and namespace of a `Secret` object in the Kubernetes API.
+
+If specified, the CSI `external-snapshotter` will attempt to fetch the secret before creation and deletion.
+
+If the secret is retrieved successfully, the snapshotter passes it to the CSI driver in the `CreateGroupSnapshotRequest.secrets` or `DeleteGroupSnapshotRequest.secrets` field.
+
+If no such secret exists in the Kubernetes API, or the snapshotter is unable to fetch it, the create operation will fail.
+
+Note, however, that the delete operation will continue even if the secret is not found (because, for example, the entire namespace containing the secret was deleted). In this case, if the driver requires a secret for deletion, then the volume group snapshot and related snapshots need to be manually cleaned up.
+
+The values of these parameters may be "templates". The `external-snapshotter` will automatically resolve templates at volume group snapshot create time, as detailed below:
+
+* `csi.storage.k8s.io/group-snapshotter-secret-name`
+  * `${volumegroupsnapshotcontent.name}`
+    * Replaced with name of the `VolumeGroupSnapshotContent` object being created.
+  * `${volumegroupsnapshot.namespace}`
+    * Replaced with namespace of the `VolumeGroupSnapshot` object that triggered creation.
+  * `${volumegroupsnapshot.name}`
+    * Replaced with the name of the `VolumeGroupSnapshot` object that triggered creation.
+* `csi.storage.k8s.io/group-snapshotter-secret-namespace`
+  * `${volumegroupsnapshotcontent.name}`
+    * Replaced with name of the `VolumeGroupSnapshotContent` object being created.
+  * `${volumegroupsnapshot.namespace}`
+    * Replaced with namespace of the `VolumeGroupSnapshot` object that triggered creation.
+
+### Get VolumeGroupSnapshot Secret
+
+CSI `external-snapshotter` v8.2.0+ looks for the following keys in `VolumeGroupSnapshotClass.parameters` for `GetGroupSnapshotRequest` operations:
+
+* `csi.storage.k8s.io/group-snapshotter-get-secret-name`
+* `csi.storage.k8s.io/group-snapshotter-get-secret-namespace`
+
+The values of both of these parameters, together, refer to the name and namespace of a `Secret` object in the Kubernetes API.
+
+If specified, the CSI `external-snapshotter` will attempt to fetch the secret before creation and deletion.
+
+If the secret is retrieved successfully, the snapshotter passes it to the CSI driver in the `GetGroupSnapshotRequest.secrets` field.
+
+If no such secret exists in the Kubernetes API, or the snapshotter is unable to fetch it, the create operation will fail.
+
+The values of these parameters may be "templates". The `external-snapshotter` will automatically resolve templates at volume group snapshot create time, as detailed below:
+
+* `csi.storage.k8s.io/group-snapshotter-secret-name`
+  * `${volumegroupsnapshotcontent.name}`
+    * Replaced with name of the `VolumeGroupSnapshotContent` object being created.
+  * `${volumegroupsnapshot.namespace}`
+    * Replaced with namespace of the `VolumeGroupSnapshot` object that triggered creation.
+  * `${volumegroupsnapshot.name}`
+    * Replaced with the name of the `VolumeGroupSnapshot` object that triggered creation.
+* `csi.storage.k8s.io/group-snapshotter-secret-namespace`
+  * `${volumegroupsnapshotcontent.name}`
+    * Replaced with name of the `VolumeGroupSnapshotContent` object being created.
+  * `${volumegroupsnapshot.namespace}`
+    * Replaced with namespace of the `VolumeGroupSnapshot` object that triggered creation.