Update documentation for overlay configmaps

horizon/README.md

@@ -25,6 +25,70 @@ helm install monms opennms/horizon --set domain=domain1.com  --create-namespace
 | ----------- | ----------- | ----------- |
 | 1.x | Horizon 32.x | Meridian 2023.x |
 
+## Overlay ConfigMaps
+
+The chart supports specifying a list of ConfigMaps with `core.overlayConfigMaps` that will be copied to the OpenNMS container overlay directory in the init container. This can be used to provide configuration files for OpenNMS. There are two ways to provide content in each ConfigMap:
+
+### Plain files
+
+Provide one or more plain files (text and/or binary) in the ConfigMap and specify the directory where these files we be copied.
+
+Here is a configuration example:
+
+```
+core:
+  overlayConfigMaps:
+    - name: "my-etc-files"
+      path: "etc"
+```
+
+Here is an example of how to create the ConfigMap:
+
+```
+instance=<helm release name> # make sure to set to your Helm release name
+configmap=my-etc-files
+
+mkdir etc
+date > etc/testing-configmap
+
+kubectl create configmap -n $instance $configmap --from-file=etc
+```
+
+### ZIP files
+
+Provide one or more ZIP files in the ConfigMap, and each will be extracted in alphabetical order at the root of the overlay directory.
+
+Here is a configuration example:
+
+```
+core:
+  overlayConfigMaps:
+    - name: "my-zip-files"
+      unzip: true
+```
+
+Here is an example of how to create the ConfigMap:
+
+```
+instance=<helm release name> # make sure to set to your Helm release name
+configmap=my-zip-files
+
+mkdir -p zip/etc
+dd if=/dev/zero bs=1k count=5000 of=zip/etc/lots-of-zeros # make a 5 MB test file
+( cd zip && zip -r -o ../lots-of-zeros.zip . )
+
+kubectl create configmap -n $instance $configmap --from-file=lots-of-zeros.zip
+```
+
+### Overlay ConfigMap Notes
+
+1. This mechanism can only be used to *add* files. When `etc` files are copied into the `onms-etc-pvc` PVC, removing a file from the ConfigMap will not cause the file in the PVC to be *deleted*. In this case, you will need to delete the file manually **after** updating the ConfigMap to remove the file. You can do this with `kubectl exec -n $instance onms-core-0 -- rm etc/testing-configmap`.
+2. ConfigMaps cannot contain recursive directory structures--only files. If you need to put files into multiple directories, each directory will need to be its own ConfigMap. `kubectl create configmap` will silently ignore sub-directories.
+3. ConfigMaps can't be larger than 1 MB (see the note [here](https://kubernetes.io/docs/concepts/configuration/configmap/#motivation). If you have more content, it will need to be split across multiple ConfigMaps or compressed into ZIP files.
+4. Use `kubectl delete configmap -n $instance $configmap` to delete an existing ConfigMap before updating.
+5. After updating a ConfigMap, you will need to restart the pod, for example: `kubectl rollout restart -n $instance statefulset/onms-core`
+6. You can use `kubectl get configmap -n $instance $configmap -o yaml` to view the ConfigMap that is created.
+
 ## Values
 
 | Key | Type | Default | Description |

horizon/README.md.gotmpl

@@ -25,6 +25,70 @@ helm install monms opennms/horizon --set domain=domain1.com  --create-namespace
 | ----------- | ----------- | ----------- |
 | 1.x | Horizon 32.x | Meridian 2023.x |
 
+## Overlay ConfigMaps
+
+The chart supports specifying a list of ConfigMaps with `core.overlayConfigMaps` that will be copied to the OpenNMS container overlay directory in the init container. This can be used to provide configuration files for OpenNMS. There are two ways to provide content in each ConfigMap:
+
+### Plain files
+
+Provide one or more plain files (text and/or binary) in the ConfigMap and specify the directory where these files we be copied.
+
+Here is a configuration example:
+
+```
+core:
+  overlayConfigMaps:
+    - name: "my-etc-files"
+      path: "etc"
+```
+
+Here is an example of how to create the ConfigMap:
+
+
+```
+instance=<helm release name> # make sure to set to your Helm release name
+configmap=my-etc-files
+
+mkdir etc
+date > etc/testing-configmap
+
+kubectl create configmap -n $instance $configmap --from-file=etc
+```
+
+### ZIP files
+
+Provide one or more ZIP files in the ConfigMap, and each will be extracted in alphabetical order at the root of the overlay directory.
+
+Here is a configuration example:
+
+```
+core:
+  overlayConfigMaps:
+    - name: "my-zip-files"
+      unzip: true
+```
+
+Here is an example of how to create the ConfigMap:
+
+```
+instance=<helm release name> # make sure to set to your Helm release name
+configmap=my-zip-files
+
+mkdir -p zip/etc
+dd if=/dev/zero bs=1k count=5000 of=zip/etc/lots-of-zeros # make a 5 MB test file
+( cd zip && zip -r -o ../lots-of-zeros.zip . )
+
+kubectl create configmap -n $instance $configmap --from-file=lots-of-zeros.zip
+```
+
+### Overlay ConfigMap Notes
+
+1. This mechanism can only be used to *add* files. When `etc` files are copied into the `onms-etc-pvc` PVC, removing a file from the ConfigMap will not cause the file in the PVC to be *deleted*. In this case, you will need to delete the file manually **after** updating the ConfigMap to remove the file. You can do this with `kubectl exec -n $instance onms-core-0 -- rm etc/testing-configmap`.
+2. ConfigMaps cannot contain recursive directory structures--only files. If you need to put files into multiple directories, each directory will need to be its own ConfigMap. `kubectl create configmap` will silently ignore sub-directories.
+3. ConfigMaps can't be larger than 1 MB (see the note [here](https://kubernetes.io/docs/concepts/configuration/configmap/#motivation). If you have more content, it will need to be split across multiple ConfigMaps or compressed into ZIP files.
+4. Use `kubectl delete configmap -n $instance $configmap` to delete an existing ConfigMap before updating.
+5. After updating a ConfigMap, you will need to restart the pod, for example: `kubectl rollout restart -n $instance statefulset/onms-core`
+6. You can use `kubectl get configmap -n $instance $configmap -o yaml` to view the ConfigMap that is created.
 
 {{ template "chart.valuesSection" . }}