Merge pull request #32673 from RaunakShah/3151-docs

Add docs for preventing volume mode conversion

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,51 @@ 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.
+
+## Converting the volume mode of a Snapshot {#convert-volume-mode}
+
+If the `VolumeSnapshots` API installed on your cluster supports the `sourceVolumeMode`
+field, then the API has the capability to prevent unauthorized users from converting 
+the mode of a volume.
+
+To check if your cluster has capability for this feature, run the following command:
+
+```yaml
+$ kubectl get crd volumesnapshotcontent -o yaml
+```
+
+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

content/en/docs/reference/labels-annotations-taints/_index.md

@@ -578,6 +578,20 @@ 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
+{{< glossary_tooltip text="PersistentVolumeClaim" term_id="persistent-volume-claim" >}} is being
+created from a VolumeSnapshot.
+
+Refer to [Converting the volume mode of a Snapshot](/docs/concepts/storage/volume-snapshots/#convert-volume-mode) 
+and the [Kubernetes CSI Developer Documentation](https://kubernetes-csi.github.io/docs/) for more information.
+
 ## Annotations used for audit
 
 <!-- sorted by annotation -->