Update README

Author: xing-yang

README.md

@@ -2,12 +2,19 @@
 
 The CSI external-snapshotter is part of Kubernetes implementation of [Container Storage Interface (CSI)](https://github.com/container-storage-interface/spec).
 
-The volume snapshot feature supports CSI v1.0 and it has been an Alpha feature in Kubernetes since v1.12.
+The volume snapshot feature supports CSI v1.0 and higher. It was introduced as an Alpha feature in Kubernetes v1.12 and has been promoted to an Beta feature in Kubernetes 1.17.
 
 ## Overview
 
 CSI Snapshotter is an external controller that watches Kubernetes Snapshot CRD objects and triggers CreateSnapshot/DeleteSnapshot against a CSI endpoint. Full design can be found at Kubernetes proposal at [here](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/storage/csi-snapshot.md)
 
+With the promotion of Volume Snapshot to beta, the feature is now enabled by default on standard Kubernetes deployments instead of being opt-in.
+
+The move of the Kubernetes Volume Snapshot feature to beta also means:
+* A revamp of volume snapshot APIs.
+* The CSI external-snapshotter sidecar is split into two controllers, a common snapshot controller and a CSI external-snapshotter sidecar.
+
+
 ## Design
 
 External snapshotter follows [controller](https://github.com/kubernetes/community/blob/master/contributors/devel/controllers.md) pattern and uses informers to watch for `VolumeSnapshot` and `VolumeSnapshotContent` create/update/delete events. It filters out these objects with `Snapshotter==<CSI driver name>` specified in the associated VolumeSnapshotClass object and then processes these events in workqueues with exponential backoff.
@@ -30,23 +37,30 @@ Snapshotter talks to CSI over socket (/run/csi/socket by default, configurable b
   * If the `VolumeSnapshotRef` is set to nil, skip this content since it is not bound to any snapshot object.
   * Otherwise, the controller verifies whether the content object is correctly bound to a snapshot object. In case the `VolumeSnapshotRef.UID` is set but it does not match its snapshot object or snapshot no long exists, the content object and its associated snapshot will be deleted.
 
-## Usage
+## Deployment
 
-### Running on command line
+The Volume Snapshot feature now depends on a new, common volume snapshot controller in addition to the volume snapshot CRDs. Both the volume snapshot controller and the CRDs are independent of any CSI driver. Regardless of the number CSI drivers deployed on the cluster, there must be only one instance of the volume snapshot controller running and one set of volume snapshot CRDs installed per cluster.
 
-For debugging, it is possible to run snapshotter on command line. For example,
+Therefore, it is strongly recommended that Kubernetes distributors bundle and deploy the controller and CRDs as part of their Kubernetes cluster management process (independent of any CSI Driver).
 
-```bash
-csi-snapshotter -kubeconfig ~/.kube/config -v 5 -csi-address /run/csi/socket
-```
+If your cluster does not come pre-installed with the correct components, you may manually install these components by executing the following steps.
 
-### Running in a statefulset
+Install Snapshot Beta CRDs:
+* kubectl create -f config/crd
+* https://github.com/kubernetes-csi/external-snapshotter/tree/master/config/crd
+* Do this once per cluster
 
-It is necessary to create a new service account and give it enough privileges to run the snapshotter. We provide .yaml files that deploy for use together with the hostpath example driver. A real production deployment must customize them:
+Install Common Snapshot Controller:
+* kubectl create -f deploy/kubernetes/snapshot-controller
+* https://github.com/kubernetes-csi/external-snapshotter/tree/master/deploy/kubernetes/snapshot-controller
+* Do this once per cluster
+
+Install CSI Driver:
+* Follow instructions provided by your CSI Driver vendor.
+* Here is an example to install the sample hostpath CSI driver
+  * kubectl create -f deploy/kubernetes/csi-snapshotter
+  * https://github.com/kubernetes-csi/external-snapshotter/tree/master/deploy/kubernetes/csi-snapshotter
 
-```bash
-for i in $(find deploy/kubernetes -name '*.yaml'); do kubectl create -f $i; done
-```
 
 ### Running with Leader Election
 
@@ -55,12 +69,24 @@ If you want to run external-snapshotter with higher availability, you can enable
 --leader-election=true
 ```
 
+### Upgrade from Alpha to Beta
+
+The change from Alpha to Beta snapshot APIs is not backward compatible.
+
+If you have already deployed Alpha snapshot APIs and controller and want to upgrade to Beta, you need to do the following:
+* Delete snapshots created using Alpha snapshot CRDs and controller.
+* Uninstall Alpha snapshot CRDs, controller, and CSI driver.
+* Install Beta snapshot CRDs, controller, and CSI driver.
+
+
 ## Testing
 
 Running Unit Tests:
 
 ```bash
-go test -timeout 30s  github.com/kubernetes-csi/external-snapshotter/pkg/controller
+go test -timeout 30s  github.com/kubernetes-csi/external-snapshotter/pkg/common-controller
+
+go test -timeout 30s  github.com/kubernetes-csi/external-snapshotter/pkg/sidecar-controller
 ```
 
 ## Dependency Management