From f89729d014d68a28d881676c36d293568fa52945 Mon Sep 17 00:00:00 2001
From: Raunak Pradip Shah <raunakshah13@gmail.com>
Date: Thu, 31 Mar 2022 10:22:04 +0530
Subject: [PATCH] Add docs for preventing volume mode conversion

---
 .../docs/concepts/storage/volume-snapshots.md | 32 +++++++++++++++++++
 .../labels-annotations-taints/_index.md       | 12 +++++++
 2 files changed, 44 insertions(+)

diff --git a/content/en/docs/concepts/storage/volume-snapshots.md b/content/en/docs/concepts/storage/volume-snapshots.md
index 8d9a5acb72..2490a1ae08 100644
--- a/content/en/docs/concepts/storage/volume-snapshots.md
+++ b/content/en/docs/concepts/storage/volume-snapshots.md
@@ -120,6 +120,7 @@ spec:
   driver: hostpath.csi.k8s.io
   source:
     volumeHandle: ee0cfb94-f8d4-11e9-b2d8-0242ac110002
+  sourceVolumeMode: Filesystem
   volumeSnapshotClassName: csi-hostpath-snapclass
   volumeSnapshotRef:
     name: new-snapshot-test
@@ -141,6 +142,7 @@ spec:
   driver: hostpath.csi.k8s.io
   source:
     snapshotHandle: 7bdd0de3-aaeb-11e8-9aae-0242ac110002
+  sourceVolumeMode: Filesystem
   volumeSnapshotRef:
     name: new-snapshot-test
     namespace: default
@@ -148,6 +150,36 @@ spec:
 
 `snapshotHandle` is the unique identifier of the volume snapshot created on the storage backend. This field is required for the pre-provisioned snapshots. It specifies the CSI snapshot id on the storage system that this `VolumeSnapshotContent` represents.
 
+`sourceVolumeMode` is the mode of the volume whose snapshot is taken. The value of the `sourceVolumeMode` field can be either `Filesystem` or `Block`. If the source volume mode is not specified, Kubernetes treats the snapshot as if the source volume's mode is unknown. Support for this field can only be enabled in VolumeSnapshot client v6.0.0 and higher. Visit the [VolumeSnapshot Release page](https://github.com/kubernetes-csi/external-snapshotter/releases) for more information.
+
+## Converting the volume mode of a Snapshot {#convert-volume-mode}
+
+This feature is only present for `VolumeSnapshotContents` created with client version `v6.0.0` onwards.
+The volume mode can be either `Filesystem` or `Block`. If not specified, it indicates the volume mode is unknown.
+If you want to allow users to create a `PersistentVolumeClaim` from an existing `VolumeSnapshot`, but with a 
+different volume mode than the source, the annotation `snapshot.storage.kubernetes.io/allowVolumeModeChange: "true"` 
+needs to be added to the `VolumeSnapshotContent` that corresponds to the `VolumeSnapshot`. For pre-provisioned snapshots,
+`Spec.SourceVolumeMode` needs to be populated by the cluster administrator.
+An example `VolumeSnapshotContent` resource with this feature enabled would look like:
+
+```yaml
+apiVersion: snapshot.storage.k8s.io/v1
+kind: VolumeSnapshotContent
+metadata:
+  name: new-snapshot-content-test
+  annotations:
+    - snapshot.storage.kubernetes.io/allowVolumeModeChange: "true"
+spec:
+  deletionPolicy: Delete
+  driver: hostpath.csi.k8s.io
+  source:
+    snapshotHandle: 7bdd0de3-aaeb-11e8-9aae-0242ac110002
+  sourceVolumeMode: Filesystem
+  volumeSnapshotRef:
+    name: new-snapshot-test
+    namespace: default
+```
+
 ## Provisioning Volumes from Snapshots
 
 You can provision a new volume, pre-populated with data from a snapshot, by using
diff --git a/content/en/docs/reference/labels-annotations-taints/_index.md b/content/en/docs/reference/labels-annotations-taints/_index.md
index bae7f3f14c..85877feb4d 100644
--- a/content/en/docs/reference/labels-annotations-taints/_index.md
+++ b/content/en/docs/reference/labels-annotations-taints/_index.md
@@ -508,6 +508,18 @@ you through the steps you follow to apply a seccomp profile to a Pod or to one o
 its containers. That tutorial covers the supported mechanism for configuring seccomp in Kubernetes,
 based on setting `securityContext` within the Pod's `.spec`.
 
+### snapshot.storage.kubernetes.io/allowVolumeModeChange
+
+Example: `snapshot.storage.kubernetes.io/allowVolumeModeChange: true`
+
+Used on: VolumeSnapshotContent
+
+Value can either be `true` or `false`.
+This determines whether a user can modify the mode of the source volume when a `PVC` is being created from a `VolumeSnapshot`.
+
+See [Converting the volume mode of a Snapshot](/docs/concepts/storage/volume-snapshots/#convert-volume-mode) for more information.
+
+
 ## Annotations used for audit
 
 <!-- sorted by annotation -->