You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{product-title} provides a snapshot controller that is deployed into the control plane. In addition, your CSI driver vendor provides the CSI snapshot sidecar as a helper container that is installed during the CSI driver installation.
9
+
[role="_abstract"]
10
+
Container Storage Interface (CSI) snapshots require two components: a controller deployed by {product-title} to the control plane, and a vendor-provided sidecar with the CSI driver. The controller manages `VolumeSnapshot` bindings while the sidecar triggers create and delete operations.
10
11
11
12
The CSI snapshot controller and sidecar provide volume snapshotting through the {product-title} API. These external components run in the cluster.
12
13
13
14
The external controller is deployed by the CSI Snapshot Controller Operator.
14
15
15
-
== External controller
16
-
The CSI snapshot controller binds `VolumeSnapshot` and `VolumeSnapshotContent` objects. The controller manages dynamic provisioning by creating and deleting `VolumeSnapshotContent` objects.
16
+
External controller:: The CSI snapshot controller binds `VolumeSnapshot` and `VolumeSnapshotContent` objects. The controller manages dynamic provisioning by creating and deleting `VolumeSnapshotContent` objects.
17
17
18
-
== External sidecar
19
-
Your CSI driver vendor provides the `csi-external-snapshotter` sidecar. This is a separate helper container that is deployed with the CSI driver. The sidecar manages snapshots by triggering `CreateSnapshot` and `DeleteSnapshot` operations. Follow the installation instructions provided by your vendor.
18
+
External sidecar:: Your CSI driver vendor provides the `csi-external-snapshotter` sidecar. This is a separate helper container that is deployed with the CSI driver. The sidecar manages snapshots by triggering `CreateSnapshot` and `DeleteSnapshot` operations. Follow the installation instructions provided by your vendor.
To make a pre-existing storage snapshot available in {product-title}, manually create a volume snapshot that references the existing snapshot content by name.
11
+
12
+
.Prerequisites
13
+
* Logged in to a running {product-title} cluster.
14
+
* A PVC created using a CSI driver that supports `VolumeSnapshot` objects.
15
+
* A storage class to provision the storage back end.
16
+
* No pods are using the persistent volume claim (PVC) that you want to take a snapshot of.
17
+
+
18
+
[WARNING]
19
+
====
20
+
Creating a volume snapshot of a PVC that is in use by a pod can cause unwritten data and cached data to be excluded from the snapshot. To ensure that all data is written to the disk, delete the pod that is using the PVC before creating the snapshot.
21
+
====
22
+
23
+
.Procedure
24
+
. Create a file with the `VolumeSnapshotClass` object described by the following YAML:
25
+
+
26
+
.Example volumesnapshotclass.yaml
27
+
[source,yaml]
28
+
----
29
+
apiVersion: snapshot.storage.k8s.io/v1
30
+
kind: VolumeSnapshotClass
31
+
metadata:
32
+
name: csi-hostpath-snap
33
+
driver: hostpath.csi.k8s.io
34
+
deletionPolicy: Delete
35
+
----
36
+
+
37
+
`driver` is the name of the CSI driver that is used to create snapshots of this `VolumeSnapshotClass` object. The name must be the same as the `Provisioner` field of the storage class that is responsible for the PVC that is being snapshotted.
38
+
+
39
+
[NOTE]
40
+
====
41
+
Depending on the driver that you used to configure persistent storage, additional parameters might be required. You can also use an existing `VolumeSnapshotClass` object.
42
+
====
43
+
44
+
. Create the object you saved in the previous step by entering the following command:
45
+
+
46
+
[source,terminal]
47
+
----
48
+
$ oc create -f volumesnapshotclass.yaml
49
+
----
50
+
51
+
. Provide a value for the `volumeSnapshotContentName` parameter as the source for the snapshot:
52
+
+
53
+
.Example volumesnapshot-manual.yaml
54
+
[source,yaml]
55
+
----
56
+
apiVersion: snapshot.storage.k8s.io/v1
57
+
kind: VolumeSnapshot
58
+
metadata:
59
+
name: snapshot-demo
60
+
spec:
61
+
source:
62
+
volumeSnapshotContentName: mycontent
63
+
----
64
+
+
65
+
`spec.source.volumeSnapshotContentName` is required for pre-provisioned snapshots.
66
+
67
+
. Create the object you saved in the previous step by entering the following command:
68
+
+
69
+
[source,terminal]
70
+
----
71
+
$ oc create -f volumesnapshot-manual.yaml
72
+
----
73
+
74
+
.Verification
75
+
After the snapshot has been created in the cluster, additional details about the snapshot are available.
76
+
77
+
. To display details about the volume snapshot that was created, enter the following command:
78
+
+
79
+
[source,terminal]
80
+
----
81
+
$ oc describe volumesnapshot mysnap
82
+
----
83
+
+
84
+
The following example displays details about the `mysnap` volume snapshot:
* `status.boundVolumeSnapshotContentName`: Specifies the pointer to the actual storage content that was created by the controller.
105
+
* `status.creationTime`: Specifies the time when the snapshot was created. The snapshot contains the volume content that was available at this indicated time.
106
+
* `status.readyToUse`: If the value is set to `true`, the snapshot can be used to restore as a new PVC. If the value is set to `false`, the snapshot was created. However, the storage back end needs to perform additional tasks to make the snapshot usable so that it can be restored as a new volume. For example, Amazon Elastic Block Store data might be moved to a different, less expensive location, which can take several minutes.
107
+
108
+
. To verify that the volume snapshot was created, enter the following command:
109
+
+
110
+
[source,terminal]
111
+
----
112
+
$ oc get volumesnapshotcontent
113
+
----
114
+
+
115
+
The pointer to the actual content is displayed. If the `boundVolumeSnapshotContentName` field is populated, a `VolumeSnapshotContent` object exists and the snapshot was created.
116
+
117
+
. To verify that the snapshot is ready, confirm that the `VolumeSnapshot` object has `readyToUse: true`.
When you create a `VolumeSnapshot` object, {product-title} creates a volume snapshot.
9
+
[role="_abstract"]
10
+
To create a point-in-time backup of a persistent volume claim (PVC), dynamically provision a volume snapshot by defining a VolumeSnapshotClass and VolumeSnapshot that automate the snapshot creation.
10
11
12
+
When you create a `VolumeSnapshot` object, {product-title} creates a volume snapshot.
11
13
12
14
.Prerequisites
13
15
* Logged in to a running {product-title} cluster.
@@ -21,24 +23,20 @@ Creating a volume snapshot of a PVC that is in use by a pod can cause unwritten
21
23
====
22
24
23
25
.Procedure
24
-
25
-
To dynamically create a volume snapshot:
26
-
27
26
. Create a file with the `VolumeSnapshotClass` object described by the following YAML:
28
-
29
27
+
30
-
.volumesnapshotclass.yaml
28
+
.Example volumesnapshotclass.yaml
31
29
[source,yaml]
32
30
----
33
31
apiVersion: snapshot.storage.k8s.io/v1
34
32
kind: VolumeSnapshotClass
35
33
metadata:
36
34
name: csi-hostpath-snap
37
-
driver: hostpath.csi.k8s.io <1>
35
+
driver: hostpath.csi.k8s.io
38
36
deletionPolicy: Delete
39
37
----
40
38
+
41
-
<1> The name of the CSI driver that is used to create snapshots of this `VolumeSnapshotClass` object. The name must be the same as the `Provisioner` field of the storage class that is responsible for the PVC that is being snapshotted.
39
+
`driver` is the name of the CSI driver that is used to create snapshots of this `VolumeSnapshotClass` object. The name must be the same as the `Provisioner` field of the storage class that is responsible for the PVC that is being snapshotted.
<1> The request for a particular class by the volume snapshot. If the `volumeSnapshotClassName` setting is absent and there is a default volume snapshot class, a snapshot is created with the default volume snapshot class name. But if the field is absent and no default volume snapshot class exists, then no snapshot is created.
72
-
+
73
-
<2> The name of the `PersistentVolumeClaim` object bound to a persistent volume. This defines what you want to create a snapshot of. Required for dynamically provisioning a snapshot.
68
+
* `spec.volumeSnapshotClassName`: Specifies the request for a particular class by the volume snapshot. If the `volumeSnapshotClassName` setting is absent and there is a default volume snapshot class, a snapshot is created with the default volume snapshot class name. But if the field is absent and no default volume snapshot class exists, then no snapshot is created.
69
+
* `spec.source.persistentVolumeClaimName`: Specifies the name of the `PersistentVolumeClaim` object bound to a persistent volume. This defines what you want to create a snapshot of. Required for dynamically provisioning a snapshot.
74
70
75
71
. Create the object you saved in the previous step by entering the following command:
76
72
+
@@ -79,35 +75,10 @@ spec:
79
75
$ oc create -f volumesnapshot-dynamic.yaml
80
76
----
81
77
82
-
83
-
To manually provision a snapshot:
84
-
85
-
. Provide a value for the `volumeSnapshotContentName` parameter as the source for the snapshot, in addition to defining volume snapshot class as shown above.
86
-
+
87
-
.volumesnapshot-manual.yaml
88
-
[source,yaml]
89
-
----
90
-
apiVersion: snapshot.storage.k8s.io/v1
91
-
kind: VolumeSnapshot
92
-
metadata:
93
-
name: snapshot-demo
94
-
spec:
95
-
source:
96
-
volumeSnapshotContentName: mycontent <1>
97
-
----
98
-
<1> The `volumeSnapshotContentName` parameter is required for pre-provisioned snapshots.
99
-
100
-
. Create the object you saved in the previous step by entering the following command:
101
-
+
102
-
[source,terminal]
103
-
----
104
-
$ oc create -f volumesnapshot-manual.yaml
105
-
----
106
-
107
78
.Verification
108
-
After the snapshot has been created in the cluster, additional details about the snapshot are available.
109
-
110
-
. To display details about the volume snapshot that was created, enter the following command:
79
+
. After the snapshot has been created in the cluster, additional details about the snapshot are available.
80
+
+
81
+
To display details about the volume snapshot that was created, run the following command:
<1> The pointer to the actual storage content that was created by the controller.
137
-
<2> The time when the snapshot was created. The snapshot contains the volume content that was available at this indicated time.
138
-
<3> If the value is set to `true`, the snapshot can be used to restore as a new PVC.
139
-
+
140
-
If the value is set to `false`, the snapshot was created. However, the storage back end needs to perform additional tasks to make the snapshot usable so that it can be restored as a new volume. For example, Amazon Elastic Block Store data might be moved to a different, less expensive location, which can take several minutes.
107
+
+
108
+
* `status.boundVolumeSnapshotContentName`: This parameter is the pointer to the actual storage content that was created by the controller.
109
+
* `status.creationTime`: Specifies the time when the snapshot was created. The snapshot contains the volume content that was available at this indicated time.
110
+
* `status.readyToUse`: Specifies the readiness of the snapshot. If the value is set to `true`, the snapshot can be used to restore as a new PVC. If the value is set to `false`, the snapshot was created. However, the storage back end needs to perform additional tasks to make the snapshot usable so that it can be restored as a new volume. For example, Amazon Elastic Block Store data might be moved to a different, less expensive location, which can take several minutes.
141
111
142
112
. To verify that the volume snapshot was created, enter the following command:
143
113
+
@@ -148,4 +118,4 @@ $ oc get volumesnapshotcontent
148
118
+
149
119
The pointer to the actual content is displayed. If the `boundVolumeSnapshotContentName` field is populated, a `VolumeSnapshotContent` object exists and the snapshot was created.
150
120
151
-
. To verify that the snapshot is ready, confirm that the `VolumeSnapshot` object has `readyToUse: true`.
121
+
. To verify that the snapshot is ready, confirm that the `VolumeSnapshot` object has `readyToUse: true`.
Copy file name to clipboardExpand all lines: modules/persistent-storage-csi-snapshots-delete.adoc
+9-7Lines changed: 9 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,10 +8,9 @@
8
8
= Deleting a volume snapshot
9
9
10
10
[role="_abstract"]
11
-
You can configure how {product-title} deletes volume snapshots.
11
+
To clean up unneeded snapshots and free storage resources, delete volume snapshots by setting a deletion policy that controls whether the underlying content is retained or removed.
12
12
13
13
.Procedure
14
-
15
14
. Specify the deletion policy that you require in the `VolumeSnapshotClass` object, as shown in the following example:
16
15
+
17
16
.Example volumesnapshotclass.yaml file
@@ -25,7 +24,8 @@ driver: hostpath.csi.k8s.io
25
24
deletionPolicy: Delete
26
25
# ...
27
26
----
28
-
**`deletionPolicy`: When deleting the volume snapshot, if the `Delete` value is set, the underlying snapshot is deleted along with the `VolumeSnapshotContent` object. If the `Retain` value is set, both the underlying snapshot and `VolumeSnapshotContent` object remain.
27
+
+
28
+
When deleting the volume snapshot, if `deletionPolicy` is set to `Delete`, the underlying snapshot is deleted along with the `VolumeSnapshotContent` object. If the `Retain` value is set, both the underlying snapshot and `VolumeSnapshotContent` object remain.
29
29
+
30
30
[NOTE]
31
31
====
@@ -36,9 +36,10 @@ If the `Retain` value is set and the `VolumeSnapshot` object is deleted without
** Replace `_<volumesnapshotcontent_name>_` with the content you want to delete.
56
+
+
57
+
Replace `<volumesnapshotcontent_name>` with the content you want to delete.
56
58
57
59
. Optional: If the `VolumeSnapshot` object is not successfully deleted, enter the following command to remove any finalizers for the leftover resource so that the delete operation can continue:
You can manage volume snapshots in {product-title} by using the CSI Snapshot Controller Operator's custom resource definitions (CRDs) for snapshot requests, storage, and configuration.
11
+
9
12
The Container Storage Interface (CSI) Snapshot Controller Operator runs in the `openshift-cluster-storage-operator` namespace. It is installed by the Cluster Version Operator (CVO) in all clusters by default.
10
13
11
14
The CSI Snapshot Controller Operator installs the CSI snapshot controller, which runs in the `openshift-cluster-storage-operator` namespace.
12
15
13
16
== Volume snapshot CRDs
14
-
15
17
During {product-title} installation, the CSI Snapshot Controller Operator creates the following snapshot custom resource definitions (CRDs) in the `snapshot.storage.k8s.io/v1` API group:
16
18
17
19
`VolumeSnapshotContent`::
18
-
19
20
A snapshot taken of a volume in the cluster that has been provisioned by a cluster administrator.
20
21
+
21
22
Similar to the `PersistentVolume` object, the `VolumeSnapshotContent` CRD is a cluster resource that points to a real snapshot in the storage back end.
@@ -25,13 +26,11 @@ For manually pre-provisioned snapshots, a cluster administrator creates a number
25
26
The `VolumeSnapshotContent` CRD is not namespaced and is for use by a cluster administrator.
26
27
27
28
`VolumeSnapshot`::
28
-
29
29
Similar to the `PersistentVolumeClaim` object, the `VolumeSnapshot` CRD defines a developer request for a snapshot. The CSI Snapshot Controller Operator runs the CSI snapshot controller, which handles the binding of a `VolumeSnapshot` CRD with an appropriate `VolumeSnapshotContent` CRD. The binding is a one-to-one mapping.
30
30
+
31
31
The `VolumeSnapshot` CRD is namespaced. A developer uses the CRD as a distinct request for a snapshot.
32
32
33
33
`VolumeSnapshotClass`::
34
-
35
34
The `VolumeSnapshotClass` CRD allows a cluster administrator to specify different attributes belonging to a `VolumeSnapshot` object. These attributes may differ among snapshots taken of the same volume on the storage system, in which case they would not be expressed by using the same storage class of a persistent volume claim.
36
35
+
37
36
The `VolumeSnapshotClass` CRD defines the parameters for the `csi-external-snapshotter` sidecar to use when creating a snapshot. This allows the storage back end to know what kind of snapshot to dynamically create if multiple options are supported.
@@ -48,7 +47,7 @@ If you want to use the images volume snapshot class for dynamic snapshot provisi
48
47
49
48
* When creating the snapshot object, be sure to set `volumeSnapshotClassName` to `csi-gce-pd-vsc-images`.
50
49
+
51
-
For information about creating volume snapshots, see Section _Creating a volume snapshot_.
50
+
For information about creating volume snapshots, see "Dynamically creating a volume snapshot" and "Statically creating a volume snapshot".
52
51
+
53
52
.Example images volume snapshot class YAML file
54
53
[source,yaml]
@@ -62,6 +61,5 @@ parameters:
62
61
snapshot-type: images
63
62
----
64
63
+
65
-
* `metadata.name:csi-gce-pd-vsc-images`: Name for the non-default images volume snapshot class.
66
-
64
+
* `metadata.name:csi-gce-pd-vsc-images`: Specifies the name for the non-default images volume snapshot class.
67
65
* `parameters: snapshot-type: images`: Defines the snapshot as a "golden image" or a bootable template, rather than the standard disk backup.
0 commit comments