Add documentation for VolumeSnapshot Beta #17233

xing-yang · 2019-10-27T16:46:33Z

This PR adds documentation for promoting VolumeSnapshot API to beta. It is pending the merge of this PR: kubernetes/kubernetes#80058

k8sio-netlify-preview-bot · 2019-10-27T16:46:39Z

Deploy preview for kubernetes-io-vnext-staging processing.

Building with commit d36b480

https://app.netlify.com/sites/kubernetes-io-vnext-staging/deploys/5dd81a5bc4524000086bc148

makoscafee · 2019-11-04T23:16:45Z

/milestone 1.17

sftim

Informal feedback

sftim · 2019-11-06T19:11:15Z

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

 - saad-ali
 - thockin
 - msau42
+- jingxu97
+- xing-yang
+- yuxiangqian
 title: Volume Snapshots
 content_template: templates/concept
 weight: 20
 ---

 {{% capture overview %}}



Suggested change

{{< feature-state for_k8s_version="1.17" state="beta" >}}

sftim · 2019-11-06T19:13:47Z

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

 title: Volume Snapshots
 content_template: templates/concept
 weight: 20
 ---

 {{% capture overview %}}

-This document describes the current state of `VolumeSnapshots` in Kubernetes. Familiarity with [persistent volumes](/docs/concepts/storage/persistent-volumes/) is suggested.
+This document describes the current state of `VolumeSnapshots` in Kubernetes. Familiarity with [persistent volumes](/docs/concepts/storage/persistent-volumes/) is suggested. `VolumeSnapshot` is introduced as an alpha feature in Kubernetes 1.12 and is promoted to beta in 1.17.


If you use a feature state shortcode, this could be:

Suggested change

This document describes the current state of `VolumeSnapshots` in Kubernetes. Familiarity with [persistent volumes](/docs/concepts/storage/persistent-volumes/) is suggested. `VolumeSnapshot` is introduced as an alpha feature in Kubernetes 1.12 and is promoted to beta in 1.17.

In Kubernetes, a _VolumeSnapshot_ represents a snapshot of a storage volume. This document assumes that you are already familiar with Kubernetes [persistent volumes](/docs/concepts/storage/persistent-volumes/).

sftim · 2019-11-06T19:14:45Z

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


-#### Static
+#### Pre-provisioned


Optional tweak:

Suggested change

#### Pre-provisioned

#### Pre-provisioned {#static}

(if there are existing inbound hyperlinks, this change means those existing links will stay working).

sftim · 2019-11-06T19:18:45Z

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

@@ -35,38 +37,36 @@ Users need to be aware of the following when using this feature:

 * API Objects `VolumeSnapshot`, `VolumeSnapshotContent`, and `VolumeSnapshotClass` are CRDs, not part of the core API.
 * `VolumeSnapshot` support is only available for CSI drivers.
-* As part of the deployment process, the Kubernetes team provides a sidecar helper container for the snapshot controller called `external-snapshotter`. It watches `VolumeSnapshot` objects and triggers `CreateSnapshot` and `DeleteSnapshot` operations against a CSI endpoint.
+* As part of the deployment process in `VolumeSnapshot` API v1beta1, the Kubernetes team provides two external snapshot controllers called `external-snapshotter`, a common controller to be deployed on the controller node and a sidecar helper container to be deployed together with the CSI driver.  The common controller watches `VolumeSnapshot` and `VolumeSnapshotContent` objects and is responsible for the creation and deletion of `VolumeSnapshotContent` object in dynamic provisioning.  The sidecar controller watches `VolumeSnapshotContent` objects and triggers `CreateSnapshot` and `DeleteSnapshot` operations against a CSI endpoint.


Optional suggestion (not particularly relevant to v1.17, but a good idea): add a glossary tooltip for “controller”:

Suggested change

* As part of the deployment process in `VolumeSnapshot` API v1beta1, the Kubernetes team provides two external snapshot controllers called `external-snapshotter`, a common controller to be deployed on the controller node and a sidecar helper container to be deployed together with the CSI driver. The common controller watches `VolumeSnapshot` and `VolumeSnapshotContent` objects and is responsible for the creation and deletion of `VolumeSnapshotContent` object in dynamic provisioning. The sidecar controller watches `VolumeSnapshotContent` objects and triggers `CreateSnapshot` and `DeleteSnapshot` operations against a CSI endpoint.

* As part of the deployment process in `VolumeSnapshot` API v1beta1, the Kubernetes team provides two external snapshot {{< glossary_tooltip term_id="controller" text="controllesr" >}} called `external-snapshotter`, a common controller to be deployed into the control plane, and a sidecar helper container to be deployed together with the CSI driver. The common controller watches `VolumeSnapshot` and `VolumeSnapshotContent` objects and is responsible for the creation and deletion of `VolumeSnapshotContent` object in dynamic provisioning. The sidecar controller watches `VolumeSnapshotContent` objects and triggers `CreateSnapshot` and `DeleteSnapshot` operations against a CSI endpoint.

I'm not sure I understand the “in VolumeSnapshot API v1beta1” addition. What's the learning outcome for a reader seeing that phrase?

Aside: I've got an open PR (#16885) to add reference documentation for controllers. Would it make sense to put the implementation details into the reference section once that's merged?

The snapshot controller code repo is here: https://github.com/kubernetes-csi/external-snapshotter, not in the core kubernetes repo. Do you want to include out-of-tree controllers in the reference doc?

On the other hand, since we documented the snapshot controller here, it does make sense to reference it in your PR.

I think it could be a separate PR and a section called something like “Additional controllers”, to highlight that this doesn't run inside kube-controller-manager.

Reworded this section.

xing-yang · 2019-11-11T03:04:25Z

/assign @msau42

sftim · 2019-11-11T22:56:07Z

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

@@ -12,7 +14,8 @@ weight: 20
 {{% capture overview %}}

 {{< feature-state for_k8s_version="v1.12" state="alpha" >}}


I don't think this line should remain/

sftim · 2019-11-11T22:57:43Z

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

 ```

-### Class
+For pre-provisioned snapshots, the admin is responsible for creating the `VolumeSnapshotContent` object.


Suggested change

For pre-provisioned snapshots, the admin is responsible for creating the `VolumeSnapshotContent` object.

For pre-provisioned snapshots, you (as cluster administrator) are responsible for creating the `VolumeSnapshotContent` object.

per address the reader as “you”.

sftim · 2019-11-11T23:01:09Z

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

@@ -36,38 +39,36 @@ Users need to be aware of the following when using this feature:

 * API Objects `VolumeSnapshot`, `VolumeSnapshotContent`, and `VolumeSnapshotClass` are CRDs, not part of the core API.


Suggested change

* API Objects `VolumeSnapshot`, `VolumeSnapshotContent`, and `VolumeSnapshotClass` are CRDs, not part of the core API.

* API Objects `VolumeSnapshot`, `VolumeSnapshotContent`, and `VolumeSnapshotClass` are {{< glossary_tooltip term_id="CustomResourceDefinition" text="CRDs" >}}, not part of the core API.

sftim · 2019-11-11T23:02:05Z

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

-* The CSI drivers that support volume snapshot will automatically install CRDs defined for the volume snapshots.
+* As part of the deployment process in the beta version 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 in dynamic provisioning.  The sidecar csi-snapshotter watches `VolumeSnapshotContent` objects and triggers `CreateSnapshot` and `DeleteSnapshot` operations against a CSI endpoint.
+* 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 snapshot controller and the csi-snapshotter.
+* The `VolumeSnapshot` v1beta CRDs need to be installed manually.


Suggested change

* The `VolumeSnapshot` v1beta CRDs need to be installed manually.

* You need to manually install the `VolumeSnapshot` v1beta CRDs.

(this kind of relies on the glossary tooltip for CRD being added above)

msau42 · 2019-11-13T01:17:15Z

content/en/docs/concepts/storage/volume-snapshot-classes.md

+### DeletionPolicy
+
+Volume snapshot classes have a deletionPolicy. It enables an admin to configure what happens to a `VolumeSnapshotContent` when the `VolumeSnapshot` object it is bound to is to be deleted. The deletionPolicy of a volume snapshot can either be `Retain` or `Delete`. This field must be specified.
+


explain what retain and delete do?

msau42 · 2019-11-13T01:17:50Z

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

-{{< feature-state for_k8s_version="v1.12" state="alpha" >}}
-This document describes the current state of `VolumeSnapshots` in Kubernetes. Familiarity with [persistent volumes](/docs/concepts/storage/persistent-volumes/) is suggested.
+{{< feature-state for_k8s_version="1.17" state="beta" >}}
+In Kubernetes, a _VolumeSnapshot_ represents a snapshot of a storage volume. This document assumes that you are already familiar with Kubernetes [persistent volumes](/docs/concepts/storage/persistent-volumes/).


snapshot of a PersistentVolumeClaim?

Changed to "snapshot of a volume on a storage system"

msau42 · 2019-11-13T01:21:10Z

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

@@ -34,40 +36,38 @@ there is the `VolumeSnapshotClass` resource.

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


The previous 3 paragraphs may need to be reworded to fit the new model, especially the 3rd paragraph "While VolumeSnapshots allow a user to consume abstract storage resources..."

msau42 · 2019-11-13T01:24:43Z

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

-* 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 `external-snapshotter`.
-* The CSI drivers that support volume snapshot will automatically install CRDs defined for the volume snapshots.
+* As part of the deployment process in the beta version 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 in dynamic provisioning.  The sidecar csi-snapshotter watches `VolumeSnapshotContent` objects and triggers `CreateSnapshot` and `DeleteSnapshot` operations against a CSI endpoint.
+* 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 snapshot controller and the csi-snapshotter.


CSI drivers should only use the sidecar. Link to the sidecar repo/documentation?

msau42 · 2019-11-13T01:25:53Z

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

-* The CSI drivers that support volume snapshot will automatically install CRDs defined for the volume snapshots.
+* As part of the deployment process in the beta version 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 in dynamic provisioning.  The sidecar csi-snapshotter watches `VolumeSnapshotContent` objects and triggers `CreateSnapshot` and `DeleteSnapshot` operations against a CSI endpoint.
+* 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 snapshot controller and the csi-snapshotter.
+* You need to manually install the `VolumeSnapshot` v1beta CRDs.


"The CRDs and snapshot controller installations are the responsibility of the Kubernetes distribution, not the CSI drivers."

Sure. Should we add "check its availability with the specific Kubernetes distribution you are using"? Otherwise it may not be there?

msau42 · 2019-11-13T01:45:21Z

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

@@ -77,58 +77,62 @@ Deletion removes both the `VolumeSnapshotContent` object from the Kubernetes API

 ## Volume Snapshot Contents

-Each VolumeSnapshotContent contains a spec, which is the specification of the volume snapshot.
+Each VolumeSnapshotContent contains a spec and status, which is the specification and status of the volume snapshot content. In dynamic provisioning, the `VolumeSnapshotContent` object is created by the snapshot common controller.


2nd half of this sentence is sort of redundant...

"In the pre-provisioned snapshot case, the object is created by an administrator"

The example is the following is a content dynamically created.

msau42 · 2019-11-13T01:45:57Z

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

-      driver:          csi-hostpath
-      restoreSize:     10Gi
-      snapshotHandle:  7bdd0de3-aaeb-11e8-9aae-0242ac110002
+    volumeHandle: ee0cfb94-f8d4-11e9-b2d8-0242ac110002


Are these fields going to be explained?

Added explanation.

msau42 · 2019-11-13T01:46:18Z

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

+  volumeSnapshotRef:
+    name: new-snapshot-test
+    namespace: default
+```

 ## VolumeSnapshots

 Each VolumeSnapshot contains a spec and a status, which is the specification and status of the volume snapshot.


2nd half of this sentence is redundant

msau42 · 2019-11-13T01:46:43Z

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

-using the attribute `snapshotClassName`.
-Only VolumeSnapshotContents of the requested class, ones with the same `snapshotClassName`
-as the VolumeSnapshot, can be bound to the VolumeSnapshot.
+using the attribute `volumeSnapshotClassName`.


If nothing is set, then the default class is used.

msau42 · 2019-11-13T01:47:41Z

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

  source:
-    name: pvc-test
-    kind: PersistentVolumeClaim
+    persistentVolumeClaimName: pvc-test


Maybe it's worth splitting up this section into "How to request a dynamically provisioned snapshot" and "How to request a pre-existing snapshot", and give examples for both.

I'd like to submit another PR as a task page for that. Things described at Concepts page seem to be relatively high level.

👍 for a separate task page.

I guess it's a little strange that not all the fields in the VolumeSnapshot are not explained, considering that this is the user-facing object. It feels inconsistent with the VolumeSnapshotContent object above that is very detailed but actually not really that important to the user.

sftim

Feedback— I hope it's useful.

sftim · 2019-11-14T11:15:45Z

content/en/docs/concepts/storage/volume-snapshot-classes.md

 used for provisioning VolumeSnapshots. This field must be specified.

+### DeletionPolicy
+
+Volume snapshot classes have a deletionPolicy. It enables an admin to configure what happens to a `VolumeSnapshotContent` when the `VolumeSnapshot` object it is bound to is to be deleted. The deletionPolicy of a volume snapshot can either be `Retain` or `Delete`. This field must be specified.


Optional, nit level suggestion

Suggested change

Volume snapshot classes have a deletionPolicy. It enables an admin to configure what happens to a `VolumeSnapshotContent` when the `VolumeSnapshot` object it is bound to is to be deleted. The deletionPolicy of a volume snapshot can either be `Retain` or `Delete`. This field must be specified.

Volume snapshot classes have a deletionPolicy. It enables you to configure what happens to a `VolumeSnapshotContent` when the `VolumeSnapshot` object it is bound to is to be deleted. The deletionPolicy of a volume snapshot can either be `Retain` or `Delete`. This field must be specified.

Really, objects like VolumeSnapshot should not have backticks. That cleanup can wait until after the v1.17 release.

Changed from "admin" to "you".

sftim · 2019-11-14T11:16:21Z

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

-need to be able to offer a variety of `VolumeSnapshotContents` without exposing
-users to the details of how those volume snapshots should be provisioned. For these needs
-there is the `VolumeSnapshotClass` resource.
+`VolumeSnapshotClass` allows user to specify different attributes belonging to a `VolumeSnapshot`. These attibutes 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`.


nit:

Suggested change

`VolumeSnapshotClass` allows user to specify different attributes belonging to a `VolumeSnapshot`. These attibutes 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`.

`VolumeSnapshotClass` allows you to specify different attributes belonging to a `VolumeSnapshot`. These attibutes 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`.

sftim · 2019-11-14T11:17:45Z

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


-#### Static
+#### Pre-provisioned {#static}


If it's better to break existing links in favour of clear naming, as a conscious decision, that's OK by me.

sftim · 2019-11-14T11:19:39Z

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

-[volume snapshot class](/docs/concepts/storage/volume-snapshot-classes/) and
-the administrator must have created and configured that class in order for dynamic
-provisioning to occur.
+Instead of a pre-existing snapshot, a user can request that a snapshot of a PVC is dynamically taken. The [VolumeSnapshotClass](/docs/concepts/storage/volume-snapshot-classes/) specifies storage provider-specific parameters to use when taking a snapshot.


Is this wording better:

Suggested change

Instead of a pre-existing snapshot, a user can request that a snapshot of a PVC is dynamically taken. The [VolumeSnapshotClass](/docs/concepts/storage/volume-snapshot-classes/) specifies storage provider-specific parameters to use when taking a snapshot.

Instead of using a pre-existing snapshot, you can request that the cluster creates a snapshot of an existing PersistentVolumeClaim. The [VolumeSnapshotClass](/docs/concepts/storage/volume-snapshot-classes/) specifies storage provider-specific parameters to use when taking a snapshot.

? (I'm not sure - although, if I've misunderstood, then that's a hint that the current wording is not clear).

sftim · 2019-11-14T11:22:02Z

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


-The purpose of the Persistent Volume Claim Object in Use Protection feature is to ensure that in-use PVC API objects are not removed from the system (as this may result in data loss).
+The purpose of the Persistent Volume Claim Object while a snapshot is being taken Protection feature is to ensure that in-use PVC API objects are not removed from the system (as this may result in data loss).


The purpose of the Persistent Volume Claim Object while a snapshot is being taken Protection feature is to ensure that in-use PVC API objects are not removed from the system (as this may result in data loss).
Ouch, that's hard to parse.

How about:

Suggested change

The purpose of the Persistent Volume Claim Object while a snapshot is being taken Protection feature is to ensure that in-use PVC API objects are not removed from the system (as this may result in data loss).

Kubernetes protects PersistentVolumeClaim objects during snapshotting operations.

(if that protection isn't done using a built-in controller, then replace “Kubernetes” with a description of what implements the protection).

I shortened the sentence a little bit. Hope that reads better.

sftim · 2019-11-14T11:23:49Z

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


-If a PVC is in active use by a snapshot as a source to create the snapshot, the PVC is in-use. If a user deletes a PVC API object in active use as a snapshot source, the PVC object is not removed immediately. Instead, removal of the PVC object is postponed until the PVC is no longer actively used by any snapshots. A PVC is no longer used as a snapshot source when `ReadyToUse` of the snapshot `Status` becomes `true`.
+If a snapshot is being taken of a PVC, that PVC is in-use. If a user deletes a PVC API object in active use as a snapshot source, the PVC object is not removed immediately. Instead, removal of the PVC object is postponed until the snapshot is readyToUse or aborted.


Suggested change

If a snapshot is being taken of a PVC, that PVC is in-use. If a user deletes a PVC API object in active use as a snapshot source, the PVC object is not removed immediately. Instead, removal of the PVC object is postponed until the snapshot is readyToUse or aborted.

While a snapshot is being taken of a PVC, that PVC is in-use. If you delete a PersistentVolumeClaim that is in active use as a snapshot source, the PersistentVolumeClaim is not removed immediately. Instead, removal of the PVC object is postponed until the snapshot either becomes readyToUse or is aborted.

How about this?

sftim · 2019-11-14T11:24:43Z

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


 ## Volume Snapshot Contents

-Each VolumeSnapshotContent contains a spec, which is the specification of the volume snapshot.
+Each VolumeSnapshotContent contains a spec and status. In dynamic provisioning, the `VolumeSnapshotContent` object is created by the snapshot common controller as follows.


Does this work better:

Suggested change

Each VolumeSnapshotContent contains a spec and status. In dynamic provisioning, the `VolumeSnapshotContent` object is created by the snapshot common controller as follows.

Each VolumeSnapshotContent contains a spec and status. In dynamic provisioning, the snapshot common controller creates `VolumeSnapshotContent` objects. Here's an example:

?

sftim · 2019-11-14T11:25:44Z

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

  source:
-    name: pvc-test
-    kind: PersistentVolumeClaim
+    persistentVolumeClaimName: pvc-test


👍 for a separate task page.

sftim · 2019-11-14T11:30:34Z

Do you also need to update https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/?

xing-yang · 2019-11-14T17:45:00Z

Do you also need to update https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/?

You are right. I missed that one. Updated this PR.

daminisatya · 2019-11-20T09:30:45Z

@sftim Do you think we need a tech review done on this?

daminisatya · 2019-11-20T09:31:18Z

Just a reminder about the last Docs deadline - 22nd Nov. We are looking for getting this merged.

sftim · 2019-11-20T15:02:51Z

@daminisatya in my opinion this does need tech review; there are behavior changes. The changes are not big so the review should be easy-ish.

xing-yang · 2019-11-20T17:58:24Z

@msau42 has been doing tech review. Michelle, can you please review again? I addressed your comments. Thanks.

msau42 · 2019-11-21T17:57:00Z

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

 [volume snapshot class](/docs/concepts/storage/volume-snapshot-classes/) and
 the administrator must have created and configured that class in order for dynamic
 provisioning to occur.

 ### Binding

-A user creates, or has already created in the case of dynamic provisioning, a `VolumeSnapshot` with a specific amount of storage requested and with certain access modes. A control loop watches for new VolumeSnapshots, finds a matching VolumeSnapshotContent (if possible), and binds them together. If a VolumeSnapshotContent was dynamically provisioned for a new VolumeSnapshot, the loop will always bind that VolumeSnapshotContent to the VolumeSnapshot. Once bound, `VolumeSnapshot` binds are exclusive, regardless of how they were bound. A VolumeSnapshot to VolumeSnapshotContent binding is a one-to-one mapping.
+A user creates, or has already created in the case of dynamic provisioning, a `VolumeSnapshot` with a specific attributes defined by the `VolumeSnapshotClass`. A control loop watches for new VolumeSnapshots, finds a matching VolumeSnapshotContent (if possible), and binds them together. If a VolumeSnapshotContent was dynamically provisioned for a new VolumeSnapshot, the loop will always bind that VolumeSnapshotContent to the VolumeSnapshot. Once bound, `VolumeSnapshot` binds are exclusive, regardless of how they were bound. A VolumeSnapshot to VolumeSnapshotContent binding is a one-to-one mapping.

 VolumeSnapshots will remain unbound indefinitely if a matching VolumeSnapshotContent does not exist. VolumeSnapshots will be bound as matching VolumeSnapshotContents become available.


maybe this can be reworded to something like "In the case of pre-provisioned binding, the VolumeSnapshot will will remain unbound until the requested VolumeSnapshotContent object is created."

msau42 · 2019-11-21T17:57:29Z

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


-The purpose of the Persistent Volume Claim Object in Use Protection feature is to ensure that in-use PVC API objects are not removed from the system (as this may result in data loss).
+The purpose of this protection is to ensure that in-use PersistentVolumeClaim API objects are not removed from the system (as this may result in data loss).


while a snapshot is being taken from it

msau42 · 2019-11-21T17:58:21Z

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

 ```

-### Class
+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.


volumeHandle

msau42 · 2019-11-21T17:58:53Z

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

-A VolumeSnapshotContent of a particular class can only be bound to VolumeSnapshots requesting
-that class. A VolumeSnapshotContent with no `snapshotClassName` has no class and can only be bound
-to VolumeSnapshots that request no particular class.
+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 physical volume snapshot resource on the storage system that this `VolumeSnapshotContent` represents.


snapshotHandle

"physical volume snapshot resource" => "CSI snapshot id"?

msau42 · 2019-11-21T17:59:48Z

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

-A VolumeSnapshotContent of a particular class can only be bound to VolumeSnapshots requesting
-that class. A VolumeSnapshotContent with no `snapshotClassName` has no class and can only be bound
-to VolumeSnapshots that request no particular class.
+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 physical volume snapshot resource on the storage system that this `VolumeSnapshotContent` represents.

 ## VolumeSnapshots


Should we move VolumeSnapshots section first since that's what users will mainly be interacting with?

msau42 · 2019-11-21T18:01:06Z

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

  source:
-    name: pvc-test
-    kind: PersistentVolumeClaim
+    persistentVolumeClaimName: pvc-test


I guess it's a little strange that not all the fields in the VolumeSnapshot are not explained, considering that this is the user-facing object. It feels inconsistent with the VolumeSnapshotContent object above that is very detailed but actually not really that important to the user.

xing-yang · 2019-11-22T03:16:42Z

@msau42 addressed your comments. PTAL. Thanks.

msau42 · 2019-11-22T06:00:23Z

/lgtm

xing-yang · 2019-11-22T06:34:35Z

@sftim Michelle has done technical review. Can you please merge this? Thanks.
@daminisatya

sftim · 2019-11-22T10:52:01Z

Happy for an approver to approve this & trigger a merge

daminisatya · 2019-11-22T17:03:38Z

@xing-yang There is still a conflicting file. Please resolve it, and I will go ahead and approve it.

xing-yang · 2019-11-22T17:27:28Z

Rebased.

daminisatya · 2019-11-22T17:28:38Z

/lgtm
/approve

k8s-ci-robot · 2019-11-22T17:29:03Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: daminisatya

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~content/en/OWNERS~~ [daminisatya]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

* feat: graduate TaintNodesByCondition to GA (#17073) * Promote StartupProbe to beta (enabled by default). (#17164) * Watch bookmarks to GA (#17026) * feat: graduate ScheduleDaemonSetPods to GA (#17350) * Update Docker installation instructions (#17405) * Use exact version numbers for installing Docker in Ubuntu (#17428) * Move CSIMigration and CSIMigrationGCE to Beta in Kubernetes v1.17 (#17478) * Promote NodeLease feature to GA (#17189) * Update docs for csi topology ga (#17408) * Update RunAsUsername to beta (#17460) * doc:Update RunAsUsername to beta * doc: update samples - kubernetes.io/os is no longer beta * Updating based on review feedback * Promote Node-specific volume limits to GA (#17432) * Promote PodShareProcessNamespace to stable (#17192) * Promote PodShareProcessNamespace to stable * Add for_k8s_version to feature-state label Co-Authored-By: Tim Bannister <tim@scalefactory.com> * Readd version-check to shareProcessNamespace task * Update service load balancer finalizer doc for GA (#17438) * Update Topology Manager docs (#17451) * Added information on how device plugins can take advantage of Topology Manager * Updated the Topology Manager documentation to include additionalinformation and update some out of date sections * Fix broken Topology Manager link (#17746) Part of What's Next Device Plugin section * Update CRD defaulting docs for GA (#17450) * Add documentation for VolumeSnapshot Beta (#17233) * Updating EndpointSlice documentation for beta release in 1.17 (#17411) * (docs/dualstack): v1.17 updates (#17457) * Add placehold doc updates for dualstack in 1.17 Signed-off-by: Lachlan Evenson <lachlan.evenson@microsoft.com> * Add Downward API and /etc/hosts Pod IP validation Signed-off-by: Lachlan Evenson <lachlan.evenson@microsoft.com> * remove addressed known issue via k/k pr 85246 Signed-off-by: Lachlan Evenson <lachlan.evenson@microsoft.com> * Remove known issue and add flag as part of k/k 79993 Signed-off-by: Lachlan Evenson <lachlan.evenson@microsoft.com> * remove follow up placeholders Signed-off-by: Lachlan Evenson <lachlan.evenson@microsoft.com> * Update verbiage Signed-off-by: Lachlan Evenson <lachlan.evenson@microsoft.com> * Make IP addressing consistent throughout the task Signed-off-by: Lachlan Evenson <lachlan.evenson@microsoft.com> * Update to status.podIPs Signed-off-by: Lachlan Evenson <lachlan.evenson@microsoft.com> * Update content/en/docs/tasks/network/validate-dual-stack.md Use set instead of env Co-Authored-By: Khaled Henidak (Kal) <khnidk@outlook.com> * add topology.kubernetes.io/zone, topology.kubernetes.io/region and node.kubernetes.io/instance-type labels to docs (#17498) Signed-off-by: Andrew Sy Kim <kiman@vmware.com> * Service topology alpha documentation (#17459) * Update list of feature flags for in-tree plugins migrated to CSI (#17533) Signed-off-by: Deep Debroy <ddebroy@docker.com> * Update Node concept for TaintNodesByCondition going GA (#17577) * feat: graduate ResourceQuotaScopeSelectors to GA in 1.17 (#17554) * kubeadm: update the upgrade documentation for 1.17 (#17587) * doc: Simplify Windows deployments with RuntimeClass (#16697) * doc: Simplify Windows deployments with RuntimeClass * Updating on review feedback * doc: Adding windows-build label from enhancement 1301 * update doc for kubelet option --reserved-cpus (#17648) * feat: update TaintNodesByCondition in feature gates table (#17377) * Update docs for v1 resource quota configuration (#17547) * AdmissionConfiguration v1 (#17548) * Update WebhookAdmissionConfiguration examples (#17549) * Update AWS EBS Migration Feature state (#16126) * Add resource version section to api-concepts documentation (#16910) * Add Resource Version semantics section to api concepts * Clarify risks of going back in time, add details about compaction and watch cache sizes * Apply suggestions from liggitt Co-Authored-By: Jordan Liggitt <jordan@liggitt.net> * remove pesudocode, apply feedback * Fix typo * Clarify equality rules * Cleanup kubectl generators docs (#17609) * Write ReplicationController without a space * Drop mentioning unsupported cluster versions * Fix capitalization for “API group” * Tweak wording * Avoid using deprecated generator in example * add Antrea description in dev-1.17 (#17919) * Promote VolumeSubpathEnvExpansion to GA * Reference Documentation for the Kubernetes API for 1.17 (#18019) * Update feature-gates.md (#18033) * Reference Documentation for kubectl Commands for 1.17 (#18017) * Update for v1.17 (#18034) * Update config.toml(release-1.17) for 1.17 (#18031)

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Oct 27, 2019

k8s-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. language/en Issues or PRs related to English language sig/docs Categorizes an issue or PR as relevant to SIG Docs. labels Oct 27, 2019

xing-yang changed the title ~~Add documentation for VolumeSnapshot Beta~~ WIP: Add documentation for VolumeSnapshot Beta Oct 27, 2019

k8s-ci-robot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Oct 27, 2019

k8s-ci-robot requested review from jsafrane and thockin October 27, 2019 16:47

xing-yang mentioned this pull request Oct 27, 2019

Snapshot / Restore Volume Support for Kubernetes (CRD + External Controller) kubernetes/enhancements#177

Closed

k8s-ci-robot added this to the 1.17 milestone Nov 4, 2019

sftim reviewed Nov 6, 2019

View reviewed changes

xing-yang force-pushed the dev-1.17 branch from 79b718f to 46f72a4 Compare November 11, 2019 03:03

xing-yang changed the title ~~WIP: Add documentation for VolumeSnapshot Beta~~ Add documentation for VolumeSnapshot Beta Nov 11, 2019

k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Nov 11, 2019

k8s-ci-robot assigned msau42 Nov 11, 2019

sftim reviewed Nov 11, 2019

View reviewed changes

xing-yang force-pushed the dev-1.17 branch from 46f72a4 to fbd0df6 Compare November 12, 2019 04:05

msau42 reviewed Nov 13, 2019

View reviewed changes

xing-yang force-pushed the dev-1.17 branch from fbd0df6 to 2925e6d Compare November 13, 2019 05:05

sftim reviewed Nov 14, 2019

View reviewed changes

xing-yang force-pushed the dev-1.17 branch from 2925e6d to ec2990d Compare November 14, 2019 18:07

msau42 reviewed Nov 21, 2019

View reviewed changes

xing-yang force-pushed the dev-1.17 branch from ec2990d to 5a37d55 Compare November 22, 2019 03:16

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Nov 22, 2019

Add documentation for VolumeSnapshot Beta

d36b480

xing-yang force-pushed the dev-1.17 branch from 5a37d55 to d36b480 Compare November 22, 2019 17:26

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Nov 22, 2019

k8s-ci-robot assigned daminisatya Nov 22, 2019

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Nov 22, 2019

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Nov 22, 2019

k8s-ci-robot merged commit 8798ce2 into kubernetes:dev-1.17 Nov 22, 2019

mrbobbytables pushed a commit that referenced this pull request Dec 6, 2019

Add documentation for VolumeSnapshot Beta (#17233)

38684c3

	This document describes the current state of `VolumeSnapshots` in Kubernetes. Familiarity with [persistent volumes](/docs/concepts/storage/persistent-volumes/) is suggested. `VolumeSnapshot` is introduced as an alpha feature in Kubernetes 1.12 and is promoted to beta in 1.17.
	In Kubernetes, a _VolumeSnapshot_ represents a snapshot of a storage volume. This document assumes that you are already familiar with Kubernetes [persistent volumes](/docs/concepts/storage/persistent-volumes/).

		@@ -12,7 +14,8 @@ weight: 20
		{{% capture overview %}}

		{{< feature-state for_k8s_version="v1.12" state="alpha" >}}

	For pre-provisioned snapshots, the admin is responsible for creating the `VolumeSnapshotContent` object.
	For pre-provisioned snapshots, you (as cluster administrator) are responsible for creating the `VolumeSnapshotContent` object.

		@@ -36,38 +39,36 @@ Users need to be aware of the following when using this feature:

		* API Objects `VolumeSnapshot`, `VolumeSnapshotContent`, and `VolumeSnapshotClass` are CRDs, not part of the core API.

	* The `VolumeSnapshot` v1beta CRDs need to be installed manually.
	* You need to manually install the `VolumeSnapshot` v1beta CRDs.

		### DeletionPolicy

		Volume snapshot classes have a deletionPolicy. It enables an admin to configure what happens to a `VolumeSnapshotContent` when the `VolumeSnapshot` object it is bound to is to be deleted. The deletionPolicy of a volume snapshot can either be `Retain` or `Delete`. This field must be specified.

		@@ -34,40 +36,38 @@ there is the `VolumeSnapshotClass` resource.

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

	`VolumeSnapshotClass` allows user to specify different attributes belonging to a `VolumeSnapshot`. These attibutes 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`.
	`VolumeSnapshotClass` allows you to specify different attributes belonging to a `VolumeSnapshot`. These attibutes 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`.

	Instead of a pre-existing snapshot, a user can request that a snapshot of a PVC is dynamically taken. The [VolumeSnapshotClass](/docs/concepts/storage/volume-snapshot-classes/) specifies storage provider-specific parameters to use when taking a snapshot.
	Instead of using a pre-existing snapshot, you can request that the cluster creates a snapshot of an existing PersistentVolumeClaim. The [VolumeSnapshotClass](/docs/concepts/storage/volume-snapshot-classes/) specifies storage provider-specific parameters to use when taking a snapshot.

	The purpose of the Persistent Volume Claim Object while a snapshot is being taken Protection feature is to ensure that in-use PVC API objects are not removed from the system (as this may result in data loss).
	Kubernetes protects PersistentVolumeClaim objects during snapshotting operations.


		If a PVC is in active use by a snapshot as a source to create the snapshot, the PVC is in-use. If a user deletes a PVC API object in active use as a snapshot source, the PVC object is not removed immediately. Instead, removal of the PVC object is postponed until the PVC is no longer actively used by any snapshots. A PVC is no longer used as a snapshot source when `ReadyToUse` of the snapshot `Status` becomes `true`.
		If a snapshot is being taken of a PVC, that PVC is in-use. If a user deletes a PVC API object in active use as a snapshot source, the PVC object is not removed immediately. Instead, removal of the PVC object is postponed until the snapshot is readyToUse or aborted.

	If a snapshot is being taken of a PVC, that PVC is in-use. If a user deletes a PVC API object in active use as a snapshot source, the PVC object is not removed immediately. Instead, removal of the PVC object is postponed until the snapshot is readyToUse or aborted.
	While a snapshot is being taken of a PVC, that PVC is in-use. If you delete a PersistentVolumeClaim that is in active use as a snapshot source, the PersistentVolumeClaim is not removed immediately. Instead, removal of the PVC object is postponed until the snapshot either becomes readyToUse or is aborted.

	Each VolumeSnapshotContent contains a spec and status. In dynamic provisioning, the `VolumeSnapshotContent` object is created by the snapshot common controller as follows.
	Each VolumeSnapshotContent contains a spec and status. In dynamic provisioning, the snapshot common controller creates `VolumeSnapshotContent` objects. Here's an example:


		The purpose of the Persistent Volume Claim Object in Use Protection feature is to ensure that in-use PVC API objects are not removed from the system (as this may result in data loss).
		The purpose of this protection is to ensure that in-use PersistentVolumeClaim API objects are not removed from the system (as this may result in data loss).

Add documentation for VolumeSnapshot Beta #17233

Add documentation for VolumeSnapshot Beta #17233

Conversation

xing-yang commented Oct 27, 2019

k8sio-netlify-preview-bot commented Oct 27, 2019 • edited Loading

makoscafee commented Nov 4, 2019

sftim left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

xing-yang commented Nov 11, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

xing-yang Nov 13, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sftim left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sftim commented Nov 14, 2019

xing-yang commented Nov 14, 2019 • edited Loading

daminisatya commented Nov 20, 2019

daminisatya commented Nov 20, 2019

sftim commented Nov 20, 2019

xing-yang commented Nov 20, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

k8sio-netlify-preview-bot commented Oct 27, 2019 •

edited

Loading

xing-yang Nov 13, 2019 •

edited

Loading

xing-yang commented Nov 14, 2019 •

edited

Loading