doc: refine doc

Author: andyzhangx

README.md

@@ -18,8 +18,8 @@ This is a repository for [NFS](https://en.wikipedia.org/wiki/Network_File_System
 
 ### Install driver on a Kubernetes cluster
  > [install NFS CSI driver on microk8s](https://microk8s.io/docs/nfs)
- - install by [kubectl](./docs/install-nfs-csi-driver.md)
- - install by [helm charts](./charts)
+ - install via [helm charts](./charts)
+ - install via [kubectl](./docs/install-nfs-csi-driver.md)
 
 ### Driver parameters
 Please refer to [`nfs.csi.k8s.io` driver parameters](./docs/driver-parameters.md)

deploy/example/nfs-provisioner/nginx-pod.yaml

@@ -2,6 +2,8 @@
 apiVersion: v1
 kind: PersistentVolume
 metadata:
+  annotations:
+    pv.kubernetes.io/provisioned-by: nfs.csi.k8s.io
   name: pv-nginx
 spec:
   capacity:
@@ -14,7 +16,9 @@ spec:
   csi:
     driver: nfs.csi.k8s.io
     readOnly: false
-    volumeHandle: unique-volumeid  # make sure it's a unique id in the cluster
+    # volumeHandle format: {nfs-server-address}#{sub-dir-name}#{share-name}
+    # make sure this value is unique for every share in the cluster
+    volumeHandle: nfs-server.default.svc.cluster.local/share##
     volumeAttributes:
       server: nfs-server.default.svc.cluster.local
       share: /

deploy/example/pv-nfs-csi.yaml

@@ -2,6 +2,8 @@
 apiVersion: v1
 kind: PersistentVolume
 metadata:
+  annotations:
+    pv.kubernetes.io/provisioned-by: nfs.csi.k8s.io
   name: pv-nfs
 spec:
   capacity:
@@ -15,7 +17,9 @@ spec:
   csi:
     driver: nfs.csi.k8s.io
     readOnly: false
-    volumeHandle: unique-volumeid  # make sure it's a unique id in the cluster
+    # volumeHandle format: {nfs-server-address}#{sub-dir-name}#{share-name}
+    # make sure this value is unique for every share in the cluster
+    volumeHandle: nfs-server.default.svc.cluster.local/share##
     volumeAttributes:
       server: nfs-server.default.svc.cluster.local
       share: /

docs/driver-parameters.md

@@ -11,11 +11,18 @@ share | NFS share path | `/` | Yes |
 subDir | sub directory under nfs share |  | No | if sub directory does not exist, this driver would create a new one
 mountPermissions | mounted folder permissions. The default is `0`, if set as non-zero, driver will perform `chmod` after mount |  | No |
 
+ - VolumeID(`volumeHandle`) is the identifier of the volume handled by the driver, format of VolumeID:
+```
+{nfs-server-address}#{sub-dir-name}#{share-name}
+```
+> example: `nfs-server.default.svc.cluster.local/share#subdir#`
+
 ### PV/PVC usage (static provisioning)
 > [`PersistentVolume` example](../deploy/example/pv-nfs-csi.yaml)
 
 Name | Meaning | Example Value | Mandatory | Default value
 --- | --- | --- | --- | ---
+volumeHandle | Specify a value the driver can use to uniquely identify the share in the cluster. | A recommended way to produce a unique value is to combine the nfs-server address, sub directory name and share name: `{nfs-server-address}#{sub-dir-name}#{share-name}`. | Yes |
 volumeAttributes.server | NFS Server address | domain name `nfs-server.default.svc.cluster.local` <br>or IP address `127.0.0.1` | Yes |
 volumeAttributes.share | NFS share path | `/` |  Yes  |
 volumeAttributes.mountPermissions | mounted folder permissions. The default is `0`, if set as non-zero, driver will perform `chmod` after mount |  | No |