Merge pull request #218 from haibinxie/master

Add volume import readme and examples

docs/csi-volume-import.md

@@ -0,0 +1,105 @@
+# Import volumes into Kubernetes
+
+## Use Cases
+- Reinstall Kubernetes or migrate volume from one Kubernetes cluster to another
+- Disaster recovery from backup volume
+- Containerize legacy application
+
+## Dependencies
+* Kubernetes v1.15+ (Lower version might work however not tested)
+* Pure CSI driver 5.2.0+
+* Support both FA (raw block and file system) and FB (file system)
+
+## Import Guidance
+The beauty of volume import feature is that there are no changes or additional annotations to persistent volume objects.  Take the scenario of migrating volumes from one Kubernetes cluster to another cluster: users can export persistent volume objects (and persistent volume claim objects) from the old cluster and deploy to a new Kubernetes cluster, with no additional changes.
+
+```diff
+-Caution: important notes about reclaim policy
+```
+>Both Delete and Retain reclaim policies are supported on imported volumes, where the reclaim policy is configured in persistent volume object. If users delete a persistent volume claim and the corresponding persistent volume has `Delete` as reclaim policy, both the persistent volume object and backend volume will be deleted automatically.
+>
+>If users delete a persistent volume (PV) object before deleting the associated persistent volume claim (PVC) the backend volume will *NOT* be deleted regardless of the reclaim policy setting for the PV. This is consistent with the behaviour of any dynamically provisioned volume.
+ 
+If users want to import a volume that was created outside of Kubernetes, persistent volume and persistent volume claim objects can be manually created using the following steps:
+
+1. Create and deploy a persistent volume object with `volumeHandle` configured to be the name of the volume in backend, and `claimRef` to be the name of the persistent volume claim at your choice.
+
+    Here is an example, but more examples can be found at: [examples/volumeimport](./examples/volumeimport)
+```yaml
+apiVersion: v1
+kind: PersistentVolume
+metadata:
+  annotations:
+    pv.kubernetes.io/provisioned-by: pure-csi
+  name: pv-import
+spec:
+  accessModes:
+  - ReadWriteOnce
+  capacity:
+    storage: 1Gi
+  claimRef:
+    apiVersion: v1
+    kind: PersistentVolumeClaim
+    # TODO: change to the PVC you want to bind this PV.
+    # If you don't pre-bind PVC here, the PV might be automatically bound to a PVC by scheduler.
+    name: pvc-import
+    # Namespace of the PVC
+    namespace: default
+  csi:
+    driver: pure-csi
+    # TODO: change to the volume name in backend.
+    # Volume with any name that exists in backend can be imported, and will not be renamed.
+    volumeHandle: ttt-pvc-a90d7d5f-da6c-44db-a306-a4cc122f9dd3
+  # TODO: configure your desired reclaim policy,
+  # Use Retain if you don't want your volume to get deleted when the PV is deleted.
+  persistentVolumeReclaimPolicy: Delete
+  storageClassName: pure-file
+  volumeMode: Filesystem
+```
+
+2. Create and deploy a persistent volume claim object with volumeName configured to the persistent volume created at step 1.
+
+   Here is an example, but more examples can be found at: [examples/volumeimport](./examples/volumeimport)
+
+```yaml
+apiVersion: "v1"
+kind: "PersistentVolumeClaim"
+metadata:
+  name: pvc-import
+spec:
+  accessModes:
+    - "ReadWriteOnce"
+  resources:
+    requests:
+      storage: "1Gi"
+  # Note: These two fields are not required for pre-bound PV.
+  # storageClassName: pure-block
+  # volumeMode: Filesystem
+
+  # TODO: Change to the name of the imported PV.
+  volumeName: pv-import
+```
+
+3. Use the persistent volume claim.
+
+```yaml
+ apiVersion: v1
+ kind: Pod
+ metadata:
+   name: nginx
+ spec:
+   # Specify a volume that uses the claim defined in pvc.yaml
+   volumes:
+   - name: pure-vol
+     persistentVolumeClaim:
+         claimName: pvc-import
+   containers:
+   - name: nginx
+     image: nginx
+     # Configure a mount for the volume We define above
+     volumeMounts:
+     - name: pure-vol
+       mountPath: /data
+     ports:
+     - containerPort: 80
+```

docs/examples/volumeimport/pod-raw.yaml

@@ -0,0 +1,19 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: nginx-raw
+spec:
+  # Specify a volume that uses the claim defined in pvc.yaml
+  volumes:
+    - name: pure-vol
+      persistentVolumeClaim:
+        claimName: pvc-import
+  containers:
+    - name: nginx
+      image: nginx
+      # Configure a device mount for the volume we defined above
+      volumeDevices:
+        - name: pure-vol
+          devicePath: /dev/pure-block-device
+      ports:
+        - containerPort: 80

docs/examples/volumeimport/pod.yaml

@@ -0,0 +1,19 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: nginx
+spec:
+  # Specify a volume that uses the claim defined in pvc.yaml
+  volumes:
+  - name: pure-vol
+    persistentVolumeClaim:
+        claimName: pvc-import
+  containers:
+  - name: nginx
+    image: nginx
+    # Configure a mount for the volume We define above
+    volumeMounts:
+    - name: pure-vol
+      mountPath: /data
+    ports:
+    - containerPort: 80

docs/examples/volumeimport/pv-import-block.yaml

@@ -0,0 +1,29 @@
+apiVersion: v1
+kind: PersistentVolume
+metadata:
+  annotations:
+    pv.kubernetes.io/provisioned-by: pure-csi
+  name: pv-import
+spec:
+  accessModes:
+  - ReadWriteOnce
+  capacity:
+    storage: 1Gi
+  claimRef:
+    apiVersion: v1
+    kind: PersistentVolumeClaim
+    # TODO: change to the PVC you want to bind this PV.
+    # If you don't pre-bind PVC here, the PV might be automatically bound to a PVC by scheduler.
+    name: pvc-import
+    # Namespace of the PVC
+    namespace: default
+  csi:
+    driver: pure-csi
+    # TODO: change to the volume name in backend.
+    # Volume with any name that exists in backend can be imported, and will not be renamed.
+    volumeHandle: ns03276-pvc-2031faf1-8348-4ac8-9737-1a0a9989cad7
+  # TODO: configure your desired reclaim policy,
+  # Use Retain if you don't want your volume to get deleted when the PV is deleted.
+  persistentVolumeReclaimPolicy: Delete
+  storageClassName: pure-block
+  volumeMode: Filesystem

docs/examples/volumeimport/pv-import-file.yaml

@@ -0,0 +1,29 @@
+apiVersion: v1
+kind: PersistentVolume
+metadata:
+  annotations:
+    pv.kubernetes.io/provisioned-by: pure-csi
+  name: pv-import
+spec:
+  accessModes:
+  - ReadWriteOnce
+  capacity:
+    storage: 1Gi
+  claimRef:
+    apiVersion: v1
+    kind: PersistentVolumeClaim
+    # TODO: change to the PVC you want to bind this PV.
+    # If you don't pre-bind PVC here, the PV might be automatically bound to a PVC by scheduler.
+    name: pvc-import
+    # Namespace of the PVC
+    namespace: default
+  csi:
+    driver: pure-csi
+    # TODO: change to the volume name in backend.
+    # Volume with any name that exists in backend can be imported, and will not be renamed.
+    volumeHandle: ttt-pvc-a90d7d5f-da6c-44db-a306-a4cc122f9dd3
+  # TODO: configure your desired reclaim policy,
+  # Use Retain if you don't want your volume to get deleted when the PV is deleted.
+  persistentVolumeReclaimPolicy: Delete
+  storageClassName: pure-file
+  volumeMode: Filesystem

docs/examples/volumeimport/pv-import-raw.yaml

@@ -0,0 +1,29 @@
+apiVersion: v1
+kind: PersistentVolume
+metadata:
+  annotations:
+    pv.kubernetes.io/provisioned-by: pure-csi
+  name: pv-import
+spec:
+  accessModes:
+  - ReadWriteOnce
+  capacity:
+    storage: 1Gi
+  claimRef:
+    apiVersion: v1
+    kind: PersistentVolumeClaim
+    # TODO: change to the PVC you want to bind this PV.
+    # If you don't pre-bind PVC here, the PV might be automatically bound to a PVC by scheduler.
+    name: pvc-import
+    # Namespace of the PVC
+    namespace: default
+  csi:
+    driver: pure-csi
+    # TODO: change to the volume name in backend.
+    # Volume with any name that exists in backend can be imported, and will not be renamed.
+    volumeHandle: ns04132-pvc-540d6142-2e86-45ba-939d-c0be5d8fd335
+  # TODO: configure your desired reclaim policy,
+  # Use Retain if you don't want your volume to get deleted when the PV is deleted.
+  persistentVolumeReclaimPolicy: Delete
+  storageClassName: pure-block
+  volumeMode: Block

docs/examples/volumeimport/pvc-import.yaml

@@ -0,0 +1,16 @@
+apiVersion: "v1"
+kind: "PersistentVolumeClaim"
+metadata:
+  name: pvc-import
+spec:
+  accessModes:
+    - "ReadWriteOnce"
+  resources:
+    requests:
+      storage: "1Gi"
+  # Note: These two fields are not required for pre-bound PV.
+  # storageClassName: pure-block
+  # volumeMode: Filesystem
+
+  # TODO: Change to the name of the imported PV.
+  volumeName: pv-import