Merge pull request #377 from vidispine/fixes-1.34

gre9ory · web-flow · commit 726c82af475c · 2025-11-27T10:31:54.000+01:00
helm 4 compatility, secret handling improvements, template expression…
diff --git a/README.md b/README.md
@@ -22,6 +22,37 @@ One major design aspect of [Helm](https://helm.sh) is that it forces the user to
 
 The primary feature of the HULL library is the ability to remove customized YAML template files entirely from Helm chart workflows and thereby allowing to remove a level of abstraction. Using the HULL library chart, Kubernetes objects including all their properties can be completely and transparently specified in the `values.yaml`. The HULL library chart itself provides the uniform layer to streamline specification, configuration and rendering of Helm charts to achieve this. You can also think of it as a thin layer on top of the Kubernetes API to avoid the middleman between Helm Chart and Kubernetes API object configuration, yet providing flexibility when it is required to customize individual configuration options instead of requiring you to add each configuration switch manually to the templates. JSON schema validation based on the [Helm JSON validation feature](https://helm.sh/docs/topics/charts/#schema-files) (via `values.schema.json`) aids in writing Kubernetes API conforming objects right from the beginning when [using an IDE that supports live JSON schema validation](./hull/doc/json_schema_validation.md). Additional benefits (uniform inheritable object metadata, simplified inclusion of ConfigMaps/Secrets, cross-referencing values within the `values.yaml`, ...) are available with HULL which you can read about below in the **Key Features Overview**. But maybe most importantly, the HULL library can be added as a dependency to any existing Helm chart and be used side-by-side without breaking any existing Helm charts functionalities, see [adding the HULL library chart to a Helm chart](./hull/doc/setup.md) for more information. And lastly, by being a library chart itself, everything works 100% within the functionality that plain Helm offers - no additional tooling is introduced or involved.
 
+### Versioning
+HULL release versions are closely tied to Kubernetes release versions due to the incorporation of the release specific Kubernetes API schemas. Each HULL release branch therefore matches a Kubernetes release branch (such as `1.34`). Kubernetes patch releases provide non-breaking updates to a Kubernetes release while maintaining API stability and therefore play no role in the HULL versioning process. HULL's patch releases contain fixes and changes to HULL alone while maintaining compatibility to the Kubernetes releases API schema. 
+
+HULLs compatibility with Helm matches the respective Kubernetes versions compatibility with Helm, see [Helm Version Support Policy for Helm 4](https://helm.sh/docs/topics/version_skew) and [Helm Version Support Policy for Helm 3](https://helm.sh/docs/v3/topics/version_skew) for the matching version ranges.
+
+Each new release of HULL is thoroughly tested and, unless explicitly noted in the `CHANGELOG.md`, they do not contain breaking changes. Hence, it is usually safe to keep HULL versions up-to-date keeping compatibility with targeted Kubernetes cluster versions in mind.
+
+### Helm v3 vs Helm v4
+
+HULL remains compatible with existing Helm 3 releases and is fully compatible with Helm v4 starting with versions `1.34.2`, `1.33.3` and `1.32.6`. 
+
+However, note that minor (however potentially chart-breaking) differences were introduced on the Helm side when moving to Helm v4:
+
+- (technical) property names under the `Chart` object in the Helm root context have changed. This is with respect to capitalization of first letters mostly (eg. `maintainers` is now `Maintainers`), but for some properties capitalization is changed in multiple places (eg. `apiVersion` is now `APIVersion`).
+
+- treatment of unset values has changed. To clarify what is mean with 'unset', consider property `field_unset` in this snippet:
+
+  ```
+  field_string: "some_text" # string text
+  field_int: 123 # number
+  field_bool: true # boolean
+  field_unset: 
+  field_dict: 
+    key_1: value_1
+  ```
+
+  The behavior of Helm 3, when accessing such a field's property value, was to treat it as an empty string value from observation. This means, the key value pair exists in the `.Values` object tree and it's value is empty and of string type. With Helm 4 on the other hand, the field is absent from the object tree and accessing it will lead to an error.
+
+Both aspects should typically be less relevant for HULL based charts, however it shall be documented here to avoid confusion. More detailed information can be found in the [related Helm issue](https://github.com/helm/helm/issues/31344).
+
+
 **Your feedback on this project is valued, hence please comment or start a discussion in the `Issues` section or create feature wishes and bug reports. Thank you!**
 
 The HULL library chart idea is partly inspired by the [common](
diff --git a/hull/CHANGELOG.md b/hull/CHANGELOG.md
@@ -6,5 +6,6 @@ FIXES:
 - fixed inconsistency in usage of ConfigMap `binaryData` entries. Previously, it was possible to provide the binary data via the `binaryData` entries' value dictionary `path` property when it is stored in an external file or directly as a string value to the `binaryData` entries key, omitting the dictionary structure in the value. To restore the symmetry in usage with a value dictionary, it is now possible to alternatively use the `inline` property in the value dictionary to submit `binaryData` entries, this works the same way as using a string value for the `binaryData` directly.
 
 CHANGES:
+- ensured compatibility with Helm v4 major releases. It is expected that the vast majority of HULL based use cases is unaffected by the major version of the Helm binary used to manage the chart. See the information in the `README.md` about the existing differences between Helm v3 and Helm v4 which _may_ affect HULL based charts as well. To accomodate for these differences, some tests were relaxed or made context aware to the hosting Helm binaries major version.
 - added optional boolean parameter `preEncoded` to Secret `data` entries. If set, the value read from the `inline` property or from an external file with path `path` will not be Base64 encoded by HULL. Instead, if `preEncoded` is set to `true`, the corresponding data content is expected to already be Base64 encoded and HULL will skip auto-encoding it. Setting `preEncoded` to `true` foremost allows to import Base64 encoded (binary) data as from a Secret `data` entry into a pod. Note that when `preEncoded` is set to `true`, the data must be correctly Base64 encoded, otherwise the Kubernetes API will not accept it. The `preEncoded` property applies to Secret `data` only and is ignored on ConfigMap `data` entries. Thanks Armin [sanarena](https://github.com/sanarena) for the feature request!
 - added convenient way to replace a customizable string pattern with double opening and closing curly braces in the rendered final YAML. This is especially helpful when packaging `customresource` objects which in its spec may contain templating expressions using double curly braces, popular examples are CRDs for [External Secrets Operator](https://external-secrets.io/latest/) and [Kyverno](https://kyverno.io/). Since these applications have their own templating engine included, their CustomResources typically contain double curly braces. Using this last minute string replacement technique, it becomes possible to execute HULL transformations on such content containing templating expressions partially targeted for Helm and partially targeted for the downstream application. The post-render string replacement of the downstream applications double curly braces allows for a clear separation of the templating stages. To enable the feature, set both `hull.config.general.postRender.globalStringReplacements.openingDoubleCurlyBraces.enabled` and `hull.config.general.postRender.globalStringReplacements.closingDoubleCurlyBraces.enabled` to `true`. Then, whenever down stream double curly braces need replacing in the rendered result, use `{+{` for opening and `}+}` for closing double curly braces and the placeholders will be replaced with `{{` and `}}` respectively last-minute before submittal to the Kubernetes API. If needed, the placeholder values can be customized in the `hull.config.general.postRender.globalStringReplacements` chart configuration.
diff --git a/hull/HISTORY.md b/hull/HISTORY.md
@@ -6,6 +6,7 @@ FIXES:
 - fixed inconsistency in usage of ConfigMap `binaryData` entries. Previously, it was possible to provide the binary data via the `binaryData` entries' value dictionary `path` property when it is stored in an external file or directly as a string value to the `binaryData` entries key, omitting the dictionary structure in the value. To restore the symmetry in usage with a value dictionary, it is now possible to alternatively use the `inline` property in the value dictionary to submit `binaryData` entries, this works the same way as using a string value for the `binaryData` directly.
 
 CHANGES:
+- ensured compatibility with Helm v4 major releases. It is expected that the vast majority of HULL based use cases is unaffected by the major version of the Helm binary used to manage the chart. See the information in the `README.md` about the existing differences between Helm v3 and Helm v4 which _may_ affect HULL based charts as well. To accomodate for these differences, some tests were relaxed or made context aware to the hosting Helm binaries major version.
 - added optional boolean parameter `preEncoded` to Secret `data` entries. If set, the value read from the `inline` property or from an external file with path `path` will not be Base64 encoded by HULL. Instead, if `preEncoded` is set to `true`, the corresponding data content is expected to already be Base64 encoded and HULL will skip auto-encoding it. Setting `preEncoded` to `true` foremost allows to import Base64 encoded (binary) data as from a Secret `data` entry into a pod. Note that when `preEncoded` is set to `true`, the data must be correctly Base64 encoded, otherwise the Kubernetes API will not accept it. The `preEncoded` property applies to Secret `data` only and is ignored on ConfigMap `data` entries. Thanks Armin [sanarena](https://github.com/sanarena) for the feature request!
 - added convenient way to replace a customizable string pattern with double opening and closing curly braces in the rendered final YAML. This is especially helpful when packaging `customresource` objects which in its spec may contain templating expressions using double curly braces, popular examples are CRDs for [External Secrets Operator](https://external-secrets.io/latest/) and [Kyverno](https://kyverno.io/). Since these applications have their own templating engine included, their CustomResources typically contain double curly braces. Using this last minute string replacement technique, it becomes possible to execute HULL transformations on such content containing templating expressions partially targeted for Helm and partially targeted for the downstream application. The post-render string replacement of the downstream applications double curly braces allows for a clear separation of the templating stages. To enable the feature, set both `hull.config.general.postRender.globalStringReplacements.openingDoubleCurlyBraces.enabled` and `hull.config.general.postRender.globalStringReplacements.closingDoubleCurlyBraces.enabled` to `true`. Then, whenever down stream double curly braces need replacing in the rendered result, use `{+{` for opening and `}+}` for closing double curly braces and the placeholders will be replaced with `{{` and `}}` respectively last-minute before submittal to the Kubernetes API. If needed, the placeholder values can be customized in the `hull.config.general.postRender.globalStringReplacements` chart configuration.
 
diff --git a/hull/README.md b/hull/README.md
@@ -8,6 +8,37 @@ One major design aspect of [Helm](https://helm.sh) is that it forces the user to
 
 The primary feature of the HULL library is the ability to remove customized YAML template files entirely from Helm chart workflows and thereby allowing to remove a level of abstraction. Using the HULL library chart, Kubernetes objects including all their properties can be completely and transparently specified in the `values.yaml`. The HULL library chart itself provides the uniform layer to streamline specification, configuration and rendering of Helm charts to achieve this. You can also think of it as a thin layer on top of the Kubernetes API to avoid the middleman between Helm Chart and Kubernetes API object configuration, yet providing flexibility when it is required to customize individual configuration options instead of requiring you to add each configuration switch manually to the templates. JSON schema validation based on the [Helm JSON validation feature](https://helm.sh/docs/topics/charts/#schema-files) (via `values.schema.json`) aids in writing Kubernetes API conforming objects right from the beginning when [using an IDE that supports live JSON schema validation](./doc/json_schema_validation.md). Additional benefits (uniform inheritable object metadata, simplified inclusion of ConfigMaps/Secrets, cross-referencing values within the `values.yaml`, ...) are available with HULL which you can read about below in the **Key Features Overview**. But maybe most importantly, the HULL library can be added as a dependency to any existing Helm chart and be used side-by-side without breaking any existing Helm charts functionalities, see [adding the HULL library chart to a Helm chart](./doc/setup.md) for more information. And lastly, by being a library chart itself, everything works 100% within the functionality that plain Helm offers - no additional tooling is introduced or involved.
 
+### Versioning
+HULL release versions are closely tied to Kubernetes release versions due to the incorporation of the release specific Kubernetes API schemas. Each HULL release branch therefore matches a Kubernetes release branch (such as `1.34`). Kubernetes patch releases provide non-breaking updates to a Kubernetes release while maintaining API stability and therefore play no role in the HULL versioning process. HULL's patch releases contain fixes and changes to HULL alone while maintaining compatibility to the Kubernetes releases API schema. 
+
+HULLs compatibility with Helm matches the respective Kubernetes versions compatibility with Helm, see [Helm Version Support Policy for Helm 4](https://helm.sh/docs/topics/version_skew) and [Helm Version Support Policy for Helm 3](https://helm.sh/docs/v3/topics/version_skew) for the matching version ranges.
+
+Each new release of HULL is thoroughly tested and, unless explicitly noted in the `CHANGELOG.md`, they do not contain breaking changes. Hence, it is usually safe to keep HULL versions up-to-date keeping compatibility with targeted Kubernetes cluster versions in mind.
+
+### Helm v3 vs Helm v4
+
+HULL remains compatible with existing Helm 3 releases and is fully compatible with Helm v4 starting with versions `1.34.2`, `1.33.3` and `1.32.6`. 
+
+However, note that minor (however potentially chart-breaking) differences were introduced on the Helm side when moving to Helm v4:
+
+- (technical) property names under the `Chart` object in the Helm root context have changed. This is with respect to capitalization of first letters mostly (eg. `maintainers` is now `Maintainers`), but for some properties capitalization is changed in multiple places (eg. `apiVersion` is now `APIVersion`).
+
+- treatment of unset values has changed. To clarify what is mean with 'unset', consider property `field_unset` in this snippet:
+
+  ```
+  field_string: "some_text" # string text
+  field_int: 123 # number
+  field_bool: true # boolean
+  field_unset: 
+  field_dict: 
+    key_1: value_1
+  ```
+
+  The behavior of Helm 3, when accessing such a field's property value, was to treat it as an empty string value from observation. This means, the key value pair exists in the `.Values` object tree and it's value is empty and of string type. With Helm 4 on the other hand, the field is absent from the object tree and accessing it will lead to an error.
+
+Both aspects should typically be less relevant for HULL based charts, however it shall be documented here to avoid confusion. More detailed information can be found in the [related Helm issue](https://github.com/helm/helm/issues/31344).
+
+
 **Your feedback on this project is valued, hence please comment or start a discussion in the `Issues` section or create feature wishes and bug reports. Thank you!**
 
 The HULL library chart idea is partly inspired by the [common](
