add instructions for st2.packs.volumes values

Author: cognifloyd

README.md

@@ -140,7 +140,7 @@ st2:
       - name: circleci
         ref: circle_ci.CircleCIWebhookSensor
 ```
-	
+
 ### [st2actionrunner](https://docs.stackstorm.com/reference/ha.html#st2actionrunner)
 Stackstorm workers that actually execute actions.
 `5` replicas for K8s Deployment are configured by default to increase StackStorm ability to execute actions without excessive queuing.
@@ -181,15 +181,23 @@ StackStorm employs redis sentinel as a distributed coordination backend, require
 As any other Helm dependency, it's possible to further configure it for specific scaling needs via `values.yaml`.
 
 ## Install custom st2 packs in the cluster
-In distributed environment of the Kubernetes cluster `st2 pack install` won’t work.
+There are two ways to install st2 packs in the k8s cluster.
+
+1. The `st2packs` method is the default. This method will work for practically all clusters, but `st2 pack install` does not work. The packs are injected via `st2packs` images instead.
+
+2. The other method defines shared/writable `volumes`. This method allows `st2 pack install` to work, but requires a persistent storage backend to be available in the cluster. This chart will not configure a storage backend for you.
+
+### Method 1: st2packs images (the default)
+The `st2packs` method is the default. `st2 pack install` does not work because this chart uses read-only `emptyDir` volumes for `/opt/stackstorm/{packs,virtualenvs}`.
 Instead, you need to bake the packs into a custom docker image, push it to a private or public docker registry and reference that image in Helm values.
-Helm chart will take it from there, sharing `/opt/stackstorm/{packs,virtualenvs}` via a sidecar container in pods which require access to the packs.
+Helm chart will take it from there, sharing `/opt/stackstorm/{packs,virtualenvs}` via a sidecar container in pods which require access to the packs
+(the sidecar is the only place where the volumes are writable).
 
-### Building st2packs image
+#### Building st2packs image
 For your convenience, we created a new `st2-pack-install <pack1> <pack2> <pack3>` utility and included it in a container that will help to install custom packs during the Docker build process without relying on live DB and MQ connection.
 Please see https://github.com/StackStorm/st2packs-dockerfiles/ for instructions on how to build your custom `st2packs` image.
 
-### How to provide custom pack configs
+#### How to provide custom pack configs
 Update the `st2.packs.configs` section of Helm values:
 
 For example:
@@ -205,7 +213,7 @@ For example:
 ```
 Don't forget running Helm upgrade to apply new changes.
 
-### Pull st2packs from a private Docker registry
+#### Pull st2packs from a private Docker registry
 If you need to pull your custom packs Docker image from a private repository, create a Kubernetes Docker registry secret and pass it to Helm values.
 See [K8s documentation](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) for more info.
 ```
@@ -214,6 +222,69 @@ kubectl create secret docker-registry st2packs-auth --docker-server=<your-regist
 ```
 Once secret created, reference its name in helm value: `st2.packs.images[].pullSecret`.
 
+### Method 2: Shared Volumes
+This method requires cluster-specific storage setup and configuration. As the storage volumes are both writable and shared, `st2 pack install` should work like it does for standalone StackStorm installations. The volumes get mounted at `/opt/stackstorm/{packs,virtualenvs}` in the containers that need read or write access to those directories. With this method, `/opt/stackstorm/configs` can also be mounted as a writable volume instead of using `st2.packs.configs`.
+
+#### Configure the storage volumes
+Enable the `st2.packs.voluems` section of Helm values and add volume definitions for both `packs` and `virtualenvs`.
+Each of the volume definitions should be customized for your cluster and storage solution.
+
+NOTE: Make sure that `st2.packs.images` is empty. This method does not use or work with the `st2packs` images.
+
+For example, to use persistentVolumeClaims:
+```
+  volumes:
+    enabled: true
+    packs:
+      persistentVolumeClaim:
+        claim-name: pvc-st2-packs
+    virtualenvs:
+      persistentVolumeClaim:
+        claim-name: pvc-st2-virtualenvs
+```
+
+Or, for example, to use NFS:
+```
+  volumes:
+    enabled: true
+    packs:
+      nfs:
+        server: nfs.example.com
+        path: /var/nfsshare/packs
+    virtualenvs:
+      nfs:
+        server: nfs.example.com
+        path: /var/nfsshare/virtualenvs
+```
+
+Please consult the documentation for your cluster's storage solution to see how to add the storage backend to your cluster and how to define volumes that use your storage backend.
+
+#### How to provide custom pack configs
+You may either use the `st2.packs.configs` section of Helm values (like Method 1, see above),
+or add another shared writable volume similar to `packs` and `virtualenvs`. This volume gets mounted
+to `/opt/stackstorm/configs` instead of the `st2.packs.config` values. NOTE: If you define a configs volume,
+anything in `st2.packs.configs` will NOT be visible to StackStorm.
+
+For example, to use persistentVolumeClaims:
+```
+  volumes:
+    enabled: true
+    ... # define packs and virtualenvs volumes as shown above
+    configs:
+      persistentVolumeClaim:
+        claim-name: pvc-st2-pack-configs
+```
+
+Or, for example, to use NFS:
+```
+  volumes:
+    enabled: true
+    ... # define packs and virtualenvs volumes as shown above
+    configs:
+      nfs:
+        server: nfs.example.com
+        path: /var/nfsshare/configs
+```
 
 ## Tips & Tricks
 Grab all logs for entire StackStorm cluster with dependent services in Helm release: