Merge pull request #555 from umagnus/add_volume_cloning_doc

doc: add volume cloning doc

README.md

@@ -27,6 +27,7 @@ Please refer to [`nfs.csi.k8s.io` driver parameters](./docs/driver-parameters.md
 ### Examples
  - [Basic usage](./deploy/example/README.md)
  - [fsGroupPolicy](./deploy/example/fsgroup)
+ - [Volume cloning](./deploy/example/cloning)
 
 ### Troubleshooting
  - [CSI driver troubleshooting guide](./docs/csi-debug.md) 

deploy/example/cloning/README.md

@@ -0,0 +1,65 @@
+# Volume Cloning Example
+
+- supported from v4.3.0
+
+## Create a Source PVC
+
+```console
+kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/master/deploy/example/storageclass-nfs.yaml
+kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/master/deploy/example/pvc-nfs-csi-dynamic.yaml
+kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/master/deploy/example/nginx-pod-nfs.yaml
+```
+
+### Check the Source PVC
+
+```console
+$ kubectl exec nginx-nfs -- ls /mnt/nfs
+outfile
+```
+
+## Create a PVC from an existing PVC
+>  Make sure application is not writing data to source nfs share
+```console
+kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/master/deploy/example/cloning/pvc-nfs-cloning.yaml
+```
+### Check the Creation Status
+
+```console
+$ kubectl describe pvc pvc-nfs-cloning
+Name:          pvc-nfs-cloning
+Namespace:     default
+StorageClass:  nfs-csi
+Status:        Bound
+Volume:        pvc-5a00da0e-9afe-40f7-9f52-edabcf28df63
+Labels:        <none>
+Annotations:   kubectl.kubernetes.io/last-applied-configuration:
+                 {"apiVersion":"v1","kind":"PersistentVolumeClaim","metadata":{"annotations":{},"name":"pvc-nfs-cloning","namespace":"default"},"spec":{"ac...
+               pv.kubernetes.io/bind-completed: yes
+               pv.kubernetes.io/bound-by-controller: yes
+               volume.beta.kubernetes.io/storage-provisioner: nfs.csi.k8s.io
+               volume.kubernetes.io/storage-provisioner: nfs.csi.k8s.io
+Finalizers:    [kubernetes.io/pvc-protection]
+Capacity:      10Gi
+Access Modes:  RWX
+VolumeMode:    Filesystem
+Mounted By:    <none>
+Events:
+  Type    Reason                 Age   From                                                                                   Message
+  ----    ------                 ----  ----                                                                                   -------
+  Normal  ExternalProvisioning   5s    persistentvolume-controller                                                            waiting for a volume to be created, either by external provisioner "nfs.csi.k8s.io" or manually created by system administrator
+  Normal  Provisioning           5s    nfs.csi.k8s.io_aks-nodepool1-34988195-vmss000000_534f1e86-3a71-4ca4-9b83-803c05a44d65  External provisioner is provisioning volume for claim "default/pvc-nfs-cloning"
+  Normal  ProvisioningSucceeded  5s    nfs.csi.k8s.io_aks-nodepool1-34988195-vmss000000_534f1e86-3a71-4ca4-9b83-803c05a44d65  Successfully provisioned volume pvc-5a00da0e-9afe-40f7-9f52-edabcf28df63
+```
+
+## Restore the PVC into a Pod
+
+```console
+kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/master/deploy/example/cloning/nginx-pod-restored-cloning.yaml
+```
+
+### Check Sample Data
+
+```console
+$ kubectl exec nginx-nfs-restored-cloning -- ls /mnt/nfs
+outfile
+```

deploy/example/cloning/nginx-pod-restored-cloning.yaml

@@ -0,0 +1,23 @@
+---
+kind: Pod
+apiVersion: v1
+metadata:
+  name: nginx-nfs-restored-cloning
+spec:
+  nodeSelector:
+    "kubernetes.io/os": linux
+  containers:
+    - image: mcr.microsoft.com/oss/nginx/nginx:1.19.5
+      name: nginx-nfs
+      command:
+        - "/bin/bash"
+        - "-c"
+        - set -euo pipefail; while true; do echo $(date) >> /mnt/nfs/outfile; sleep 1; done
+      volumeMounts:
+        - name: persistent-storage
+          mountPath: "/mnt/nfs"
+          readOnly: false
+  volumes:
+    - name: persistent-storage
+      persistentVolumeClaim:
+        claimName: pvc-nfs-cloning

deploy/example/cloning/pvc-nfs-cloning.yaml

@@ -2,7 +2,7 @@
 apiVersion: v1
 kind: PersistentVolumeClaim
 metadata:
-  name: pvc-nfs-clone
+  name: pvc-nfs-cloning
   namespace: default
 spec:
   accessModes:

deploy/example/nginx-pod-nfs.yaml

@@ -0,0 +1,23 @@
+---
+kind: Pod
+apiVersion: v1
+metadata:
+  name: nginx-nfs
+spec:
+  nodeSelector:
+    "kubernetes.io/os": linux
+  containers:
+    - image: mcr.microsoft.com/oss/nginx/nginx:1.19.5
+      name: nginx-nfs
+      command:
+        - "/bin/bash"
+        - "-c"
+        - set -euo pipefail; while true; do echo $(date) >> /mnt/nfs/outfile; sleep 1; done
+      volumeMounts:
+        - name: persistent-storage
+          mountPath: "/mnt/nfs"
+          readOnly: false
+  volumes:
+    - name: persistent-storage
+      persistentVolumeClaim:
+        claimName: pvc-nfs-dynamic

hack/verify-yamllint.sh

@@ -29,7 +29,7 @@ if [[ "${deployDirNum}" != "${helmDirNum}" ]]; then
   exit 1
 fi
 
-for path in "deploy/*.yaml" "deploy/example/*.yaml" "deploy/example/nfs-provisioner/*.yaml"
+for path in "deploy/*.yaml" "deploy/example/*.yaml" "deploy/example/nfs-provisioner/*.yaml" "deploy/example/cloning/*.yaml"
 do
     echo "checking yamllint under path: $path ..."
     yamllint -f parsable $path | grep -v "line too long" > $LOG