RHIDP-5570-2 - Document that the Dynamic Plugin cache PVC is disabled by default (redhat-developer#998)

Author: Gerry-Forde

modules/dynamic-plugins/con-dynamic-plugins-cache.adoc

@@ -13,10 +13,13 @@ When you enable dynamic plugins cache:
 == Enabling the dynamic plugins cache
 To enable the dynamic plugins cache in {product-very-short}, the plugins directory `dynamic-plugins-root` must be a persistent volume. 
 
-For Helm chart installations, a persistent volume named `dynamic-plugins-root` is automatically created.
+=== Creating a PVC for the dynamic plugin cache by using the Operator
 
-For operator-based installations, you must manually create the PersistentVolumeClaim (PVC) as follows:
+For operator-based installations, you must manually create the persistent volume claim (PVC) by replacing the default `dynamic-plugins-root` volume with a PVC named `dynamic-plugins-root`.
 
+.Procedure
+. Create the persistent volume definition and save it to a file, such as `pvc.yaml`. For example:
++
 [source,yaml]
 ----
 kind: PersistentVolumeClaim
@@ -30,8 +33,23 @@ spec:
     requests:
       storage: 5Gi
 
----
-
+----
++
+[NOTE]
+====
+This example uses `ReadWriteOnce` as the access mode which prevents multiple replicas from sharing the PVC across different nodes. 
+To run multiple replicas on different nodes, depending on your storage driver, you must use an access mode such as `ReadWriteMany`.
+====
+. To apply this PVC to your cluster, run the following command:
++
+[source,terminal]
+----
+oc apply -f pvc.yaml
+----
+. Replace the default `dynamic-plugins-root` volume with a PVC named `dynamic-plugins-root`. For example:
++
+[source,yaml]
+----
 apiVersion: rhdh.redhat.com/v1alpha3
 kind: Backstage
 metadata:
@@ -48,10 +66,77 @@ spec:
                 persistentVolumeClaim:
                   claimName: dynamic-plugins-root
 ----
++
+[NOTE]
+To avoid adding a new volume, you must use the `$patch: replace` directive.
+
+=== Creating a PVC for the dynamic plugin cache using the Helm Chart
+For Helm chart installations, if you require the dynamic plugin cache to persist across pod restarts, you must create a persistent volume claim (PVC) and configure the Helm chart to use it.
 
+.Procedure 
+. Create the persistent volume definition. For example: 
++
+[source,yaml]
+----
+kind: PersistentVolumeClaim
+apiVersion: v1
+metadata:
+  name: dynamic-plugins-root
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 5Gi
+----
++
+[NOTE]
+====
+This example uses `ReadWriteOnce` as the access mode which prevents multiple replicas from sharing the PVC across different nodes. 
+To run multiple replicas on different nodes, depending on your storage driver, you must use an access mode such as `ReadWriteMany`.
+Gerry-Forde marked this conversation as resolved.
+====
+
+. To apply this PVC to your cluster, run the following command:
++
+[source,terminal]
+----
+oc apply -f pvc.yaml
+----
+. Configure the Helm chart to use the PVC. For example:
++
+[source,yaml]
+----
+upstream:
+  backstage:
+    extraVolumes:
+      - name: dynamic-plugins-root
+        persistentVolumeClaim:
+          claimName: dynamic-plugins-root
+      - name: dynamic-plugins
+        configMap:
+          defaultMode: 420
+          name: '{{ printf "%s-dynamic-plugins" .Release.Name }}'
+          optional: true
+      - name: dynamic-plugins-npmrc
+        secret:
+          defaultMode: 420
+          optional: true
+          secretName: '{{ printf "%s-dynamic-plugins-npmrc" .Release.Name }}'
+      - name: dynamic-plugins-registry-auth
+        secret:
+          defaultMode: 416
+          optional: true
+          secretName: '{{ printf "%s-dynamic-plugins-registry-auth" .Release.Name }}'
+      - name: npmcacache
+        emptyDir: {}
+      - name: temp
+        emptyDir: {}
+----
++
 [NOTE]
 ====
-Future versions of the {product-very-short} operator are planned to automatically create the PVC.
+When you configure the Helm chart to use the PVC, you must also include the link:https://github.com/redhat-developer/rhdh-chart/blob/release-{product-version}/charts/backstage/values.yaml#L145-L181[`extraVolumes`] defined in the default Helm chart.
 ====
 
 == Configuring the dynamic plugins cache