Add Documentation for Snapshot Feature (kubernetes#9948)

* Add documentation for snapshot feature

* Update volume-snapshots.md

content/en/docs/concepts/storage/persistent-volumes.md

@@ -630,6 +630,34 @@ Volume binding matrix for statically provisioned volumes:
 **Note:** Only statically provisioned volumes are supported for alpha release. Administrators should take care to consider these values when working with raw block devices.
 {{< /note >}}
 
+## Volume Snapshot and Restore Volume from Snapshot Support
+
+{{< feature-state for_k8s_version="v1.12" state="alpha" >}}
+
+Volume snapshot feature was added to support CSI Volume Plugins only. For details, see [volume snapshots](/docs/concepts/storage/volume-snapshots/).
+
+To enable support for restoring a volume from a volume snapshot data source, enable the
+`VolumeSnapshotDataSource` feature gate on the apiserver and controller-manager.
+
+### Create Persistent Volume Claim from Volume Snapshot
+```yaml
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: restore-pvc
+spec:
+  storageClassName: csi-hostpath-sc
+  dataSource:
+    name: new-snapshot-test
+    kind: VolumeSnapshot
+    apiGroup: snapshot.storage.k8s.io
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 10Gi
+```
+
 ## Writing Portable Configuration
 
 If you're writing configuration templates or examples that run on a wide range of clusters
@@ -657,4 +685,4 @@ and need persistent storage, we recommend that you use the following pattern:
   or the cluster has no storage system (in which case the user cannot deploy
   config requiring PVCs).
 
-{{% /capture %}}
+{{% /capture %}}

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

@@ -0,0 +1,64 @@
+---
+reviewers:
+- jsafrane
+- saad-ali
+- thockin
+- msau42
+title: Volume Snapshot Classes 
+content_template: templates/concept
+weight: 30
+---
+
+{{% capture overview %}}
+
+This document describes the concept of `VolumeSnapshotClass` in Kubernetes. Familiarity
+with [volume snapshots](/docs/concepts/storage/volume-snapshots/) and
+[storage classes](/docs/concepts/storage/storage-classes) is suggested.
+
+{{% /capture %}}
+
+{{< toc >}}
+
+{{% capture body %}}
+
+## Introduction
+
+Just like `StorageClass` provides a way for administrators to describe the "classes"
+of storage they offer when provisioning a volume, `VolumeSnapshotClass` provides a
+way to describe the "classes" of storage when provisioning a volume snapshot.
+
+## The VolumeSnapshotClass Resource
+
+Each `VolumeSnapshotClass` contains the fields `snapshotter` and `parameters`,
+which are used when a `VolumeSnapshot` belonging to the class needs to be
+dynamically provisioned.
+
+The name of a `VolumeSnapshotClass` object is significant, and is how users can
+request a particular class. Administrators set the name and other parameters
+of a class when first creating `VolumeSnapshotClass` objects, and the objects cannot
+be updated once they are created.
+
+Administrators can specify a default `VolumeSnapshotClass` just for VolumeSnapshots
+that don't request any particular class to bind to.
+
+```yaml
+apiVersion: snapshot.storage.k8s.io/v1alpha1
+kind: VolumeSnapshotClass
+metadata:
+  name: csi-hostpath-snapclass
+snapshotter: csi-hostpath
+parameters:
+```
+
+### Snapshotter
+
+Volume snapshot classes have a snapshotter that determines what CSI volume plugin is
+used for provisioning VolumeSnapshots. 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`.
+
+{{% /capture %}}

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

@@ -0,0 +1,120 @@
+---
+reviewers:
+- jsafrane
+- saad-ali
+- thockin
+- msau42
+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.
+
+{{% /capture %}}
+
+{{< toc >}}
+
+{{% capture body %}}
+
+## Introduction
+
+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.
+
+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. 
+
+A `VolumeSnapshot` is a request for snapshot of a volume by a user. It is similar to a PersistentVolumeClaim.
+
+While `VolumeSnapshots` allow a user to consume abstract storage resources, cluster administrators
+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.
+
+
+## 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.
+
+#### 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
+[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.
+
+VolumeSnapshots will remain unbound indefinitely if a matching VolumeSnapshotContent does not exist. VolumeSnapshots will be bound as matching VolumeSnapshotContents become available.
+
+### Delete
+
+Deletion removes both the `VolumeSnapshotContent` object from the Kubernetes API, as well as the associated storage asset in the external infrastructure.
+
+## Volume Snapshot Contents
+
+Each VolumeSnapshotContent contains a spec, which is the specification of the volume snapshot.
+
+```yaml
+apiVersion: snapshot.storage.k8s.io/v1alpha1
+kind: VolumeSnapshotContent
+metadata:
+  name: new-snapshot-content-test
+spec:
+  snapshotClassName: csi-hostpath-snapclass
+  source:
+    name: pvc-test 
+    kind: PersistentVolumeClaim
+  volumeSnapshotSource:
+    csiVolumeSnapshotSource:
+      creationTime:    1535478900692119403
+      driver:          csi-hostpath
+      restoreSize:     10Gi
+      snapshotHandle:  7bdd0de3-aaeb-11e8-9aae-0242ac110002
+```
+
+### Class
+
+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.
+
+## 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
+kind: VolumeSnapshot
+metadata:
+  name: new-snapshot-test
+spec:
+  snapshotClassName: csi-hostpath-snapclass
+  source:
+    name: pvc-test
+    kind: PersistentVolumeClaim
+```
+
+### 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.
+
+{{% /capture %}}