Add documentation for VolumeSnapshot Beta

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

@@ -1,9 +1,11 @@
 ---
 reviewers:
-- jsafrane
 - saad-ali
 - thockin
 - msau42
+- jingxu97
+- xing-yang
+- yuxiangqian
 title: Volume Snapshot Classes
 content_template: templates/concept
 weight: 30
@@ -28,7 +30,7 @@ way to describe the "classes" of storage when provisioning a volume snapshot.
 
 ## The VolumeSnapshotClass Resource
 
-Each `VolumeSnapshotClass` contains the fields `snapshotter` and `parameters`,
+Each `VolumeSnapshotClass` contains the fields `driver`, `deletionPolicy`, and `parameters`,
 which are used when a `VolumeSnapshot` belonging to the class needs to be
 dynamically provisioned.
 
@@ -41,23 +43,28 @@ Administrators can specify a default `VolumeSnapshotClass` just for VolumeSnapsh
 that don't request any particular class to bind to.
 
 ```yaml
-apiVersion: snapshot.storage.k8s.io/v1alpha1
+apiVersion: snapshot.storage.k8s.io/v1beta1
 kind: VolumeSnapshotClass
 metadata:
   name: csi-hostpath-snapclass
-snapshotter: csi-hostpath
+driver: hostpath.csi.k8s.io 
+deletionPolicy: Delete
 parameters:
 ```
 
-### Snapshotter
+### Driver
 
-Volume snapshot classes have a snapshotter that determines what CSI volume plugin is
+Volume snapshot classes have a driver that determines what CSI volume plugin is
 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.
+
 ## Parameters
 
 Volume snapshot classes have parameters that describe volume snapshots belonging to
 the volume snapshot class. Different parameters may be accepted depending on the
-`snapshotter`.
+`driver`.
 
 {{% /capture %}}

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

@@ -1,9 +1,11 @@
 ---
 reviewers:
-- jsafrane
 - saad-ali
 - thockin
 - msau42
+- jingxu97
+- xing-yang
+- yuxiangqian
 title: Volume Snapshots
 content_template: templates/concept
 weight: 20
@@ -12,7 +14,8 @@ weight: 20
 {{% capture overview %}}
 
 {{< 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/).
 
 {{% /capture %}}
 
@@ -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.
 * `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.
-* 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.
+* The `VolumeSnapshot` v1beta CRDs need to be installed manually.
 
 ## Lifecycle of a volume snapshot and volume snapshot content
 
 `VolumeSnapshotContents` are resources in the cluster. `VolumeSnapshots` are requests for those resources. The interaction between `VolumeSnapshotContents` and `VolumeSnapshots` follow this lifecycle:
 
 ### Provisioning Volume Snapshot
 
-There are two ways snapshots may be provisioned: statically or dynamically.
+There are two ways snapshots may be provisioned: pre-provisioned or dynamically provisioned.
 
-#### Static
+#### Pre-provisioned {#static}
 A cluster administrator creates a number of `VolumeSnapshotContents`. They carry the details of the real storage which is available for use by cluster users. They exist in the Kubernetes API and are available for consumption.
 
 #### Dynamic
-When none of the static `VolumeSnapshotContents` the administrator created matches a user's `VolumeSnapshot`,
-the cluster may try to dynamically provision a volume snapshot specially for the `VolumeSnapshot` object.
-This provisioning is based on `VolumeSnapshotClasses`: the `VolumeSnapshot` must request a
+The dynamic provisioning is based on `VolumeSnapshotClasses`: the `VolumeSnapshot` must request a
 [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.
 
-### Persistent Volume Claim in Use Protection
+### Persistent Volume Claim as Snapshot Source Protection
 
-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 as Snapshot Source Protection feature is to ensure that in-use PVC API objects are not removed from the system (as this may result in data loss).
 
 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`.
 
@@ -77,58 +78,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.
 
 ```yaml
-apiVersion: snapshot.storage.k8s.io/v1alpha1
+apiVersion: snapshot.storage.k8s.io/v1beta1
 kind: VolumeSnapshotContent
 metadata:
-  name: new-snapshot-content-test
+  name: snapcontent-72d9a349-aacd-42d2-a240-d775650d2455
 spec:
-  snapshotClassName: csi-hostpath-snapclass
+  deletionPolicy: Delete
+  driver: hostpath.csi.k8s.io
   source:
-    name: pvc-test
-    kind: PersistentVolumeClaim
-  volumeSnapshotSource:
-    csiVolumeSnapshotSource:
-      creationTime:    1535478900692119403
-      driver:          csi-hostpath
-      restoreSize:     10Gi
-      snapshotHandle:  7bdd0de3-aaeb-11e8-9aae-0242ac110002
+    volumeHandle: ee0cfb94-f8d4-11e9-b2d8-0242ac110002
+  volumeSnapshotClassName: csi-hostpath-snapclass
+  volumeSnapshotRef:
+    name: new-snapshot-test
+    namespace: default
+    uid: 72d9a349-aacd-42d2-a240-d775650d2455
 ```
 
-### Class
+For pre-provisioned snapshots, the admin is responsible for creating the `VolumeSnapshotContent` object.
 
-A VolumeSnapshotContent can have a class, which is specified by setting the
-`snapshotClassName` attribute to the name of a
-[VolumeSnapshotClass](/docs/concepts/storage/volume-snapshot-classes/).
-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.
+```yaml
+apiVersion: snapshot.storage.k8s.io/v1beta1
+kind: VolumeSnapshotContent
+metadata:
+  name: new-snapshot-content-test
+spec:
+  deletionPolicy: Delete
+  driver: hostpath.csi.k8s.io
+  source:
+    snapshotHandle: 7bdd0de3-aaeb-11e8-9aae-0242ac110002
+  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.
 
 ```yaml
-apiVersion: snapshot.storage.k8s.io/v1alpha1
+apiVersion: snapshot.storage.k8s.io/v1beta1
 kind: VolumeSnapshot
 metadata:
   name: new-snapshot-test
 spec:
-  snapshotClassName: csi-hostpath-snapclass
+  volumeSnapshotClassName: csi-hostpath-snapclass
   source:
-    name: pvc-test
-    kind: PersistentVolumeClaim
+    persistentVolumeClaimName: pvc-test
 ```
 
 ### Class
 
 A volume snapshot can request a particular class by specifying the name of a
 [VolumeSnapshotClass](/docs/concepts/storage/volume-snapshot-classes/)
-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`.
 
 ## Provisioning Volumes from Snapshots