update docs

docs/install.md

@@ -0,0 +1,101 @@
+# Install iRODS CSI Driver using Helm
+
+You will need [Helm](https://helm.sh/docs/helm/helm_install/) to install `iRODS CSI Driver`.
+
+## Add Helm Chart Repository to Helm
+
+Run following command to add `iRODS CSI Driver Helm Chart Repository`.
+```shell script
+helm repo add irods-csi-driver-repo https://cyverse.github.io/irods-csi-driver-helm/
+helm repo update
+```
+
+Verify if the repository is added successfully.
+```shell script
+helm search repo irods
+```
+
+## Install iRODS CSI Driver
+
+Install `iRODS CSI Driver` with default configurations.
+The command below will install `irods-csi-driver-repo/irods-csi-driver` chart and the installed driver will be named `irods-csi-driver`. The driver pods will be created in `irods-csi-driver` namespace.
+
+```shell script
+helm install --create-namespace -n irods-csi-driver irods-csi-driver irods-csi-driver-repo/irods-csi-driver
+```
+
+Check pods of `iRODS CSI Driver`.
+
+```shell script
+kubectl get pods -n irods-csi-driver
+```
+
+The command will display following output.
+```
+NAME                                           READY   STATUS    RESTARTS   AGE
+irods-csi-driver-controller-6c7bb75479-d7z4p   2/2     Running   0          35m
+irods-csi-driver-controller-6c7bb75479-nk6cd   2/2     Running   0          35m
+irods-csi-driver-node-zbnkp                    4/4     Running   0          35m
+```
+
+By default, `iRODS CSI Driver` will create:
+- two `irods-csi-driver-controller` pods in a cluster
+- one `irods-csi-driver-node` pod per cluster node
+
+## Advanced configuration
+
+### Cache Configuration
+
+`iRODS FUSE Lite Pool Server` is built-in `iRODS CSI Driver` to provide connection pooling and data caching. The server runs in `irods-csi-driver-node` pod.
+
+To configure cache-related settings, create a YAML file that adds `nodeService/irodsPool/extraArgs`. 
+
+For example, the following sets `cache timeout` for paths, increase `max cache size`, and set `data root path` for storing cache and log.
+
+```yaml
+nodeService:
+  irodsPool:
+    extraArgs:
+      - '--cache_timeout_settings=[{"path":"/","timeout":"-1ns","inherit":false},{"path":"/cyverse","timeout":"-1ns","inherit":false},{"path":"/cyverse/home","timeout":"1h","inherit":false},{"path":"/cyverse/home/shared","timeout":"1h","inherit":true}]'
+      - --cache_size_max=10737418240
+      - --data_root=/irodsfs-pool
+```
+
+Then, provide the YAML file when installing `iRODS CSI Driver` using Helm.
+
+```shell script
+helm install --create-namespace -n irods-csi-driver irods-csi-driver irods-csi-driver-repo/irods-csi-driver -f ./pool_config.yaml
+```
+
+### Volume Configuration
+
+To configure default volume settings, create a YAML file that adds `globalConfig/secret/stringData`. 
+
+For example, the following sets default `client`, `host`, `port`, `zone`, `user`, `password` for iRODS access.
+
+Set `retainData` to `false` to delete the volume directory in iRODS after use (only for dynamic volume provisioning mode).
+Set `enforceProxyAccess` to `true` for only allowing proxy access to iRODS.
+Set `mountPathWhitelist` to allow mounting certain iRODS paths.
+
+```yaml
+globalConfig:
+  secret:
+    stringData:
+      client: "irodsfuse"
+      host: "bishop.cyverse.org"
+      port: "1247"
+      zone: "cyverse"
+      user: "de-irods"
+      retainData: "false"
+      password: "real-password-here"
+      enforceProxyAccess: "true"
+      mountPathWhitelist: "/cyverse/home"
+```
+
+Then, provide the YAML file when installing `iRODS CSI Driver` using Helm.
+
+```shell script
+helm install --create-namespace -n irods-csi-driver irods-csi-driver irods-csi-driver-repo/irods-csi-driver -f ./volume_config.yaml
+```
+
+

docs/irodsfs_static_volume_provisioning.md

@@ -0,0 +1,190 @@
+# Create a Persistent Volume using iRODS CSI Driver
+
+This document shows how to create a `Persistent Volume (PV)` using `static volume provisioning` in `iRODS CSI Driver`.
+
+## Create a Storage Class (SC)
+
+Define a `Storage Class` with following YAML file (`sc.yaml`).
+
+```yaml
+kind: StorageClass
+apiVersion: storage.k8s.io/v1
+metadata:
+  name: irods-sc # the name of the SC
+provisioner: irods.csi.cyverse.org
+```
+
+Create a Kubernetes object.
+
+```shell script
+kubectl apply -f sc.yaml
+```
+
+Check if the `Storage Class` is created successfully.
+
+```shell script
+kubectl get sc
+```
+
+The command will display following output.
+
+```
+NAME                   PROVISIONER             RECLAIMPOLICY   VOLUMEBINDINGMODE      ALLOWVOLUMEEXPANSION   AGE
+irods-sc               irods.csi.cyverse.org   Delete          Immediate              false                  5s
+local-path (default)   rancher.io/local-path   Delete          WaitForFirstConsumer   false                  7h
+```
+
+## Create a Secret
+
+Define a `Secret` that stores access information with following YAML file (`secret.yaml`).
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: my-secret # the name of the secret
+type: Opaque
+stringData:
+  user: "my_username" # iRODS username
+  password: "my_password" # iRODS password
+```
+
+Create a Kubernetes object.
+
+```shell script
+kubectl apply -f secret.yaml
+```
+
+Check if the `Secret` is created successfully.
+
+```shell script
+kubectl get secret
+```
+
+The command will display following output.
+
+```
+NAME        TYPE     DATA   AGE
+my-secret   Opaque   2      40s
+```
+
+## Create a Persistent Volume (PV)
+
+Define a `Persistent Volume` with following YAML file (`pv.yaml`).
+
+```yaml
+apiVersion: v1
+kind: PersistentVolume
+metadata:
+  name: my-pv # the name of the pv
+  labels:
+    vol-name: my-pv # same as the name
+spec:
+  capacity:
+    storage: 5Gi # this is required but not meaningful (ignored by csi driver)
+  volumeMode: Filesystem
+  accessModes:
+    - ReadWriteMany
+  persistentVolumeReclaimPolicy: Retain
+  storageClassName: irods-sc # the name of Storage Class
+  csi:
+    driver: irods.csi.cyverse.org # the name of iRODS CSI driver
+    volumeHandle: my-vol-id # unique volume ID
+    volumeAttributes:
+      client: "irodsfuse" # iRODS client
+      host: "data.cyverse.org" # iRODS host
+      port: "1247" # iRODS port
+      zone: "iplant" # iRODS zone name
+      path: "/iplant/home/my_username" # iRODS path to mount
+    nodeStageSecretRef:
+      name: "my-secret" # the name of the secret (read user and password from the secret)
+      namespace: "default"
+```
+
+Create a Kubernetes object.
+
+```shell script
+kubectl apply -f pv.yaml
+```
+
+Check if the `Persistent Volume` is created successfully.
+
+```shell script
+kubectl get pv
+```
+
+The command will display following output.
+
+```
+NAME    CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS      CLAIM   STORAGECLASS   VOLUMEATTRIBUTESCLASS   REASON   AGE
+my-pv   5Gi        RWX            Retain           Available           irods-sc       <unset>                          5s
+```
+
+## Create a Persistent Volume Claim (PVC)
+
+Define a `Persistent Volume Claim` with following YAML file (`pvc.yaml`).
+
+```yaml
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: my-pvc # the name of the pvc
+spec:
+  accessModes:
+    - ReadWriteMany
+  storageClassName: irods-sc # the name of Storage Class
+  selector:
+    matchLabels:
+      vol-name: my-pv # the name of the pv
+  resources:
+    requests:
+      storage: 5Gi # this is required but not meaningful (must match to PV's storage capacity)
+```
+
+Create a Kubernetes object.
+
+```shell script
+kubectl apply -f pvc.yaml
+```
+
+Check if the `Persistent Volume Claim` is created successfully.
+
+```shell script
+kubectl get pvc
+```
+
+The command will display following output.
+
+```
+NAME     STATUS   VOLUME   CAPACITY   ACCESS MODES   STORAGECLASS   VOLUMEATTRIBUTESCLASS   AGE
+my-pvc   Bound    my-pv    5Gi        RWX            irods-sc       <unset>                 12s
+```
+
+## Use it in Apps
+
+Mount the iRODS volume using the `Persistent Volume Claim` created above.
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: my-app # the name of the app
+spec:
+  containers:
+  - name: app
+    image: busybox
+    command: ["/bin/sh"]
+    args: ["-c", "echo Hello Kubernetes! $(date -u) >> /data/irods_csi_driver_out.txt"]
+    volumeMounts:
+    - name: persistent-storage # the name of the volume
+      mountPath: /data # mount point
+  restartPolicy: Never
+  volumes:
+  - name: persistent-storage # the name of the volume
+    persistentVolumeClaim:
+      claimName: my-pvc # the name of the PVC
+```
+
+The example app will create a file `irods_csi_driver_out.txt` at `/data` directory in the pod.
+Because the `/data` directory is a mount point where `iRODS CSI Driver` mounts the iRODS path `/iplant/home/my_username` on. 
+So this will create the file `/iplant/home/my_username/irods_csi_driver_out.txt`.

examples/kubernetes/static_volume_provisioning/irodsfuse/app.yaml

@@ -1,18 +1,18 @@
 apiVersion: v1
 kind: Pod
 metadata:
-  name: irods-irodsfuse-app
+  name: my-app # the name of the app
 spec:
   containers:
   - name: app
     image: busybox
     command: ["/bin/sh"]
-    args: ["-c", "echo Hello Kubernetes! $(date -u) >> /data/kubernetes_irodsfuse_out.txt"]
+    args: ["-c", "echo Hello Kubernetes! $(date -u) >> /data/irods_csi_driver_out.txt"]
     volumeMounts:
-    - name: persistent-storage
-      mountPath: /data
+    - name: persistent-storage # the name of the volume
+      mountPath: /data # mount point
   restartPolicy: Never
   volumes:
-  - name: persistent-storage
+  - name: persistent-storage # the name of the volume
     persistentVolumeClaim:
-      claimName: irods-irodsfuse-pvc
+      claimName: my-pvc # the name of the PVC

examples/kubernetes/static_volume_provisioning/irodsfuse/pv.yaml

@@ -1,25 +1,25 @@
 apiVersion: v1
 kind: PersistentVolume
 metadata:
-  name: irods-irodsfuse-pv
+  name: my-pv # the name of the pv
   labels:
-    vol-name: irods-irodsfuse-pv
+    vol-name: my-pv # same as the name
 spec:
   capacity:
-    storage: 5Gi
+    storage: 5Gi # this is required but not meaningful (ignored by csi driver)
   volumeMode: Filesystem
   accessModes:
     - ReadWriteMany
   persistentVolumeReclaimPolicy: Retain
-  storageClassName: irods-sc
+  storageClassName: irods-sc # the name of Storage Class
   csi:
-    driver: irods.csi.cyverse.org
-    volumeHandle: irods-irodsfuse-vol-id
+    driver: irods.csi.cyverse.org # the name of iRODS CSI driver
+    volumeHandle: my-vol-id # unique volume ID
     volumeAttributes:
-      client: "irodsfuse"
-      host: "data.cyverse.org"
-      port: "1247"
-      zone: "iplant"
-      user: "iychoi"
-      password: "yourpassword"
-      path: "/iplant/home/iychoi"
+      client: "irodsfuse" # iRODS client
+      host: "data.cyverse.org" # iRODS host
+      port: "1247" # iRODS port
+      zone: "iplant" # iRODS zone name
+      path: "/iplant/home/my_username" # iRODS path to mount
+      user: "my_username" # iRODS username
+      password: "my_password" # iRODS password

examples/kubernetes/static_volume_provisioning/irodsfuse/pvc.yaml

@@ -1,14 +1,14 @@
 apiVersion: v1
 kind: PersistentVolumeClaim
 metadata:
-  name: irods-irodsfuse-pvc
+  name: my-pvc # the name of the pvc
 spec:
   accessModes:
     - ReadWriteMany
-  storageClassName: irods-sc
+  storageClassName: irods-sc # the name of Storage Class
   selector:
     matchLabels:
-      vol-name: irods-irodsfuse-pv
+      vol-name: my-pv # the name of the pv
   resources:
     requests:
-      storage: 5Gi
+      storage: 5Gi # this is required but not meaningful (must match to PV's storage capacity)

examples/kubernetes/static_volume_provisioning/irodsfuse/storageclass.yaml → examples/kubernetes/static_volume_provisioning/irodsfuse/sc.yaml

@@ -1,5 +1,5 @@
 kind: StorageClass
 apiVersion: storage.k8s.io/v1
 metadata:
-  name: irods-sc
+  name: irods-sc # the name of the SC
 provisioner: irods.csi.cyverse.org