Update README and add more examples

docs/README.md

@@ -5,87 +5,57 @@
 **DISCLAIMER**: This is not an officially supported Amazon product
 
 ## AWS EFS CSI Driver
-###
 
-The [Amazon Elastic File System](https://aws.amazon.com/efs/) Container Storage Interface (CSI) Driver implements [CSI](https://github.com/container-storage-interface/spec/blob/master/spec.md) interface for container orchestrators to manage lifecycle of Amazon EFS volumes.
-
-This driver is in alpha stage. Basic volume operations that are functional include NodePublishVolume/NodeUnpublishVolume.
+The [Amazon Elastic File System](https://aws.amazon.com/efs/) Container Storage Interface (CSI) Driver implements [CSI](https://github.com/container-storage-interface/spec/blob/master/spec.md) interface for container orchestrators to manage lifecycle of Amazon EFS filesystem.
 
 ### CSI Specification Compability Matrix
 | AWS EFS CSI Driver \ CSI Version       | v0.3.0| v1.0.0 |
 |----------------------------------------|-------|--------|
 | master branch                          | yes   | no     |
 
-### Kubernetes Version Compability Matrix
-| AWS EFS CSI Driver \ Kubernetes Version| v1.12 | v1.13 |
-|----------------------------------------|-------|-------|
-| master branch                          | yes   | yes   |
-
 ## Features
-Currently only static provisioning is supported. This means a AWS EFS filesystem needs to be created manually on AWS first. After that it could be mounted inside container as a volume using AWS EFS CSI Driver.
+Currently only static provisioning is supported. This means a AWS EFS filesystem needs to be created manually on AWS first. After that it could be mounted inside container as a volume using the driver.
+
+The following CSI interfaces are implemented:
+* Node Service: NodePublishVolume, NodeUnpublishVolume, NodeGetCapabilities, NodeGetInfo, NodeGetId
 
 ### Encryption In Transit
-One of the advantages of using EFS is that it provides [encryption in transit](https://aws.amazon.com/blogs/aws/new-encryption-of-data-in-transit-for-amazon-efs/) support using TLS. Using encryption in transit, data will be encrypted during its transition over the network to EFS service. This provides extra layer of depth-in-depth for applications that requires higher secuity compliance.
+One of the advantages of using EFS is that it provides [encryption in transit](https://aws.amazon.com/blogs/aws/new-encryption-of-data-in-transit-for-amazon-efs/) support using TLS. Using encryption in transit, data will be encrypted during its transition over the network to EFS service. This provides extra layer of defence-in-depth for applications that requires strict secuity compliance.
 
-To enable encryption in transit, `tls` needs to be set at `NodePublishVolumeRequest.VolumeCapability.MountVolume` object's `MountFlags` fields. For example of using it in kuberentes, see persistence volume manifest in [Example](#kubernetes-example)
+To enable encryption in transit, `tls` needs to be set at `NodePublishVolumeRequest.VolumeCapability.MountVolume` object's `MountFlags` fields. For example of using it in kuberentes, see persistence volume manifest in [Encryption in Transit Example](../examples/kubernetes/encryption_in_transit/pv.yaml)
 
-**Note** Kubernetes version 1.13 and above is required if you are using this feature in Kuberentes.
+**Note** Kubernetes version 1.13+ is required if you are using this feature in Kuberentes.
 
-# Kubernetes Example
-This example demos how to make a EFS filesystem mounted inside container using the driver. Before this, get yourself familiar with setting up kubernetes on AWS and [creating EFS filesystem](https://docs.aws.amazon.com/efs/latest/ug/getting-started.html). And when creating EFS filesystem, make sure it is accessible from kuberenetes cluster. This can be achieved by creating EFS filesystem inside the same VPC as kubernetes cluster or using VPC peering.
+## EFS CSI Driver on Kubernetes
+The following sections are Kubernetes specific. If you are Kubernetes user, use this for driver features, installation steps and examples.
 
+### Kubernetes Version Compability Matrix
+| AWS EFS CSI Driver \ Kubernetes Version| v1.12 | v1.13 |
+|----------------------------------------|-------|-------|
+| master branch                          | yes   | yes   |
+
+### Features
+* Static provisioning - EFS filesystem needs to be created manually first, then it could be mounted inside container as a persistence volume (PV) using the driver.
+* Mount Options - Mount options could be specified in persistence volume (PV) to define how the volume should be mounted. Aside from normal mount options, you can also specify `tls` as mount option to enable encryption in transit of EFS filesystem.
+
+### Installation
 Deploy AWS EFS CSI driver:
 
 ```
 kubectl apply -f https://raw.githubusercontent.com/aws/aws-efs-csi-driver/master/deploy/kubernetes/controller.yaml 
 kubectl apply -f https://raw.githubusercontent.com/aws/aws-efs-csi-driver/master/deploy/kubernetes/node.yaml
 ```
 
-Edit the [persistence volume manifest file](../examples/kubernetes/sample_app/pv.yaml) (note that encryption in transit is enabled using mount option):
-```
-apiVersion: v1
-kind: PersistentVolume
-metadata:
-  name: efs-pv
-spec:
-  capacity:
-    storage: 5Gi
-  volumeMode: Filesystem
-  accessModes:
-    - ReadWriteOnce
-  persistentVolumeReclaimPolicy: Recycle
-  storageClassName: efs-sc
-  mountOptions:
-    - tls
-  csi:
-    driver: efs.csi.aws.com
-    volumeHandle: [FileSystemId] 
-```
-Replace `VolumeHandle` with `FileSystemId` of the EFS filesystem that needs to be mounted. You can find it using AWS CLI:
-
-```
-aws efs describe-file-systems 
-```
-
-Then create PV, persistence volume claim (PVC) and storage class:
-```
-kubectl apply -f examples/kubernetes/sample_app/storageclass.yaml
-kubectl apply -f examples/kubernetes/sample_app/pv.yaml
-kubectl apply -f examples/kubernetes/sample_app/claim.yaml
-kubectl apply -f examples/kubernetes/sample_app/pod.yaml
-```
-
-After the objects are created, verify that pod name app is running:
-
-```
-kubectl get pods
-```
+### Examples
+Before the example, you need to:
+* Get yourself familiar with how to setup Kubernetes on AWS and how to [create EFS filesystem](https://docs.aws.amazon.com/efs/latest/ug/getting-started.html).
+* When creating EFS filesystem, make sure it is accessible from Kuberenetes cluster. This can be achieved by creating the filesystem inside the same VPC as Kubernetes cluster or using VPC peering.
+* Install EFS CSI driver following the [Installation](README.md#Installation) steps.
 
-Also you can verify that data is written onto EFS filesystem:
-
-```
-kubectl exec -ti app -- tail -f /data/out.txt
-```
+#### Example links
+* [Static provisioning](../examples/kubernetes/static_provisioning/README.md)
+* [Encryption in transit](../examples/kubernetes/encryption_in_transit/README.md)
+* [Accessing the filesystem from multiple pods](../examples/kubernetes/multiple_pods/README.md)
 
 ## Development
 Please go through [CSI Spec](https://github.com/container-storage-interface/spec/blob/master/spec.md) and [General CSI driver development guideline](https://kubernetes-csi.github.io/docs/Development.html) to get some basic understanding of CSI driver before you start.

examples/kubernetes/encryption_in_transit/README.md

@@ -0,0 +1,54 @@
+## Encryption in Transit
+This example shows how to make a static provisioned EFS PV mounted inside container with encryption in transit enabled.
+
+**Note**: this example required Kubernetes v1.13+
+
+### Edit [Persistence Volume Spec](pv.yaml) 
+
+```
+apiVersion: v1
+kind: PersistentVolume
+metadata:
+  name: efs-pv
+spec:
+  capacity:
+    storage: 5Gi
+  volumeMode: Filesystem
+  accessModes:
+    - ReadWriteOnce
+  persistentVolumeReclaimPolicy: Recycle
+  storageClassName: efs-sc
+  mountOptions:
+    - tls
+  csi:
+    driver: efs.csi.aws.com
+    volumeHandle: [FileSystemId] 
+```
+Note that encryption in transit is enabled using mount option `tls`. Replace `VolumeHandle` with `FileSystemId` of the EFS filesystem that needs to be mounted.
+
+You can find it using AWS CLI:
+```
+aws efs describe-file-systems 
+```
+
+### Deploy the Example
+Create PV, persistence volume claim (PVC) and storage class:
+```
+kubectl apply -f examples/kubernetes/encryption_in_transit/storageclass.yaml
+kubectl apply -f examples/kubernetes/encryption_in_transit/pv.yaml
+kubectl apply -f examples/kubernetes/encryption_in_transit/claim.yaml
+kubectl apply -f examples/kubernetes/encryption_in_transit/pod.yaml
+```
+
+### Check EFS filesystem is used
+After the objects are created, verify that pod is running:
+
+```
+kubectl get pods
+```
+
+Also you can verify that data is written onto EFS filesystem:
+
+```
+kubectl exec -ti app -- tail -f /data/out.txt
+```

examples/kubernetes/multiple_pods/README.md

@@ -0,0 +1,55 @@
+## Multiple Pods Read Write Many 
+This example shows how to create a static provisioned EFS PV and access it from multiple pods with RWX access mode.
+
+### Edit Persistent Volume
+Edit persistent volume using sample [spec](pv.yaml):
+```
+apiVersion: v1
+kind: PersistentVolume
+metadata:
+  name: efs-pv
+spec:
+  capacity:
+    storage: 5Gi
+  volumeMode: Filesystem
+  accessModes:
+    - ReadWriteMany
+  persistentVolumeReclaimPolicy: Recycle
+  storageClassName: efs-sc
+  csi:
+    driver: efs.csi.aws.com
+    volumeHandle: [FileSystemId] 
+```
+Replace `volumeHandle` with `FileSystemId` of the EFS filesystem that needs to be mounted. Note that the access mode is `RWX` which means the PV can be read and write from multiple pods.
+
+You can get `FileSystemId` using AWS CLI:
+
+```
+aws efs describe-file-systems 
+```
+
+### Deploy the Example Application
+Create PV, persistence volume claim (PVC), storageclass and the pods that consume the PV:
+```
+kubectl apply -f examples/kubernetes/multiple_pods/storageclass.yaml
+kubectl apply -f examples/kubernetes/multiple_pods/pv.yaml
+kubectl apply -f examples/kubernetes/multiple_pods/claim.yaml
+kubectl apply -f examples/kubernetes/multiple_pods/pod1.yaml
+kubectl apply -f examples/kubernetes/multiple_pods/pod2.yaml
+```
+
+Both pod1 and pod2 are writing to the same EFS filesystem at the same time.
+
+### Check the Application uses EFS filesystem
+After the objects are created, verify that pod is running:
+
+```
+kubectl get pods
+```
+
+Also verify that data is written onto EFS filesystem:
+
+```
+kubectl exec -ti app1 -- tail -f /data/out1.txt
+kubectl exec -ti app2 -- tail -f /data/out2.txt
+```

examples/kubernetes/multiple_pods/pv.yaml

@@ -12,4 +12,4 @@ spec:
   storageClassName: efs-sc
   csi:
     driver: efs.csi.aws.com
-    volumeHandle: fs-d26a037a
+    volumeHandle: fs-4af69aab

examples/kubernetes/static_provisioning/README.md

@@ -0,0 +1,50 @@
+## Static Provisioning
+This example shows how to make a static provisioned EFS PV mounted inside container.
+
+### Edit [Persistence Volume Spec](pv.yaml) 
+
+```
+apiVersion: v1
+kind: PersistentVolume
+metadata:
+  name: efs-pv
+spec:
+  capacity:
+    storage: 5Gi
+  volumeMode: Filesystem
+  accessModes:
+    - ReadWriteOnce
+  persistentVolumeReclaimPolicy: Recycle
+  storageClassName: efs-sc
+  csi:
+    driver: efs.csi.aws.com
+    volumeHandle: [FileSystemId] 
+```
+Replace `VolumeHandle` with `FileSystemId` of the EFS filesystem that needs to be mounted.
+
+You can find it using AWS CLI:
+```
+aws efs describe-file-systems 
+```
+
+### Deploy the Example Application
+Create PV, persistence volume claim (PVC) and storage class:
+```
+kubectl apply -f examples/kubernetes/static_provisioning/storageclass.yaml
+kubectl apply -f examples/kubernetes/static_provisioning/pv.yaml
+kubectl apply -f examples/kubernetes/static_provisioning/claim.yaml
+kubectl apply -f examples/kubernetes/static_provisioning/pod.yaml
+```
+
+### Check EFS filesystem is used
+After the objects are created, verify that pod is running:
+
+```
+kubectl get pods
+```
+
+Also you can verify that data is written onto EFS filesystem:
+
+```
+kubectl exec -ti app -- tail -f /data/out.txt
+```

examples/kubernetes/static_provisioning/claim.yaml

@@ -0,0 +1,11 @@
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: efs-claim
+spec:
+  accessModes:
+    - ReadWriteOnce
+  storageClassName: efs-sc
+  resources:
+    requests:
+      storage: 5Gi

examples/kubernetes/static_provisioning/pod.yaml

@@ -0,0 +1,17 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: efs-app
+spec:
+  containers:
+  - name: app
+    image: centos
+    command: ["/bin/sh"]
+    args: ["-c", "while true; do echo $(date -u) >> /data/out.txt; sleep 5; done"]
+    volumeMounts:
+    - name: persistent-storage
+      mountPath: /data
+  volumes:
+  - name: persistent-storage
+    persistentVolumeClaim:
+      claimName: efs-claim

examples/kubernetes/static_provisioning/pv.yaml

@@ -0,0 +1,15 @@
+apiVersion: v1
+kind: PersistentVolume
+metadata:
+  name: efs-pv
+spec:
+  capacity:
+    storage: 5Gi
+  volumeMode: Filesystem
+  accessModes:
+    - ReadWriteOnce
+  persistentVolumeReclaimPolicy: Recycle
+  storageClassName: efs-sc
+  csi:
+    driver: efs.csi.aws.com
+    volumeHandle: fs-4af69aab

examples/kubernetes/static_provisioning/storageclass.yaml

@@ -0,0 +1,5 @@
+kind: StorageClass
+apiVersion: storage.k8s.io/v1
+metadata:
+  name: efs-sc
+provisioner: efs.csi.aws.com