docs: add notes about deprecating VolumeSnapshot functions

VolumeSnapshot functions are using provider specific code to manage snapshots. Since CSI has better support for more providers, users should switch to CSI snapshotting functions instead.
kanisterio · Jun 7, 2024 · dbd2bfc · dbd2bfc
1 parent 0b7c1ff
commit dbd2bfc
Show file tree

Hide file tree

Showing 4 changed files with 47 additions and 0 deletions.
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -18,6 +18,7 @@ Please join the Kanister community to give feedback on the roadmap
 
 ### Prioritized (Doing):
 1. Fork block storage functions, deprecate unused Kanister code
+   a. Deprecate `VolumeSnapshot` functions using provider-specific snapshotting code
 1. Kopia.io Repository Controller with a CR to control the lifecycle of a Kopia Repository Server
 1. Replace [github.com/pkg/errors](http://github.com/pkg/errors) package with a supported fork = https://github.com/kanisterio/kanister/issues/1838
 1. Release notes

diff --git a/docs/functions.rst b/docs/functions.rst
@@ -721,6 +721,9 @@ associated with an application. It takes individual snapshot
 of each PVC which can be then restored later. It generates an
 output that contains the Snapshot info required for restoring PVCs.
 
+.. warning::
+   The *CreateVolumeSnapshot* will be deprecated soon. We recommend using :ref:`createcsisnapshot` instead. CSI snapshotting should have better support for underlying storage providers.
+
 .. note::
    Currently we only support PVC snapshots on AWS EBS. Support for more storage
    providers is coming soon!
@@ -774,6 +777,10 @@ WaitForSnapshotCompletion
 This function is used to wait for completion of snapshot operations
 initiated using the :ref:`createvolumesnapshot` function.
 
+.. warning::
+   The *WaitForSnapshotCompletion* will be deprecated soon together with :ref:`createvolumesnapshot`.
+   We recommend using :ref:`createcsisnapshot` instead, which will wait for completion by default.
+
 Arguments:
 
 .. csv-table::
@@ -790,6 +797,10 @@ This function is used to restore one or more PVCs of an application from the
 snapshots taken using the :ref:`createvolumesnapshot` function. It deletes old
 PVCs, if present and creates new PVCs from the snapshots taken earlier.
 
+.. warning::
+   The *CreateVolumeFromSnapshot* will be deprecated soon together with :ref:`createvolumesnapshot`. We recommend using CSI snapshotting functions (:ref:`createcsisnapshot` and :ref:`restorecsisnapshot`) instead.
+   CSI snapshotting should have better support for underlying storage providers.
+
 Arguments:
 
 .. csv-table::
@@ -836,6 +847,10 @@ DeleteVolumeSnapshot
 This function is used to delete snapshots of PVCs taken using the
 :ref:`createvolumesnapshot` function.
 
+.. warning::
+   The *DeleteVolumeSnapshot* will be deprecated soon together with :ref:`createvolumesnapshot`. We recommend using CSI snapshotting functions (:ref:`createcsisnapshot` and :ref:`deletecsisnapshot`) instead.
+   CSI snapshotting should have better support for underlying storage providers.
+
 Arguments:
 
 .. csv-table::
@@ -1330,6 +1345,7 @@ Example:
               resource: namespaces
               name: "{{ .Namespace.Name }}"
 
+.. _createcsisnapshot:
 
 CreateCSISnapshot
 -----------------
@@ -1386,6 +1402,7 @@ Example:
           namespace: "{{ .PVC.Namespace }}"
           snapshotClass: do-block-storage
 
+.. _createcsisnapshotstatic:
 
 CreateCSISnapshotStatic
 -----------------------
@@ -1441,6 +1458,7 @@ Example:
           driver: hostpath.csi.k8s.io
           handle: 7bdd0de3-aaeb-11e8-9aae-0242ac110002
 
+.. _restorecsisnapshot:
 
 RestoreCSISnapshot
 ------------------
@@ -1487,6 +1505,7 @@ Example:
           accessModes: ["ReadWriteOnce"]
           volumeMode: "Filesystem"
 
+.. _deletecsisnapshot:
 
 DeleteCSISnapshot
 -----------------
@@ -1522,6 +1541,7 @@ Example:
           name: "{{ .ArtifactsIn.snapshotInfo.KeyValue.name }}"
           namespace: "{{ .ArtifactsIn.snapshotInfo.KeyValue.namespace }}"
 
+.. _deletecsisnapshotcontent:
 
 DeleteCSISnapshotContent
 ------------------------

diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
@@ -63,3 +63,4 @@ webhook
 Kopia
 kopia
 hostname
+snapshotting
diff --git a/docs_new/functions.md b/docs_new/functions.md
@@ -625,6 +625,12 @@ with an application. It takes individual snapshot of each PVC which can
 be then restored later. It generates an output that contains the
 Snapshot info required for restoring PVCs.
 
+::: tip WARNING
+
+The *CreateVolumeSnapshot* will be deprecated soon. We recommend using [CreateCSISnapshot](#createcsisnapshot) instead.
+CSI snapshotting should have better support for underlying storage providers.
+:::
+
 ::: tip NOTE
 
 Currently we only support PVC snapshots on AWS EBS. Support for more
@@ -674,6 +680,12 @@ This function is used to wait for completion of snapshot operations
 initiated using the [CreateVolumeSnapshot](#createvolumesnapshot) function.
 function.
 
+::: tip WARNING
+
+   The *WaitForSnapshotCompletion* will be deprecated soon together with [CreateVolumeSnapshot](#createvolumesnapshot).
+   We recommend using [CreateCSISnapshot](#createcsisnapshot) instead, which will wait for completion by default.
+:::
+
 Arguments:
 
   | Argument  | Required | Type   | Description |
@@ -687,6 +699,12 @@ the snapshots taken using the `createvolumesnapshot`{.interpreted-text
 role="ref"} function. It deletes old PVCs, if present and creates new
 PVCs from the snapshots taken earlier.
 
+::: tip WARNING
+
+   The *CreateVolumeFromSnapshot* will be deprecated soon together with [CreateVolumeSnapshot](#createvolumesnapshot). We recommend using CSI snapshotting functions ([CreateCSISnapshot](#createcsisnapshot) and [RestoreCSISnapshot](#restorecsisnapshot)) instead.
+   CSI snapshotting should have better support for underlying storage providers.
+:::
+
 Arguments:
 
   | Argument  | Required | Type   | Description |
@@ -728,6 +746,13 @@ by the [CreateVolumeSnapshot](#createvolumesnapshot) function.
 This function is used to delete snapshots of PVCs taken using the
 [CreateVolumeSnapshot](#createvolumesnapshot) function.
 
+
+::: tip WARNING
+
+   The *DeleteVolumeSnapshot* will be deprecated soon together with [CreateVolumeSnapshot](#createvolumesnapshot). We recommend using CSI snapshotting functions ([CreateCSISnapshot](#createcsisnapshot) and [DeleteCSISnapshot](#deletecsisnapshot)) instead.
+   CSI snapshotting should have better support for underlying storage providers.
+:::
+
 Arguments:
 
   | Argument  | Required | Type   | Description |