Skip to content

Commit cd2d854

Browse files
windsonseawindsonsea
committed
Tweak line wrappings in /volume-snapshots.md
1 parent e212bfe commit cd2d854

File tree

1 file changed

+97
-41
lines changed

1 file changed

+97
-41
lines changed

‎content/en/docs/concepts/storage/volume-snapshots.md

Lines changed: 97 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -13,65 +13,107 @@ weight: 60
1313

1414
<!-- overview -->
1515

16-
In Kubernetes, a _VolumeSnapshot_ represents a snapshot of a volume on a storage system. This document assumes that you are already familiar with Kubernetes [persistent volumes](/docs/concepts/storage/persistent-volumes/).
17-
18-
19-
16+
In Kubernetes, a _VolumeSnapshot_ represents a snapshot of a volume on a storage
17+
system. This document assumes that you are already familiar with Kubernetes
18+
[persistent volumes](/docs/concepts/storage/persistent-volumes/).
2019

2120
<!-- body -->
2221

2322
## Introduction
2423

25-
Similar to how API resources `PersistentVolume` and `PersistentVolumeClaim` are used to provision volumes for users and administrators, `VolumeSnapshotContent` and `VolumeSnapshot` API resources are provided to create volume snapshots for users and administrators.
24+
Similar to how API resources `PersistentVolume` and `PersistentVolumeClaim` are
25+
used to provision volumes for users and administrators, `VolumeSnapshotContent`
26+
and `VolumeSnapshot` API resources are provided to create volume snapshots for
27+
users and administrators.
2628

27-
A `VolumeSnapshotContent` is a snapshot taken from a volume in the cluster that has been provisioned by an administrator. It is a resource in the cluster just like a PersistentVolume is a cluster resource.
29+
A `VolumeSnapshotContent` is a snapshot taken from a volume in the cluster that
30+
has been provisioned by an administrator. It is a resource in the cluster just
31+
like a PersistentVolume is a cluster resource.
2832

29-
A `VolumeSnapshot` is a request for snapshot of a volume by a user. It is similar to a PersistentVolumeClaim.
33+
A `VolumeSnapshot` is a request for snapshot of a volume by a user. It is similar
34+
to a PersistentVolumeClaim.
3035

31-
`VolumeSnapshotClass` allows you to specify different attributes belonging to a `VolumeSnapshot`. These attributes may differ among snapshots taken from the same volume on the storage system and therefore cannot be expressed by using the same `StorageClass` of a `PersistentVolumeClaim`.
36+
`VolumeSnapshotClass` allows you to specify different attributes belonging to a
37+
`VolumeSnapshot`. These attributes may differ among snapshots taken from the same
38+
volume on the storage system and therefore cannot be expressed by using the same
39+
`StorageClass` of a `PersistentVolumeClaim`.
3240

33-
Volume snapshots provide Kubernetes users with a standardized way to copy a volume's contents at a particular point in time without creating an entirely new volume. This functionality enables, for example, database administrators to backup databases before performing edit or delete modifications.
41+
Volume snapshots provide Kubernetes users with a standardized way to copy a volume's
42+
contents at a particular point in time without creating an entirely new volume. This
43+
functionality enables, for example, database administrators to backup databases before
44+
performing edit or delete modifications.
3445

3546
Users need to be aware of the following when using this feature:
3647

37-
* API Objects `VolumeSnapshot`, `VolumeSnapshotContent`, and `VolumeSnapshotClass` are {{< glossary_tooltip term_id="CustomResourceDefinition" text="CRDs" >}}, not part of the core API.
38-
* `VolumeSnapshot` support is only available for CSI drivers.
39-
* As part of the deployment process of `VolumeSnapshot`, the Kubernetes team provides a snapshot controller to be deployed into the control plane, and a sidecar helper container called csi-snapshotter to be deployed together with the CSI driver. The snapshot controller watches `VolumeSnapshot` and `VolumeSnapshotContent` objects and is responsible for the creation and deletion of `VolumeSnapshotContent` object. The sidecar csi-snapshotter watches `VolumeSnapshotContent` objects and triggers `CreateSnapshot` and `DeleteSnapshot` operations against a CSI endpoint.
40-
* There is also a validating webhook server which provides tightened validation on snapshot objects. This should be installed by the Kubernetes distros along with the snapshot controller and CRDs, not CSI drivers. It should be installed in all Kubernetes clusters that has the snapshot feature enabled.
41-
* CSI drivers may or may not have implemented the volume snapshot functionality. The CSI drivers that have provided support for volume snapshot will likely use the csi-snapshotter. See [CSI Driver documentation](https://kubernetes-csi.github.io/docs/) for details.
42-
* The CRDs and snapshot controller installations are the responsibility of the Kubernetes distribution.
48+
- API Objects `VolumeSnapshot`, `VolumeSnapshotContent`, and `VolumeSnapshotClass`
49+
are {{< glossary_tooltip term_id="CustomResourceDefinition" text="CRDs" >}}, not
50+
part of the core API.
51+
- `VolumeSnapshot` support is only available for CSI drivers.
52+
- As part of the deployment process of `VolumeSnapshot`, the Kubernetes team provides
53+
a snapshot controller to be deployed into the control plane, and a sidecar helper
54+
container called csi-snapshotter to be deployed together with the CSI driver.
55+
The snapshot controller watches `VolumeSnapshot` and `VolumeSnapshotContent` objects
56+
and is responsible for the creation and deletion of `VolumeSnapshotContent` object.
57+
The sidecar csi-snapshotter watches `VolumeSnapshotContent` objects and triggers
58+
`CreateSnapshot` and `DeleteSnapshot` operations against a CSI endpoint.
59+
- There is also a validating webhook server which provides tightened validation on
60+
snapshot objects. This should be installed by the Kubernetes distros along with
61+
the snapshot controller and CRDs, not CSI drivers. It should be installed in all
62+
Kubernetes clusters that has the snapshot feature enabled.
63+
- CSI drivers may or may not have implemented the volume snapshot functionality.
64+
The CSI drivers that have provided support for volume snapshot will likely use
65+
the csi-snapshotter. See [CSI Driver documentation](https://kubernetes-csi.github.io/docs/) for details.
66+
- The CRDs and snapshot controller installations are the responsibility of the Kubernetes distribution.
4367

4468
## Lifecycle of a volume snapshot and volume snapshot content
4569

46-
`VolumeSnapshotContents` are resources in the cluster. `VolumeSnapshots` are requests for those resources. The interaction between `VolumeSnapshotContents` and `VolumeSnapshots` follow this lifecycle:
70+
`VolumeSnapshotContents` are resources in the cluster. `VolumeSnapshots` are requests
71+
for those resources. The interaction between `VolumeSnapshotContents` and `VolumeSnapshots`
72+
follow this lifecycle:
4773

4874
### Provisioning Volume Snapshot
4975

5076
There are two ways snapshots may be provisioned: pre-provisioned or dynamically provisioned.
5177

5278
#### Pre-provisioned {#static}
53-
A cluster administrator creates a number of `VolumeSnapshotContents`. They carry the details of the real volume snapshot on the storage system which is available for use by cluster users. They exist in the Kubernetes API and are available for consumption.
79+
80+
A cluster administrator creates a number of `VolumeSnapshotContents`. They carry the details
81+
of the real volume snapshot on the storage system which is available for use by cluster users.
82+
They exist in the Kubernetes API and are available for consumption.
5483

5584
#### Dynamic
56-
Instead of using a pre-existing snapshot, you can request that a snapshot to be dynamically taken from a PersistentVolumeClaim. The [VolumeSnapshotClass](/docs/concepts/storage/volume-snapshot-classes/) specifies storage provider-specific parameters to use when taking a snapshot.
85+
86+
Instead of using a pre-existing snapshot, you can request that a snapshot to be dynamically
87+
taken from a PersistentVolumeClaim. The [VolumeSnapshotClass](/docs/concepts/storage/volume-snapshot-classes/)
88+
specifies storage provider-specific parameters to use when taking a snapshot.
5789

5890
### Binding
5991

60-
The snapshot controller handles the binding of a `VolumeSnapshot` object with an appropriate `VolumeSnapshotContent` object, in both pre-provisioned and dynamically provisioned scenarios. The binding is a one-to-one mapping.
92+
The snapshot controller handles the binding of a `VolumeSnapshot` object with an appropriate
93+
`VolumeSnapshotContent` object, in both pre-provisioned and dynamically provisioned scenarios.
94+
The binding is a one-to-one mapping.
6195

62-
In the case of pre-provisioned binding, the VolumeSnapshot will remain unbound until the requested VolumeSnapshotContent object is created.
96+
In the case of pre-provisioned binding, the VolumeSnapshot will remain unbound until the
97+
requested VolumeSnapshotContent object is created.
6398

6499
### Persistent Volume Claim as Snapshot Source Protection
65100

66101
The purpose of this protection is to ensure that in-use
67102
{{< glossary_tooltip text="PersistentVolumeClaim" term_id="persistent-volume-claim" >}}
68-
API objects are not removed from the system while a snapshot is being taken from it (as this may result in data loss).
103+
API objects are not removed from the system while a snapshot is being taken from it
104+
(as this may result in data loss).
69105

70-
While a snapshot is being taken of a PersistentVolumeClaim, that PersistentVolumeClaim is in-use. If you delete a PersistentVolumeClaim API object in active use as a snapshot source, the PersistentVolumeClaim object is not removed immediately. Instead, removal of the PersistentVolumeClaim object is postponed until the snapshot is readyToUse or aborted.
106+
While a snapshot is being taken of a PersistentVolumeClaim, that PersistentVolumeClaim
107+
is in-use. If you delete a PersistentVolumeClaim API object in active use as a snapshot
108+
source, the PersistentVolumeClaim object is not removed immediately. Instead, removal of
109+
the PersistentVolumeClaim object is postponed until the snapshot is readyToUse or aborted.
71110

72111
### Delete
73112

74-
Deletion is triggered by deleting the `VolumeSnapshot` object, and the `DeletionPolicy` will be followed. If the `DeletionPolicy` is `Delete`, then the underlying storage snapshot will be deleted along with the `VolumeSnapshotContent` object. If the `DeletionPolicy` is `Retain`, then both the underlying snapshot and `VolumeSnapshotContent` remain.
113+
Deletion is triggered by deleting the `VolumeSnapshot` object, and the `DeletionPolicy`
114+
will be followed. If the `DeletionPolicy` is `Delete`, then the underlying storage snapshot
115+
will be deleted along with the `VolumeSnapshotContent` object. If the `DeletionPolicy` is
116+
`Retain`, then both the underlying snapshot and `VolumeSnapshotContent` remain.
75117

76118
## VolumeSnapshots
77119

@@ -88,13 +130,17 @@ spec:
88130
persistentVolumeClaimName: pvc-test
89131
```
90132
91-
`persistentVolumeClaimName` is the name of the PersistentVolumeClaim data source for the snapshot. This field is required for dynamically provisioning a snapshot.
133+
`persistentVolumeClaimName` is the name of the PersistentVolumeClaim data source
134+
for the snapshot. This field is required for dynamically provisioning a snapshot.
92135

93136
A volume snapshot can request a particular class by specifying the name of a
94137
[VolumeSnapshotClass](/docs/concepts/storage/volume-snapshot-classes/)
95-
using the attribute `volumeSnapshotClassName`. If nothing is set, then the default class is used if available.
138+
using the attribute `volumeSnapshotClassName`. If nothing is set, then the
139+
default class is used if available.
96140

97-
For pre-provisioned snapshots, you need to specify a `volumeSnapshotContentName` as the source for the snapshot as shown in the following example. The `volumeSnapshotContentName` source field is required for pre-provisioned snapshots.
141+
For pre-provisioned snapshots, you need to specify a `volumeSnapshotContentName`
142+
as the source for the snapshot as shown in the following example. The
143+
`volumeSnapshotContentName` source field is required for pre-provisioned snapshots.
98144

99145
```yaml
100146
apiVersion: snapshot.storage.k8s.io/v1
@@ -108,7 +154,8 @@ spec:
108154

109155
## Volume Snapshot Contents
110156

111-
Each VolumeSnapshotContent contains a spec and status. In dynamic provisioning, the snapshot common controller creates `VolumeSnapshotContent` objects. Here is an example:
157+
Each VolumeSnapshotContent contains a spec and status. In dynamic provisioning,
158+
the snapshot common controller creates `VolumeSnapshotContent` objects. Here is an example:
112159

113160
```yaml
114161
apiVersion: snapshot.storage.k8s.io/v1
@@ -128,9 +175,13 @@ spec:
128175
uid: 72d9a349-aacd-42d2-a240-d775650d2455
129176
```
130177

131-
`volumeHandle` is the unique identifier of the volume created on the storage backend and returned by the CSI driver during the volume creation. This field is required for dynamically provisioning a snapshot. It specifies the volume source of the snapshot.
178+
`volumeHandle` is the unique identifier of the volume created on the storage
179+
backend and returned by the CSI driver during the volume creation. This field
180+
is required for dynamically provisioning a snapshot.
181+
It specifies the volume source of the snapshot.
132182

133-
For pre-provisioned snapshots, you (as cluster administrator) are responsible for creating the `VolumeSnapshotContent` object as follows.
183+
For pre-provisioned snapshots, you (as cluster administrator) are responsible
184+
for creating the `VolumeSnapshotContent` object as follows.
134185

135186
```yaml
136187
apiVersion: snapshot.storage.k8s.io/v1
@@ -148,19 +199,24 @@ spec:
148199
namespace: default
149200
```
150201

151-
`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.
202+
`snapshotHandle` is the unique identifier of the volume snapshot created on
203+
the storage backend. This field is required for the pre-provisioned snapshots.
204+
It specifies the CSI snapshot id on the storage system that this
205+
`VolumeSnapshotContent` represents.
152206

153-
`sourceVolumeMode` is the mode of the volume whose snapshot is taken. The value
154-
of the `sourceVolumeMode` field can be either `Filesystem` or `Block`. If the
155-
source volume mode is not specified, Kubernetes treats the snapshot as if the
207+
`sourceVolumeMode` is the mode of the volume whose snapshot is taken. The value
208+
of the `sourceVolumeMode` field can be either `Filesystem` or `Block`. If the
209+
source volume mode is not specified, Kubernetes treats the snapshot as if the
156210
source volume's mode is unknown.
157211

158-
`volumeSnapshotRef` is the reference of the corresponding `VolumeSnapshot`. Note that when the `VolumeSnapshotContent` is being created as a pre-provisioned snapshot, the `VolumeSnapshot` referenced in `volumeSnapshotRef` might not exist yet.
212+
`volumeSnapshotRef` is the reference of the corresponding `VolumeSnapshot`. Note that
213+
when the `VolumeSnapshotContent` is being created as a pre-provisioned snapshot, the
214+
`VolumeSnapshot` referenced in `volumeSnapshotRef` might not exist yet.
159215

160216
## Converting the volume mode of a Snapshot {#convert-volume-mode}
161217

162218
If the `VolumeSnapshots` API installed on your cluster supports the `sourceVolumeMode`
163-
field, then the API has the capability to prevent unauthorized users from converting
219+
field, then the API has the capability to prevent unauthorized users from converting
164220
the mode of a volume.
165221

166222
To check if your cluster has capability for this feature, run the following command:
@@ -169,12 +225,12 @@ To check if your cluster has capability for this feature, run the following comm
169225
$ kubectl get crd volumesnapshotcontent -o yaml
170226
```
171227

172-
If you want to allow users to create a `PersistentVolumeClaim` from an existing
173-
`VolumeSnapshot`, but with a different volume mode than the source, the annotation
174-
`snapshot.storage.kubernetes.io/allowVolumeModeChange: "true"`needs to be added to
175-
the `VolumeSnapshotContent` that corresponds to the `VolumeSnapshot`.
228+
If you want to allow users to create a `PersistentVolumeClaim` from an existing
229+
`VolumeSnapshot`, but with a different volume mode than the source, the annotation
230+
`snapshot.storage.kubernetes.io/allowVolumeModeChange: "true"`needs to be added to
231+
the `VolumeSnapshotContent` that corresponds to the `VolumeSnapshot`.
176232

177-
For pre-provisioned snapshots, `Spec.SourceVolumeMode` needs to be populated
233+
For pre-provisioned snapshots, `Spec.SourceVolumeMode` needs to be populated
178234
by the cluster administrator.
179235

180236
An example `VolumeSnapshotContent` resource with this feature enabled would look like:
@@ -200,7 +256,7 @@ spec:
200256
## Provisioning Volumes from Snapshots
201257

202258
You can provision a new volume, pre-populated with data from a snapshot, by using
203-
the *dataSource* field in the `PersistentVolumeClaim` object.
259+
the _dataSource_ field in the `PersistentVolumeClaim` object.
204260

205261
For more details, see
206262
[Volume Snapshot and Restore Volume from Snapshot](/docs/concepts/storage/persistent-volumes/#volume-snapshot-and-restore-volume-from-snapshot-support).

0 commit comments

Comments
 (0)