Merge pull request #86 from davidz627/fix/docs

Revised documentation. Made versioning more clear. Made distinction between installation and examples more clear.

Author: k8s-ci-robot

OWNERS

@@ -6,4 +6,5 @@ reviewers:
   - jingxu97
 approvers:
   - davidz627
-  - saad-ali
+  - saad-ali
+  - msau42

README.md

@@ -15,41 +15,115 @@ The GCP Compute Persistent Disk CSI Driver is a
 Specification compliant driver used by Container Orchestrators to manage the
 lifecycle of Google Compute Engine Persistent Disks.
 
-## Installing
-### Kubernetes
-Templates and further information for installing this driver on Kubernetes are
-in [`./deploy/kubernetes/README.md`](deployREADME)
+## Project Status
+Status: Alpha
+Latest image: `gcr.io/google-containers/volume-csi/gcp-compute-persistent-disk-csi-driver:v0.1.0.alpha`
 
-## Development
+### CSI Compatibility
+This plugin is compatible with CSI versions v0.2.0 and v0.3.0
 
-###Manual
+### Kubernetes Compatibility
+This plugin can be used as-is beginning with Kubernetes v1.10.5
 
-Setup [GCP service account first](deployREADME) (one time step)
+### Known Issues
+See Github [Issues](https://github.com/kubernetes-sigs/gcp-compute-persistent-disk-csi-driver/issues)
 
-To bring up developed drivers:
+## Plugin Features
+### CreateVolume Parameters
+| Parameter          | Values               | Default     | Description                                                                                                                 |
+|--------------------|----------------------|-------------|-----------------------------------------------------------------------------------------------------------------------------|
+| "type"             | pd-ssd | pd-standard | pd-standard | Type allows you to choose between standard Persistent Disks  or Solid State Drive Persistent Disks                          |
+| "replication-type" | none | regional-pd   | none        | Replication type allows you to choose between standard zonal Persistent Disks or highly available Regional Persistent Disks |
+
+### Future Features
+See Github [Issues](https://github.com/kubernetes-sigs/gcp-compute-persistent-disk-csi-driver/issues)
+
+### Topology
+This driver supports only one topology key:
+`com.google.topology/zone`
+that represents availability by zone.
+
+## Kubernetes User Guide
+### Install Driver
+1. [One-time per project] Create GCP service account for the CSI driver and set required roles
+```
+PROJECT=your-project-here                       # GCP project
+GCE_PD_SA_NAME=my-gce-pd-csi-sa                 # Name of the service account to create
+GCE_PD_SA_DIR=/my/safe/credentials/directory    # Directory to save the service account key
+./deploy/setup-project.sh
+```
+
+2. Deploy driver to Kubernetes Cluster
+```
+GCE_PD_SA_DIR=/my/safe/credentials/directory    # Directory to get the service account key
+GCE_PD_DRIVER_VERSION=stable                    # Driver version to deploy
+./deploy/kubernetes/deploy-driver.sh
+```
+
+### Zonal Example
+1. Create example Zonal Storage Class
+```
+kubectl apply -f ./examples/kubernetes/demo-zonal-sc.yaml
+```
+
+2. Create example PVC and Pod
+```
+kubectl apply -f ./examples/kubernetes/demo-pod.yaml
+```
+
+3. Verify PV is created and bound to PVC
+```
+$ kubectl get pvc
+NAME      STATUS    VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   AGE
+podpvc     Bound     pvc-e36abf50-84f3-11e8-8538-42010a800002   10Gi       RWO            csi-gce-pd     9s
 ```
+
+4. Verify pod is created and in `RUNNING` state (it may take a few minutes to get to running state)
+```
+NAME                      READY     STATUS    RESTARTS   AGE
+web-server                1/1       Running   0          1m
+```
+
+## Kubernetes Development
+
+### Manual
+To build and install a development version of the driver:
+```
+$ GCE_PD_CSI_STAGING_IMAGE=gcr.io/path/to/driver/image:dev   # Location to push dev image to
 $ make push-container
+
+# Modify controller.yaml and node.yaml in ./deploy/kubernetes/dev to use dev image
+GCE_PD_DRIVER_VERSION=dev
 $ ./deploy/kubernetes/deploy-driver.sh
 ```
 
-To bring down drivers:
+To bring down driver:
 ```
 $ ./deploy/kubernetes/delete-driver.sh
 ```
 
 ## Testing
-Unit tests in `_test` files in the same package as the functions tested.
+Running E2E Tests:
+```
+PROJECT=my-project                               # GCP Project to run tests in
+[email protected]  # Existing IAM Account with GCE PD CSI Driver Permissions
+./test/run-e2e-local.sh
+```
 
-Sanity and E2E tests can be found in `./test/` and more detailed testing
-information is in [`./test/README.md`](testREADME)
+Running Sanity Tests:
+```
+./test/run-sanity.sh
+```
+
+Running Unit Tests:
+```
+./test/run-unit.sh
+```
 
 ## Dependency Management
 Use [dep](https://github.com/golang/dep)
 ```
 $ dep ensure
 ```
 
-To modify dependencies or versions change `./Gopkg.toml`
-
-[deployREADME]: deploy/kubernetes/README.md
-[testREADME]: test/README.md
+To modify dependencies or versions change `./Gopkg.toml`

deploy/common.sh

@@ -1,4 +1,18 @@
+#!/bin/bash
+
+# Common functions
+
+function ensure_var(){
+    if [[ -v "${1}" ]];
+    then
+        echo "${1} is ${!1}"
+    else
+        echo "${1} is unset"
+        exit 1
+    fi
+}
+
 function get_needed_roles()
 {
 	echo "roles/compute.storageAdmin roles/iam.serviceAccountUser projects/${PROJECT}/roles/gcp_compute_persistent_disk_csi_driver_custom_role"
-}
+}

deploy/kubernetes/README.md

@@ -2,16 +2,21 @@
 
 # This script will remove the GCP Compute Persistent Disk CSI Driver from the
 # currently available Kubernetes cluster
+#
+# Args:
+# GCE_PD_DRIVER_VERSION: The version of the GCE PD CSI Driver to deploy. Can be one of {v0.1.0, latest}
 
 set -o nounset
 set -o errexit
 
 readonly PKGDIR="${GOPATH}/src/sigs.k8s.io/gcp-compute-persistent-disk-csi-driver"
-readonly KUBEDEPLOY="${PKGDIR}/deploy/kubernetes"
+source "${PKGDIR}/deploy/common.sh"
+
+ensure_var GCE_PD_DRIVER_VERSION
+
+readonly KUBEDEPLOY="${PKGDIR}/deploy/kubernetes/${GCE_PD_DRIVER_VERSION}"
 
 kubectl delete -f "${KUBEDEPLOY}/node.yaml" --ignore-not-found
 kubectl delete -f "${KUBEDEPLOY}/controller.yaml" --ignore-not-found
-kubectl delete -f "${KUBEDEPLOY}/zonal-sc.yaml" --ignore-not-found
-kubectl delete -f "${KUBEDEPLOY}/regional-sc.yaml" --ignore-not-found
 kubectl delete -f "${KUBEDEPLOY}/setup-cluster.yaml" --ignore-not-found
 kubectl delete secret cloud-sa --ignore-not-found

deploy/kubernetes/delete-driver.sh

@@ -9,14 +9,18 @@
 
 # Args:
 # GCE_PD_SA_DIR: Directory the service account key has been saved in (generated by setup-project.sh)
+# GCE_PD_DRIVER_VERSION: The version of the GCE PD CSI Driver to deploy. Can be one of {stable, dev}
 
 set -o nounset
 set -o errexit
 
 readonly PKGDIR="${GOPATH}/src/sigs.k8s.io/gcp-compute-persistent-disk-csi-driver"
-readonly KUBEDEPLOY="${PKGDIR}/deploy/kubernetes"
+source "${PKGDIR}/deploy/common.sh"
 
-. $(dirname $0)/../common.sh
+ensure_var GCE_PD_SA_DIR
+ensure_var GCE_PD_DRIVER_VERSION
+
+readonly KUBEDEPLOY="${PKGDIR}/deploy/kubernetes/${GCE_PD_DRIVER_VERSION}"
 
 function check_service_account()
 {
@@ -57,6 +61,5 @@ then
 fi
 
 kubectl apply -f "${KUBEDEPLOY}/setup-cluster.yaml"
-kubectl apply -f "${KUBEDEPLOY}/zonal-sc.yaml"
 kubectl apply -f "${KUBEDEPLOY}/node.yaml"
 kubectl apply -f "${KUBEDEPLOY}/controller.yaml"

deploy/kubernetes/deploy-driver.sh

@@ -0,0 +1,15 @@
+WARNING: DO NOT USE THE STAGING-LATEST VERSION OF THE DRIVER FOR PRODUCTION
+DISCLAIMER: THE LATEST IMAGE IS CONSTANTLY CHANGING WITH DEVELOPMENT AND CAN BE
+BROKEN AT ANY TIME
+
+This is the absolute cutting edge development Driver, it is intended for testing
+and development only and can have vast differences in
+functionality/behavior/configuration. Use only to try the newest features that
+are not guaranteed to work yet.
+
+APPROXIMATE CHANGELOG in latest:
+* Topology
+* RePD
+* Volume ID Format Changed
+* Node ID Format Changed
+* Parameter "zone" Removed

deploy/kubernetes/dev/WARNING.md

@@ -42,7 +42,7 @@ spec:
               mountPath: /csi
         - name: gce-pd-driver
           imagePullPolicy: Always
-          image: gcr.io/google-containers/volume-csi/gcp-compute-persistent-disk-csi-driver:v0.1.0.alpha
+          image: gcr.io/dyzz-csi-staging/csi/gce-pd-driver:latest
           args:
             - "--v=5"
             - "--endpoint=$(CSI_ENDPOINT)"
@@ -62,4 +62,4 @@ spec:
           emptyDir: {}
         - name: cloud-sa-volume
           secret:
-            secretName: cloud-sa
+            secretName: cloud-sa

deploy/kubernetes/controller.yaml renamed to deploy/kubernetes/dev/controller.yaml

@@ -36,7 +36,7 @@ spec:
           securityContext:
             privileged: true
           imagePullPolicy: Always
-          image: gcr.io/google-containers/volume-csi/gcp-compute-persistent-disk-csi-driver:v0.1.0.alpha
+          image: gcr.io/dyzz-csi-staging/csi/gce-pd-driver:latest 
           args:
             - "--v=5"
             - "--endpoint=$(CSI_ENDPOINT)"
@@ -68,4 +68,4 @@ spec:
         - name: device-dir
           hostPath:
             path: /dev
-            type: Directory
+            type: Directory