Merge pull request #336 from vidispine/release-1.31

fix hashsum bug, namespaceoverride, include in tpl transformation

azure-pipelines-gated.yml

@@ -39,6 +39,12 @@ jobs:
       Helm_3_15_4_multi: 
         HelmVersion: "3.15.4"
         TestType: multi
+      Helm_3_16_1_single: 
+        HelmVersion: "3.16.1"
+        TestType: single
+      Helm_3_16_1_multi: 
+        HelmVersion: "3.16.1"
+        TestType: multi
   steps:
   - template: azure-pipelines-test.yml  # Template reference
     parameters:

azure-pipelines.yml

@@ -103,6 +103,18 @@ jobs:
       Helm_3_15_4_multi: 
         HelmVersion: "3.15.4"
         TestType: multi
+      Helm_3_16_0_single: 
+        HelmVersion: "3.16.0"
+        TestType: single
+      Helm_3_16_0_multi: 
+        HelmVersion: "3.16.0"
+        TestType: multi
+      Helm_3_16_1_single: 
+        HelmVersion: "3.16.1"
+        TestType: single
+      Helm_3_16_1_multi: 
+        HelmVersion: "3.16.1"
+        TestType: multi
   steps:
   - template: azure-pipelines-test.yml  # Template reference
     parameters:

hull/CHANGELOG.md

@@ -1,7 +1,11 @@
 # Changelog
 ------------------
-[1.31.0]
+[1.31.1]
 ------------------
+FIXES:
+- fixed follow-up problem with a previous fix for calculation of `hashsumAnnotation` for ConfigMaps or Secrets. In an unlikely case, where a ConfigMap or Secret object has no `data` property set and is then disabled, an unintended error was thrown. ConfigMaps or Secrets with no actual `data` properties can now be disabled without the `hashsumAnnotation` functionality failing. 
+
 CHANGES:
-- initial K8S 1.31 release
-- deprecating 1.28 release
+- added include shortform transformation `_HT/` to the allowed transformations that can be used within `_HT!` tpl transformations. Similar to using the `_HT*` get syntax within `_HT!` transformations, the `_HT/` include syntax is now embeddable as well. To delimit the `_HT/` arguments from the rest of the `_HT!` content, the `_HT/` block must have a clear ending suffix `/TH_`, similar to bashs `if`/`fi` style. For example, the following syntax now executes the include function within the tpl content: `_HT!{{- printf "%s-%s" _HT/hull.metadata.name:COMPONENT:"tpl-include"/TH_ "example" -}}`
+- added possibility to override individual object instance namespaces by setting an optional `namespaceOverride` property on the object instance. CAUTION: creating objects in multiple namespaces _may_ go against Helm principles since normally all objects are created only in the release namespace!  
+- added more example `values.yaml` files to `files/examples` and updated outdated ones

hull/Chart.yaml

@@ -1,6 +1,6 @@
 apiVersion: v2
 name: hull
-version: "1.31.0"
+version: "1.31.1"
 description: HULL - Helm Uniform Layer Library
 type: library
 keywords:

hull/HISTORY.md

@@ -1,4 +1,15 @@
 # History
+------------------
+[1.31.1]
+------------------
+FIXES:
+- fixed follow-up problem with a previous fix for calculation of `hashsumAnnotation` for ConfigMaps or Secrets. In an unlikely case, where a ConfigMap or Secret object has no `data` property set and is then disabled, an unintended error was thrown. ConfigMaps or Secrets with no actual `data` properties can now be disabled without the `hashsumAnnotation` functionality failing. 
+
+CHANGES:
+- added include shortform transformation `_HT/` to the allowed transformations that can be used within `_HT!` tpl transformations. Similar to using the `_HT*` get syntax within `_HT!` transformations, the `_HT/` include syntax is now embeddable as well. To delimit the `_HT/` arguments from the rest of the `_HT!` content, the `_HT/` block must have a clear ending suffix `/TH_`, similar to bashs `if`/`fi` style. For example, the following syntax now executes the include function within the tpl content: `_HT!{{- printf "%s-%s" _HT/hull.metadata.name:COMPONENT:"tpl-include"/TH_ "example" -}}`
+- added possibility to override individual object instance namespaces by setting an optional `namespaceOverride` property on the object instance. CAUTION: creating objects in multiple namespaces _may_ go against Helm principles since normally all objects are created only in the release namespace!  
+- added more example `values.yaml` files to `files/examples` and updated outdated ones
+
 ------------------
 [1.31.0]
 ------------------

hull/doc/README.md

@@ -0,0 +1 @@
+This folder contains the detailed documentation of the HULL library.

hull/doc/objects_base.md

@@ -12,6 +12,7 @@ You can add the following optional properties to any object specified via HULL:
 | --------  | -------------| ------- | --------
 `staticName` | A boolean switch. If set to true the object does not get a dynamically created name (see above) assigned but a name that only consists of the key name. Using static names is helpful in case you need to address the object from another Kubernetes object that is not part of the Helm chart and hence you want to refer to particular object in the cluster by a fixed name. Note that by setting `hull.config.general.noObjectNamePrefixes` to `true`, the individual `staticName` settings have no effect anymore | `false` | `true`<br>`false`
 `metadataNameOverride` | A string field which overwrites the object instances component part in `metadata.name` and provides the full value of `metadata.labels.app.kubernetes.io/component`. While normally it is appropriate and convenient to derive the object instance names from the instance key in the object types dictionary, there may be special cases where having the possibility to alter the `metadata.name` of a defined object instance at deployment time is helpful.
+`namespaceOverride` | A string field which, if set to a value that is not empty, overwrites the object instances `namespace`. CAUTION: Use with care since this _may_ not be supported Helm behavior to create objects in multiple namespaces within a single chart.
 `enabled` | Needs to resolve to a boolean switch, it can be a boolean input directly or a transformation that resolves to a boolean value. If resolved to true or missing, the object will be rendered for deployment. If resolved to false, it will be omitted. This way you can predefine objects which are only enabled and created in the cluster in certain environments when needed. | `true` | `true`<br>`false`<br><br>`"_HULL_TRANSFORMATION_<<<NAME=hull.util.transformation.tpl>>><<<CONTENT=`<br>&#160;&#160;`{{`&#160;`(index`&#160;`.`&#160;`\"PARENT\").Values.hull.config.specific.enable_addon`&#160;`}}>>>"`
 `annotations` | Dictionary with annotations to add to the Kubernetes objects main `metadata.annotations` section. The annotation value must be of string type on the Kubernetes side, but it is allowed to have boolean, integer or float type input on the HULL side. Any value will be automatically converted to string on rendering. | `{}` | `appImportance:`&#160;`"very`&#160;`low"`<br>`appStatus:`&#160;`"good"`
 `labels` | Dictionary with labels to add to the Kubernetes objects main `metadata.labels` section. The label value must be of string type on the Kubernetes side, but it is allowed to have boolean, integer or float type input on the HULL side. Any value will be automatically converted to string on rendering. | | `label-1:`&#160;`DB_TYPE`<br>`label-2:`&#160;`"false"`<br>`label-3:`&#160;`false`<br>`label-4:`&#160;`true`<br>`label-5:`&#160;`"123"`<br>`label-6:`&#160;`123`<br>`label-7:`&#160;`"3.14"`<br>`label-8:`&#160;`3.14` | 

hull/doc/transformations.md

@@ -618,6 +618,23 @@ hull:
                 ]
 ```
 
+Additionally the `include` short form transformation `_HT/` is now also available for use within `_HT!` content! To correctly delimit the `_HT/` parameters from the remaining `_HT!` content, it needs to be ended with a `/TH_` suffix, similar to a bash `if`/`fi` start/end tag. 
+
+Here is a brief example on how to put `_HT/` transformations into the `_HT!` content:
+
+```yaml
+value: |-
+  _HT!
+    {{- printf "%s is the chart reference value" _HT/hull.
+    metadata.chartref/TH_ -}}
+```
+
+This will render similar to the below, depending on your parents helm charts name and version:
+
+```yaml
+value: hull-test-1.31.0 is the chart reference value
+```
+
 More detailed on this feature is available in the below section on _hull.util.transformation.tpl_ transformations.
 
 ## Provided transformations
@@ -702,7 +719,7 @@ Provides an easy to use shortcut to simply get the value of a field in `values.y
 
 ⚠️ **In case the referenced value should be manipulated in any other way you can use `_HT!` transformations in combination with the `_HT*` reference style. For more information see the 'Example of a complex custom transformation' above and the `hull.util.transformation.tpl` section below** ⚠️
 
-When used in the `values.yaml` context, any complex object (dictionary or array) referenced will in fact be inserted as an object with further leaves into the `values.yaml` tree. This is very powerful since it allows to reuse larger configuration parts multiple times. But in some cases you may want to serialize the referenced dictionary or list object into a JSON or YAML string, for this you have the additional possibility to prefix the REFERENCE with one of the following prefixes:
+When used in the `values.yaml` context, any complex object (dictionary or array) referenced will in fact be inserted as an object with further leafes into the `values.yaml` tree. This is very powerful since it allows to reuse larger configuration parts multiple times. But in some cases you may want to serialize the referenced dictionary or list object into a JSON or YAML string, for this you have the additional possibility to prefix the REFERENCE with one of the following prefixes:
 
 - `toJson`
 - `toPrettyJson`
@@ -802,7 +819,7 @@ The processed result of executing `tpl` on the string. Depending on where this t
 
 The most powerful transformation that allows to freely specify the Go templating expression(s) to be evaluated. Care needs to be taken so that the returned string can be converted to the desired return type if it is not string.
 
-Consider using the `_HT*` reference style to address fields in the `values.yaml` for more compact style and less typing. The full range of `_HT*` usage is available, hence you can also use `_HT**` for root context access or serialization instructions as in `_HT*toJson|hull.config.xyz`.
+Consider using the `_HT*` reference style within the `_HT!` content to address fields in the `values.yaml` for more compact style and less typing. The full range of `_HT*` usage is available, hence you can also use `_HT**` for root context access or serialization instructions as in `_HT*toJson|hull.config.xyz`.
 
 #### __Combinations__
 
@@ -830,7 +847,7 @@ you may use the most concise form:
 string: _HT!*_HT*hull.config.specific.some_referenced_value | lower
 ```
 
-All three variants yield the same result.
+All three variants yield the same result. 
 
 
 #### __Short Form Examples__
@@ -862,7 +879,7 @@ ports: # dictionary-form transformation style
       }
 ```
 
-### Call an `incude` function (_hull.util.transformation.include_)
+### Call an `include` function (_hull.util.transformation.include_)
 
 #### __Arguments__
 
@@ -908,6 +925,17 @@ name_tpl: _HT!{{ include "hull.metadata.name" (dict "PARENT_CONTEXT" (index . "$
 name_include: _HT/hull.metadata.name:COMPONENT:"test"
 ```
 
+⚠️ **In case the referenced value should be manipulated in any other way you can use `_HT!` transformations in combination with the `_HT/` include style! For more information see the 'Example of a complex custom transformation' above and the `hull.util.transformation.tpl` section below** ⚠️
+
+Hence the following:
+
+```yaml
+name_include_in_tpl: _HT!{{ _HT/hull.metadata.name/COMPONENT:"test" }}
+name_include: _HT/hull.metadata.name:COMPONENT:"test"
+```
+
+also delivers identical results while the `name_include_in_tpl` expression provides the possibility to further manipulate the returned value.
+
 It is possible to not only return simple strings but also complex dictionaries or arrays produced by the `include`. Without an extra serialization prefix the resulting object tree or list is inserted into the `values.yaml`.
 
 In case of an expected YAML dictionary, you can optionally denote a dictionary key in the result to get the key's values from and insert them instead of the dictionaries root key itself. If no optional dictionary key is provided, the complete dictionary returned is the result. The following example will expand on this feature and explain the difference.

hull/files/examples/README.md

@@ -0,0 +1,3 @@
+This folder contains example `values.yaml` files from various self created Helm charts, ranging from simpler ones like `eventrouter_values.yaml` to complex ones like `authservice_values.yaml`.
+
+Note that any additional external files that may be referenced in the `values.yaml`s are not contained here!