ROX-27332,ROX-27333: Overlays for configmaps

modules/customize-installation-operator-overlays.adoc

@@ -39,21 +39,21 @@ The following example shows the structure of an overlay:
 [source,yaml]
 ----
 overlays:
-- apiVersion: v1     # <1>
-  kind: ConfigMap    # <2>
-  name: my-configmap # <3>
+- apiVersion: v1         # <1>
+  kind: ExampleKind      # <2>
+  name: my-resource      # <3>
   patches:
-    - path: .data    # <4>
-      value: |       # <5>
+    - path: .some.field  # <4>
+      value: |           # <5>
         key1: data2
         key2: data2
 ----
 
 <1> Targeted Kubernetes resource ApiVersion, for example `apps/v1`, `v1`, `networking.k8s.io/v1`
 <2> Resource type (e.g., Deployment, ConfigMap, NetworkPolicy)
-<3> Name of the resource, for example `my-configmap`
+<3> Name of the resource, for example `my-resource`
 <4> JSONPath expression to the field, for example `spec.template.spec.containers[name:central].env[-1]`
-<5> YAML string for the new field value
+<5> YAML string for the new field value. If you do not want to use YAML parsing, you can use the `verbatim` key as shown in the following ConfigMap example.
 
 [id="adding-an-overlay_{context}"]
 === Adding an overlay
@@ -157,12 +157,21 @@ spec:
       kind: ConfigMap
       name: central-endpoints
       patches:
-      - path: data
-        value: |
-          endpoints.yaml: |
-            disableDefault: false
+      - path: data.endpoints\.yaml
+        verbatim: |
+          disableDefault: false
+          # another line
 ----
 
+This example shows how to override only a single item (file) under `data`.
+
+Follow this example by taking these steps:
+
+* Use the `verbatim` key, rather than `value`.
+This helps pass through characters such as newlines or quotes so that they are unaffected.
+* You must escape the dot in the filename in the `path` key as shown, or
+ you can write the path as `data["endpoints.yaml"]`.
+
 [id="adding-a-container-to-a-deployment_{context}"]
 === Adding a container to the `Central` deployment