Merge pull request #264 from hossainemruz/snapshot-guide

Improve VolumeSnapshot guide

Author: k8s-ci-robot

docs/kubernetes/user-guides/snapshots.md

@@ -1,8 +1,11 @@
 # Kubernetes Snapshots User Guide (Alpha)
 
+>**Attention:** VolumeSnapshot is an alpha feature. Make sure you have enabled it in Kubernetes API server using `--feature-gates=VolumeSnapshotDataSource=true` flag.
+
 ### Install Driver with alpha snapshot feature
 
 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
@@ -11,6 +14,7 @@ $ ./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=alpha                     # Driver version to deploy
@@ -19,33 +23,89 @@ $ ./deploy/kubernetes/deploy-driver.sh
 
 ### Snapshot Example
 
-1. Create example Default Snapshot Class
+**Create Storage Class:**
+
+If you haven't created a `StorageClass` yet, create one first:
+
+```console
+kubectl apply -f ./examples/kubernetes/demo-zonal-sc.yaml
 ```
-$ kubectl create -f ./examples/kubernetes/demo-defaultsnapshotclass.yaml
+
+**Create  Default VolumeSnapshotClass:**
+
+```console
+kubectl create -f ./examples/kubernetes/snapshot/default_volumesnapshotclass.yaml
 ```
-2. Create a snapshot of the PVC created in above example
+
+**Create source PVC:**
+
+```console
+kubectl create -f ./examples/kubernetes/snapshot/source_pvc.yaml
 ```
-$ kubectl create -f ./examples/kubernetes/demo-snapshot.yaml
+
+**Generate sample data:**
+
+Create a sample pod with the source PVC. The source PVC is mounted into `/demo/data` directory of this pod. This pod will create a file `sample-file.txt` in `/demo/data` directory.
+
+```console
+kubectl create -f ./examples/kubernetes/snapshot/source_pod.yaml
+```
+
+Check if the file has been created successfully:
+
+```console
+$ kubectl exec source-pod -- ls /demo/data/
+lost+found
+sample-file.txt
 ```
-3. Verify Snapshot is created and is ready to use
+
+**Create a snapshot of the source PVC:**
+
+```console
+kubectl create -f ./examples/kubernetes/snapshot/snapshot.yaml
 ```
-$ k get volumesnapshots demo-snapshot-podpvc -o yaml
+
+**Verify Snapshot has been created and it is ready to use:**
+
+```console
+$ kubectl get volumesnapshot snapshot-source-pvc -o yaml
 apiVersion: snapshot.storage.k8s.io/v1alpha1
 kind: VolumeSnapshot
 metadata:
-  creationTimestamp: 2018-10-05T16:59:26Z
-  generation: 1
-  name: demo-snapshot-podpvc
+  ...
+  name: snapshot-source-pvc
   namespace: default
-
-...
-
+  ...
+spec:
+  snapshotClassName: default-snapshot-class
+  snapshotContentName: snapcontent-b408076b-720b-11e9-b9e3-42010a800014
+  ...
 status:
-  creationTime: 2018-10-05T16:59:27Z
-  ready: true
+  creationTime: "2019-05-09T03:37:01Z"
+  readyToUse: true
   restoreSize: 6Gi
+```
+
+**Restore the Snapshot into a new PVC:**
 
+Create a new PVC. Specify `spec.dataSource` section to restore from VolumeSnapshot `snapshot-source-pvc`.
+
+```console
+ kubectl create -f ./examples/kubernetes/snapshot/restored_pvc.yaml
 ```
-4. Create a new volume from the snapshot
+
+**Verify sample data has been restored:**
+
+Create a sample pod with the restored PVC:
+
+```console
+kubectl create -f ./examples/kubernetes/snapshot/restored_pod.yaml
+```
+
+Check data has been restored in `/demo/data` directory:
+
+```console
+$ kubectl exec restored-pod -- ls /demo/data/
+lost+found
+sample-file.txt
 ```
-$ kubectl create -f ./examples/kubernetes/demo-restore-snapshot.yaml

examples/kubernetes/demo-defaultsnapshotclass.yaml renamed to examples/kubernetes/snapshot/default-volumesnapshotclass.yaml

@@ -0,0 +1,19 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: restored-pod
+spec:
+  containers:
+  - name: busybox
+    image: busybox
+    args:
+    - sleep
+    - "3600"
+    volumeMounts:
+    - name: source-data
+      mountPath: /demo/data
+  volumes:
+  - name: source-data
+    persistentVolumeClaim:
+      claimName: restored-pvc
+      readOnly: false

examples/kubernetes/snapshot/restored-pod.yaml

@@ -1,7 +1,7 @@
 kind: PersistentVolumeClaim
 apiVersion: v1
 metadata:
-  name: restore-snapshot
+  name: restored-pvc
 spec:
   accessModes:
     - ReadWriteOnce
@@ -11,5 +11,5 @@ spec:
       storage: 6Gi
   dataSource:
     kind: VolumeSnapshot
-    name: demo-snapshot-podpvc
+    name: snapshot-source-pvc
     apiGroup: snapshot.storage.k8s.io

examples/kubernetes/demo-restore-snapshot.yaml renamed to examples/kubernetes/snapshot/restored-pvc.yaml

@@ -1,9 +1,8 @@
 apiVersion: snapshot.storage.k8s.io/v1alpha1
 kind: VolumeSnapshot
 metadata:
-  name: demo-snapshot-podpvc
+  name: snapshot-source-pvc
 spec:
   source:
     kind: PersistentVolumeClaim
-    name: podpvc
-
+    name: source-pvc

examples/kubernetes/demo-snapshot.yaml renamed to examples/kubernetes/snapshot/snapshot.yaml

@@ -0,0 +1,18 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: source-pod
+spec:
+  containers:
+  - name: busybox
+    image: busybox
+    command: ["/bin/sh", "-c"]
+    args: ["touch /demo/data/sample-file.txt && sleep 3000"]
+    volumeMounts:
+    - name: source-data
+      mountPath: /demo/data
+  volumes:
+  - name: source-data
+    persistentVolumeClaim:
+      claimName: source-pvc
+      readOnly: false

examples/kubernetes/snapshot/source-pod.yaml

@@ -0,0 +1,11 @@
+kind: PersistentVolumeClaim
+apiVersion: v1
+metadata:
+  name: source-pvc
+spec:
+  accessModes:
+    - ReadWriteOnce
+  storageClassName: csi-gce-pd
+  resources:
+    requests:
+      storage: 6Gi