docs: Add CSI volume snapshot documentation #17085

MusicDin · 2025-11-27T10:33:43Z

Adds CSI volume snapshot documentation:

New Helm chart values
Examples for VolumeSnapshotClass and VolumeSnapshot
Explanation of Kubernetes snapshot primitives

Related PR:

Implement volume snapshots lxd-csi-driver#98

Signed-off-by: Din Music <din.music@canonical.com>

Copilot

Pull request overview

This PR adds comprehensive documentation for CSI volume snapshot support in the LXD CSI driver, enabling users to create and manage snapshots of persistent volumes in Kubernetes.

Key changes:

Adds Helm chart configuration options for the CSI snapshotter and snapshot controller components
Provides VolumeSnapshotClass and VolumeSnapshot configuration examples with various use cases
Documents the Kubernetes snapshot primitives (VolumeSnapshotClass, VolumeSnapshot, VolumeSnapshotContent) and their role in the CSI architecture

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
`doc/reference/driver_csi.md`	Adds Helm chart values for CSI snapshotter sidecar and snapshot controller configuration
`doc/howto/storage_csi.md`	Adds how-to sections for VolumeSnapshotClass and VolumeSnapshot configuration with examples for default classes and retention policies
`doc/explanation/csi.md`	Updates capability table to mark volume snapshots as supported and documents snapshot-related Kubernetes primitives
`doc/.custom_wordlist.txt`	Adds CRDs, VolumeSnapshotClass, and VolumeSnapshotContent to the custom wordlist for spell checking

doc/reference/driver_csi.md

doc/explanation/csi.md

doc/howto/storage_csi.md

Signed-off-by: Din Music <din.music@canonical.com>

…t values Signed-off-by: Din Music <din.music@canonical.com>

…on examples Signed-off-by: Din Music <din.music@canonical.com>

Signed-off-by: Din Music <din.music@canonical.com>

tomponline · 2025-11-28T14:29:36Z

I'll wait for @minaelee review of this.

escabo · 2025-11-28T19:47:14Z

doc/howto/storage_csi.md

+metadata:
+  name: lxd-csi-snapshotclass
+driver: lxd.csi.canonical.com       # Name of the LXD CSI driver.
+deletionPolicy: Delete              # Possible values are "Retain" and "Delete" (default).


Deletion Policy is mandatory, otherwise you get a The VolumeSnapshotClass "lxd-csi-snapshotclass" is invalid: deletionPolicy: Required value

escabo · 2025-11-28T19:53:05Z

doc/reference/driver_csi.md

 `node.csiLivenessProbe.image.tag`                  | string | Chart release dependent                                 | CSI liveness probe image tag
 `node.csiLivenessProbe.image.pullPolicy`           | string | `IfNotPresent`                                          | CSI liveness probe image pull policy
 `node.csiLivenessProbe.resources`                  | object | `{}`                                                    | CSI liveness probe resource limits and requests
+`snapshotter.enabled`                              | bool   | `false`                                                 | Whether to enable support for volume snapshots. If enabled, CSI snapshot controller is deployed along with CSI driver itself.


Would be nice to include an example of how to install the helm chart with that option on

minaelee · 2025-11-28T20:20:56Z

doc/explanation/csi.md

+
+A [VolumeSnapshot &#8599;](https://kubernetes.io/docs/concepts/storage/volume-snapshots) represents a user request for a snapshot of a specific PVC.
+Each volume snapshot references a VolumeSnapshotClass and a source PVC.
+The snapshot controller invokes the CSI driver to create a snapshot from a source volume using the parameters defined in this class.


Suggested change

The snapshot controller invokes the CSI driver to create a snapshot from a source volume using the parameters defined in this class.

The snapshot controller invokes the CSI driver to create a snapshot from a source volume, using the parameters defined in this class.

minaelee · 2025-11-28T20:26:31Z

doc/howto/storage_csi.md

+```
+
+*This resource requires the VolumeSnapshot CRDs to be installed and the snapshot controller to be running.*
+*Using the Helm chart, this is enabled by setting `snapshotter.enabled` to `true`.*


What is "this resource"? Do you mean "Using a VolumeSnapshotClass" or something different?

minaelee · 2025-11-28T20:35:29Z

doc/howto/storage_csi.md

+```
+
+*This resource requires the VolumeSnapshot CRDs to be installed and the snapshot controller to be running.*
+*Using the Helm chart, this is enabled by setting `snapshotter.enabled` to `true`.*


Suggested change

*Using the Helm chart, this is enabled by setting `snapshotter.enabled` to `true`.*

In the {ref}`Helm chart <howto-storage-csi-deploy-helm>`, enable the snapshot controller by by setting `snapshotter.enabled` to `true`.

minaelee · 2025-11-28T20:37:13Z

doc/howto/storage_csi.md

+#### Default VolumeSnapshotClass
+
+The default VolumeSnapshotClass is used when `volumeSnapshotClassName` is not explicitly set in the VolumeSnapshot configuration.
+You can mark a Kubernetes VolumeSnapshotClass as the default by setting the `snapshot.storage.kubernetes.io/is-default-class: "true"` annotation.


Suggested change

You can mark a Kubernetes VolumeSnapshotClass as the default by setting the `snapshot.storage.kubernetes.io/is-default-class: "true"` annotation.

To mark a Kubernetes VolumeSnapshotClass as the default, set the `snapshot.storage.kubernetes.io/is-default-class: "true"` annotation.

In how-tos, prefer direct, imperative instructions over merely describing what is possible.

minaelee · 2025-11-28T20:38:28Z

doc/howto/storage_csi.md

+#### Prevent volume snapshot deletion
+
+By default, the volume snapshot is deleted when the corresponding VolumeSnapshot is removed.
+Setting the deletion policy to `Retain` prevents the CSI driver from deleting the underlying LXD volume snapshot, allowing for manual cleanup or data recovery later.


Suggested change

Setting the deletion policy to `Retain` prevents the CSI driver from deleting the underlying LXD volume snapshot, allowing for manual cleanup or data recovery later.

To prevent the CSI driver from deleting the underlying LXD volume, set the deletion policy to `Retain`. This allows for manual cleanup or data recovery later.

In how-tos, prefer direct, imperative instructions over merely describing what is possible.

minaelee · 2025-11-28T20:45:00Z

doc/howto/storage_csi.md

+### VolumeSnapshot configuration
+
+A VolumeSnapshot requests a snapshot of the volume bound to the referenced PVC.
+The fields `spec.volumeSnapshotClassName` and `spec.source.persistentVolumeClaimName` select the LXD CSI snapshot class to handle the snapshot and the PVC to snapshot, respectively.


Suggested change

The fields `spec.volumeSnapshotClassName` and `spec.source.persistentVolumeClaimName` select the LXD CSI snapshot class to handle the snapshot and the PVC to snapshot, respectively.

Set the fields `spec.volumeSnapshotClassName` and `spec.source.persistentVolumeClaimName` to the LXD CSI snapshot class to handle the snapshot and the PVC to snapshot, respectively.

Are the values lxd-csi-snapshotclass and lxd-csi-pvc in the code below meant to be examples, or preset options? Are there other options?

minaelee · 2025-11-28T20:54:23Z

doc/howto/storage_csi.md

+    persistentVolumeClaimName: lxd-csi-pvc
+```
+
+*This resource requires the VolumeSnapshot CRDs to be installed and the snapshot controller to be running.*


These lines 383 and 384 duplicate lines 335-336 above. We can use a substitution to copy it so that any updates can be made in a single place. This would mean adding the lines to doc/substitutions.yaml then using {{<substitution_name>}} within this page in both places.

```{include} ```

minaelee · 2025-11-28T20:54:51Z

doc/reference/driver_csi.md

 `node.csiLivenessProbe.image.tag`                  | string | Chart release dependent                                 | CSI liveness probe image tag
 `node.csiLivenessProbe.image.pullPolicy`           | string | `IfNotPresent`                                          | CSI liveness probe image pull policy
 `node.csiLivenessProbe.resources`                  | object | `{}`                                                    | CSI liveness probe resource limits and requests
+`snapshotter.enabled`                              | bool   | `false`                                                 | Whether to enable support for volume snapshots. If enabled, CSI snapshot controller is deployed along with CSI driver itself.


Suggested change

`snapshotter.enabled` | bool | `false` | Whether to enable support for volume snapshots. If enabled, CSI snapshot controller is deployed along with CSI driver itself.

`snapshotter.enabled` | bool | `false` | Whether to enable support for volume snapshots. If enabled, the CSI snapshot controller is deployed along with the CSI driver.

minaelee · 2025-11-28T20:55:58Z

doc/reference/driver_csi.md

 `node.csiLivenessProbe.image.pullPolicy`           | string | `IfNotPresent`                                          | CSI liveness probe image pull policy
 `node.csiLivenessProbe.resources`                  | object | `{}`                                                    | CSI liveness probe resource limits and requests
+`snapshotter.enabled`                              | bool   | `false`                                                 | Whether to enable support for volume snapshots. If enabled, CSI snapshot controller is deployed along with CSI driver itself.
+`snapshotter.installCRDs`                          | bool   | `true`                                                  | Whether to install required volume snapshot CRDs. The value is ignored if `snapshotter.enabled` is false. Should be disabled if CRDs are installed manually or by other CSI driver.


Suggested change

`snapshotter.installCRDs` | bool | `true` | Whether to install required volume snapshot CRDs. The value is ignored if `snapshotter.enabled` is false. Should be disabled if CRDs are installed manually or by other CSI driver.

`snapshotter.installCRDs` | bool | `true` | Whether to install required volume snapshot CRDs. The value is ignored if `snapshotter.enabled` is false. Should be disabled if CRDs are installed manually or by other CSI drivers.

"Should be disabled" as in the user should disable it, or it should be disabled automatically?

doc/explanation/csi: Mark volume snapshots as supported

9dffc07

Signed-off-by: Din Music <din.music@canonical.com>

github-actions bot added the Documentation Documentation needs updating label Nov 27, 2025

MusicDin requested a review from Copilot November 27, 2025 10:35

Copilot started reviewing on behalf of MusicDin November 27, 2025 10:35 View session

Copilot finished reviewing on behalf of MusicDin November 27, 2025 10:36

Copilot AI reviewed Nov 27, 2025

View reviewed changes

doc/reference/driver_csi.md Outdated Show resolved Hide resolved

doc/explanation/csi.md Outdated Show resolved Hide resolved

doc/howto/storage_csi.md Outdated Show resolved Hide resolved

MusicDin added 4 commits November 27, 2025 11:11

doc/explanation/csi: Describe volume snapshot primitives

0ca1771

Signed-off-by: Din Music <din.music@canonical.com>

doc/reference/csi: Document snapshot sidecar and controller Helm char…

a81c6c5

…t values Signed-off-by: Din Music <din.music@canonical.com>

doc/howto/csi: Add VolumeSnapshotClass and VolumeSnapshot configurati…

7825520

…on examples Signed-off-by: Din Music <din.music@canonical.com>

doc/custom_wordlist: Add new words for spellchecker

ad45f82

Signed-off-by: Din Music <din.music@canonical.com>

MusicDin force-pushed the docs/csi-snapshots branch from 5feaa30 to ad45f82 Compare November 27, 2025 11:13

MusicDin marked this pull request as ready for review November 27, 2025 11:27

MusicDin requested review from minaelee and tomponline November 27, 2025 11:28

escabo reviewed Nov 28, 2025

View reviewed changes

minaelee requested changes Nov 28, 2025

View reviewed changes

MusicDin marked this pull request as draft November 29, 2025 12:03

	The snapshot controller invokes the CSI driver to create a snapshot from a source volume using the parameters defined in this class.
	The snapshot controller invokes the CSI driver to create a snapshot from a source volume, using the parameters defined in this class.

	Using the Helm chart, this is enabled by setting `snapshotter.enabled` to `true`.
	In the {ref}`Helm chart <howto-storage-csi-deploy-helm>`, enable the snapshot controller by by setting `snapshotter.enabled` to `true`.

	You can mark a Kubernetes VolumeSnapshotClass as the default by setting the `snapshot.storage.kubernetes.io/is-default-class: "true"` annotation.
	To mark a Kubernetes VolumeSnapshotClass as the default, set the `snapshot.storage.kubernetes.io/is-default-class: "true"` annotation.

	Setting the deletion policy to `Retain` prevents the CSI driver from deleting the underlying LXD volume snapshot, allowing for manual cleanup or data recovery later.
	To prevent the CSI driver from deleting the underlying LXD volume, set the deletion policy to `Retain`. This allows for manual cleanup or data recovery later.

	The fields `spec.volumeSnapshotClassName` and `spec.source.persistentVolumeClaimName` select the LXD CSI snapshot class to handle the snapshot and the PVC to snapshot, respectively.
	Set the fields `spec.volumeSnapshotClassName` and `spec.source.persistentVolumeClaimName` to the LXD CSI snapshot class to handle the snapshot and the PVC to snapshot, respectively.

	`snapshotter.enabled` \| bool \| `false` \| Whether to enable support for volume snapshots. If enabled, CSI snapshot controller is deployed along with CSI driver itself.
	`snapshotter.enabled` \| bool \| `false` \| Whether to enable support for volume snapshots. If enabled, the CSI snapshot controller is deployed along with the CSI driver.

	`snapshotter.installCRDs` \| bool \| `true` \| Whether to install required volume snapshot CRDs. The value is ignored if `snapshotter.enabled` is false. Should be disabled if CRDs are installed manually or by other CSI driver.
	`snapshotter.installCRDs` \| bool \| `true` \| Whether to install required volume snapshot CRDs. The value is ignored if `snapshotter.enabled` is false. Should be disabled if CRDs are installed manually or by other CSI drivers.

docs: Add CSI volume snapshot documentation #17085

Are you sure you want to change the base?

docs: Add CSI volume snapshot documentation #17085

Conversation

MusicDin commented Nov 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tomponline commented Nov 28, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

MusicDin commented Nov 27, 2025 •

edited

Loading