Merge pull request #260 from xing-yang/snapshot_beta

k8s-ci-robot · web-flow · commit 1f7dce85bf59 · 2020-02-10T09:11:55.000-08:00
Update snapshot docs for beta
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
@@ -3,6 +3,8 @@
 - [Introduction](introduction.md)
 - [Developing a CSI Driver for Kubernetes](developing.md)
     - [Kubernetes Changelog](kubernetes-changelog.md)
+    - [Kubernetes Cluster Controllers](kubernetes-cluster-controllers.md)
+        - [Snapshot Controller](snapshot-controller.md)
     - [Sidecar Containers](sidecar-containers.md)
         - [Kubernetes Compatibility](kubernetes-compatibility.md)
         - [external-attacher](external-attacher.md)
diff --git a/book/src/external-snapshotter.md b/book/src/external-snapshotter.md
@@ -4,34 +4,61 @@
 
 **Git Repository:** [https://github.com/kubernetes-csi/external-snapshotter](https://github.com/kubernetes-csi/external-snapshotter)
 
-**Status:** Alpha
+**Status:** v2.0.0 and higher is Beta; version below v2.0.0 is Alpha
+
+### CSI External-Snapshotter Sidecar
 
 Latest stable release | Branch | Min CSI Version | Max CSI Version | Container Image | Min K8s Version | Max K8s Version | Recommended K8s Version
 --|--|--|--|--|--|--|--
-[external-snapshotter v1.2.2](https://github.com/kubernetes-csi/external-snapshotter/releases/tag/v1.2.2) | [release-1.2](https://github.com/kubernetes-csi/external-snapshotter/tree/release-1.2) | [v1.0.0](https://github.com/container-storage-interface/spec/releases/tag/v1.0.0) | - | quay.io/k8scsi/csi-snapshotter:v1.2.2 | v1.13 | - | v1.14
-[external-snapshotter v0.4.1](https://github.com/kubernetes-csi/external-snapshotter/releases/tag/v0.4.1) | [release-0.4](https://github.com/kubernetes-csi/external-snapshotter/tree/release-0.4) | [v0.3.0](https://github.com/container-storage-interface/spec/releases/tag/v0.3.0) | [v0.3.0](https://github.com/container-storage-interface/spec/releases/tag/v0.3.0) | quay.io/k8scsi/csi-snapshotter:v0.4.1 | v1.10 | -v1.16 | v1.10
+[external-snapshotter v2.0.1](https://github.com/kubernetes-csi/external-snapshotter/releases/tag/v2.0.1) | [release-2.0](https://github.com/kubernetes-csi/external-snapshotter/tree/release-2.0) | [v1.0.0](https://github.com/container-storage-interface/spec/releases/tag/v1.0.0) | - | quay.io/k8scsi/csi-snapshotter:v2.0.1 | v1.17 | - | v1.17
+[external-snapshotter v1.2.2](https://github.com/kubernetes-csi/external-snapshotter/releases/tag/v1.2.2) | [release-1.2](https://github.com/kubernetes-csi/external-snapshotter/tree/release-1.2) | [v1.0.0](https://github.com/container-storage-interface/spec/releases/tag/v1.0.0) | - | quay.io/k8scsi/csi-snapshotter:v1.2.2 | v1.13 | v1.16 | v1.14
+[external-snapshotter v0.4.2](https://github.com/kubernetes-csi/external-snapshotter/releases/tag/v0.4.2) | [release-0.4](https://github.com/kubernetes-csi/external-snapshotter/tree/release-0.4) | [v0.3.0](https://github.com/container-storage-interface/spec/releases/tag/v0.3.0) | [v0.3.0](https://github.com/container-storage-interface/spec/releases/tag/v0.3.0) | quay.io/k8scsi/csi-snapshotter:v0.4.2 | v1.12 | v1.16 | v1.12
 
 Definitions of the min/max/recommended Kubernetes versions can be found on the
 [sidecar page](sidecar-containers.md#versioning)
 
-## Description
+To use the snapshot beta feature, a snapshot controller is also required. For more information, see [this snapshot-controller page](snapshot-controller.md).
 
-The CSI `external-snapshotter` is a sidecar container that watches the Kubernetes API server for `VolumeSnapshot` and `VolumeSnapshotContent` CRD objects.
+## Snapshot Beta
 
-The creation of a new `VolumeSnapshot` object referencing a `SnapshotClass` CRD object corresponding to this driver causes the sidecar container to trigger a `CreateSnapshot` operation against the specified CSI endpoint to provision a new snapshot. When a new snapshot is successfully provisioned, the sidecar container creates a Kubernetes `VolumeSnapshotContent` object to represent the new snapshot.
+### Description
 
-The deletion of a `VolumeSnapshot` object bound to a `VolumeSnapshotContent` corresponding to this driver with a `delete` reclaim policy causes the sidecar container to trigger a `DeleteSnapshot` operation against the specified CSI endpoint to delete the snapshot. Once the snapshot is successfully deleted, the sidecar container also deletes the `VolumeSnapshotContent` object representing the snapshot.
+In the Beta version, the snapshot controller will be watching the Kubernetes API server for `VolumeSnapshot` and `VolumeSnapshotContent` CRD objects. The CSI `external-snapshotter` sidecar only watches the Kubernetes API server for `VolumeSnapshotContent` CRD objects. The CSI `external-snapshotter` sidecar is also responsible for calling the CSI RPCs CreateSnapshot, DeleteSnapshot, and ListSnapshots.
+
+For detailed snapshot beta design changes, see the design doc [here](https://github.com/kubernetes/enhancements/blob/master/keps/sig-storage/20190709-csi-snapshot.md).
 
 For detailed information about volume snapshot and restore functionality, see [Volume Snapshot & Restore](snapshot-restore-feature.md).
 
-## Usage
+### Usage
+
+CSI drivers that support provisioning volume snapshots and the ability to provision new volumes using those snapshots should use this sidecar container, and advertise the CSI `CREATE_DELETE_SNAPSHOT` controller capability.
+
+For detailed information (binary parameters, RBAC rules, etc.), see [https://github.com/kubernetes-csi/external-snapshotter/blob/release-2.0/README.md](https://github.com/kubernetes-csi/external-snapshotter/blob/release-2.0/README.md).
+
+### Deployment
+
+The CSI `external-snapshotter` is deployed as a sidecar controller. See [deployment section](deploying.md) for more details.
+
+For an example deployment, see [this example](https://github.com/kubernetes-csi/external-snapshotter/tree/release-2.0/deploy/kubernetes/setup-csi-snapshotter.yaml) which deploys `external-snapshotter` and `external-provisioner` with the Hostpath CSI driver.
+
+## Snapshot Alpha
+
+### Description
+
+The CSI `external-snapshotter` is a sidecar container that watches the Kubernetes API server for `VolumeSnapshot` and `VolumeSnapshotContent` CRD objects.
+
+The creation of a new `VolumeSnapshot` object referencing a `SnapshotClass` CRD object corresponding to this driver causes the sidecar container to trigger a `CreateSnapshot` operation against the specified CSI endpoint to provision a new snapshot. When a new snapshot is successfully provisioned, the sidecar container creates a Kubernetes `VolumeSnapshotContent` object to represent the new snapshot.
+
+The deletion of a `VolumeSnapshot` object bound to a `VolumeSnapshotContent` corresponding to this driver with a `delete` deletion policy causes the sidecar container to trigger a `DeleteSnapshot` operation against the specified CSI endpoint to delete the snapshot. Once the snapshot is successfully deleted, the sidecar container also deletes the `VolumeSnapshotContent` object representing the snapshot.
+
+### Usage
 
 CSI drivers that support provisioning volume snapshots and the ability to provision new volumes using those snapshots should use this sidecar container, and advertise the CSI `CREATE_DELETE_SNAPSHOT` controller capability.
 
-For detailed information (binary parameters, RBAC rules, etc.), see [https://github.com/kubernetes-csi/external-snapshotter/blob/master/README.md](https://github.com/kubernetes-csi/external-snapshotter/blob/master/README.md).
+For detailed information (binary parameters, RBAC rules, etc.), see [https://github.com/kubernetes-csi/external-snapshotter/blob/release-1.2/README.md](https://github.com/kubernetes-csi/external-snapshotter/blob/release-1.2/README.md).
 
-## Deployment
+### Deployment
 
 The CSI `external-snapshotter` is deployed as a controller. See [deployment section](deploying.md) for more details.
 
-For an example deployment, see [this example](https://github.com/kubernetes-csi/external-snapshotter/blob/release-1.2/deploy/kubernetes/setup-csi-snapshotter.yaml) which deploys `external-snapshotter` and `external-provisioner` with the Hostpath CSI driver.
+For an example deployment, see [this example](https://github.com/kubernetes-csi/external-snapshotter/tree/release-1.2/deploy/kubernetes/setup-csi-snapshotter.yaml) which deploys `external-snapshotter` and `external-provisioner` with the Hostpath CSI driver.
diff --git a/book/src/kubernetes-cluster-controllers.md b/book/src/kubernetes-cluster-controllers.md
@@ -0,0 +1,7 @@
+# Kubernetes Cluster Controllers
+
+The Kubernetes cluster controllers are responsible for managing snapshot objects and operations across multiple CSI drivers, so they should be bundled and deployed by the Kubernetes distributors as part of their Kubernetes cluster management process (independent of any CSI Driver).
+
+The Kubernetes development team maintains the following Kubernetes cluster controllers:
+
+* [snapshot-controller](snapshot-controller.md)
diff --git a/book/src/snapshot-controller.md b/book/src/snapshot-controller.md
@@ -0,0 +1,51 @@
+# Snapshot Controller
+
+## Status and Releases
+
+**Git Repository:** [https://github.com/kubernetes-csi/external-snapshotter](https://github.com/kubernetes-csi/external-snapshotter)
+
+**Status:** v2.0.0 and higher is Beta
+
+### Snapshot Controller
+
+When Volume Snapshot is promoted to Beta in Kubernetes 1.17, the CSI external-snapshotter sidecar controller is split into two controllers: a snapshot-controller and a CSI external-snapshotter sidecar. See the following table for snapshot-controller release information.
+
+Latest stable release | Branch | Min CSI Version | Max CSI Version | Container Image | Min K8s Version | Max K8s Version | Recommended K8s Version
+--|--|--|--|--|--|--|--
+[external-snapshotter v2.0.1](https://github.com/kubernetes-csi/external-snapshotter/releases/tag/v2.0.1) | [release-2.0](https://github.com/kubernetes-csi/external-snapshotter/tree/release-2.0) | [v1.0.0](https://github.com/container-storage-interface/spec/releases/tag/v1.0.0) | - | quay.io/k8scsi/snapshot-controller:v2.0.1 | v1.17 | - | v1.17
+
+For more information on the beta version of the CSI external-snapshotter sidecar, see [this external-snapshotter page](external-snapshotter.md).
+
+## Description
+
+In the Beta version, the snapshot controller will be watching the Kubernetes API server for `VolumeSnapshot` and `VolumeSnapshotContent` CRD objects. The CSI `external-snapshotter` sidecar only watches the Kubernetes API server for `VolumeSnapshotContent` CRD objects. The snapshot controller will be creating the `VolumeSnapshotContent` CRD object which triggers the CSI `external-snapshotter` sidecar to create a snapshot on the storage system.
+
+For detailed snapshot beta design changes, see the design doc [here](https://github.com/kubernetes/enhancements/blob/master/keps/sig-storage/20190709-csi-snapshot.md).
+
+For detailed information about volume snapshot and restore functionality, see [Volume Snapshot & Restore](snapshot-restore-feature.md).
+
+For detailed information (binary parameters, RBAC rules, etc.), see [https://github.com/kubernetes-csi/external-snapshotter/blob/release-2.0/README.md](https://github.com/kubernetes-csi/external-snapshotter/blob/release-2.0/README.md).
+
+## Deployment
+
+Kubernetes distributors should bundle and deploy the controller and CRDs as part of their Kubernetes cluster management process (independent of any CSI Driver).
+
+If your cluster does not come pre-installed with the correct components, you may manually install these components by executing the following steps.
+
+Install Snapshot Beta CRDs per cluster:
+
+```
+kubectl create -f  https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/release-2.0/config/crd/snapshot.storage.k8s.io_volumesnapshotclasses.yaml
+
+kubectl create -f  https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/release-2.0/config/crd/snapshot.storage.k8s.io_volumesnapshotcontents.yaml
+
+kubectl create -f  https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/release-2.0/config/crd/snapshot.storage.k8s.io_volumesnapshots.yaml
+```
+
+Install Snapshot Controller per cluster:
+
+```
+kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/release-2.0/deploy/kubernetes/snapshot-controller/rbac-snapshot-controller.yaml
+
+kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/release-2.0/deploy/kubernetes/snapshot-controller/setup-snapshot-controller.yaml
+```
diff --git a/book/src/snapshot-restore-feature.md b/book/src/snapshot-restore-feature.md
