Merger options

docs/_docs/config/reference.md

@@ -20,3 +20,4 @@ repo_auto_auth | Whether or not to try to auth authorize docker repo registry if
 skip | List of resources to skip. Can also be set with the `KUBES_SKIP` env var. `KUBES_SKIP` should be a list of strings separated by spaces. It adds onto the `config.skip` option. | []
 state.path | Where to store the state file with the last build Docker image. | .kubes/state/KUBES_ENV/data.json
 suffix_hash | Whether or not to append suffix hash to ConfigMap and Secret | true
+merger.options | Merger options that control how Hashes are merged. More info: [Merger Options]({% link _docs/layering/merge-options.md %}) | `{overwrite_arrays: true}`

docs/_docs/dsl.md

@@ -63,4 +63,4 @@ In general:
 
 ## Merge Behavior
 
-Generally, the merge should behave as expected. For example, map or Hash fields are merged together from multiple layers. Strings are simply replaced. See more details at [Layering Merge Behavior]({% link _docs/layering/merge.md %})
+Generally, the merge should behave as expected. For example, map or Hash fields are merged together from multiple layers. Strings are simply replaced. See more details at [Layering Merge Behavior]({% link _docs/layering/merge-dsl.md %})

docs/_docs/layering.md

@@ -7,4 +7,4 @@ Kubes supports layering files together so you can use the same Kubernetes files
 * [YAML Layering]({% link _docs/layering/yaml.md %})
 * [DSL Layering]({% link _docs/layering/dsl.md %})
 * [Mix Layering]({% link _docs/layering/mix.md %})
-* [Merge Behavior]({% link _docs/layering/merge.md %})
+* [Merge Behavior]({% link _docs/layering/merge-dsl.md %})

docs/_docs/layering/merge-options.md

@@ -0,0 +1,76 @@
+---
+title: Merge Options
+---
+
+Underneath the hood, Kubes uses the [danielsdeleo/deep_merge](https://github.com/danielsdeleo/deep_merge) library to merge layers together. You can control the merge behavior options with [config.merger.options]({% link _docs/config/reference.md %}).
+
+The default merge options is:
+
+    {overwrite_arrays: true}
+
+You can control the merge behavior by setting:
+
+.kubes/config.rb
+
+```ruby
+Kubes.configure do |config|
+  # ...
+  config.merger.options = {overwrite_arrays: false}
+end
+```
+
+See the [danielsdeleo/deep_merge](https://github.com/danielsdeleo/deep_merge) docs for the different options.
+
+## Example of overwrite_arrays false
+
+An example of where you might want to use `{overwrite_arrays: false}` is if you are using YAML and want a base sidecar container in all of your deployments.
+
+.kubes/resources/base/deployment.yaml
+
+```yaml
+spec:
+  template:
+    spec:
+      containers:
+      - name: sidecar
+        image: sidecar-image
+```
+
+.kubes/resources/web/deployment.yaml
+
+```yaml
+spec:
+  template:
+    metadata:
+      labels:
+        role: web
+    spec:
+      containers:
+      - name: web
+        image: <%= docker_image %>
+```
+
+Produces:
+
+```yaml
+# ...
+spec:
+  template:
+    metadata:
+      labels:
+        role: web
+    spec:
+      containers:
+      - name: sidecar
+        image: sidecar-image
+      - name: web
+        image: gcr.io/boltops-learn/demo:kubes-2021-10-21T18-06-48
+# ...
+```
+
+However, using this merge behavior will also add additional ports if you are assigning a `targetPort` in the DSL. See:
+
+* [DSL in service creates always default port 80 #45](https://github.com/boltops-tools/kubes/issues/45)
+* [use deep_merge overwrite_arrays option #48](https://github.com/boltops-tools/kubes/pull/48)
+
+Will welcome PRs for improvements.

docs/_includes/sidebar.html

@@ -97,7 +97,8 @@ <h2><a href="{% link docs.md %}">Docs</a></h2>
           <li><a href="{% link _docs/layering/yaml.md %}">YAML</a></li>
           <li><a href="{% link _docs/layering/dsl.md %}">DSL</a></li>
           <li><a href="{% link _docs/layering/mix.md %}">Mix</a></li>
-          <li><a href="{% link _docs/layering/merge.md %}">Merge Behavior</a></li>
+          <li><a href="{% link _docs/layering/merge-dsl.md %}">Merge DSL</a></li>
+          <li><a href="{% link _docs/layering/merge-options.md %}">Merge Options</a></li>
         </ul>
       </li>
       <li><a href="{% link _docs/dsl.md %}">DSL</a>

lib/kubes/config.rb

@@ -43,6 +43,9 @@ def defaults
 
       config.suffix_hash = true # append suffix hash to ConfigMap and Secret
 
+      config.merger = ActiveSupport::OrderedOptions.new
+      config.merger.options = {overwrite_arrays: true}
+
       config
     end
 

lib/kubes/core.rb

@@ -37,7 +37,7 @@ def check_project!
 
     # wrapper to ensure we use the same deeper_merge options everywhere
     def deep_merge!(a, b)
-      a.deeper_merge!(b, overwrite_arrays: true)
+      a.deeper_merge!(b, config.merger.options)
       a
     end
   end