You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+34-1Lines changed: 34 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -22,6 +22,37 @@ One major design aspect of [Helm](https://helm.sh) is that it forces the user to
22
22
23
23
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.
24
24
25
+
### Versioning
26
+
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.
27
+
28
+
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.
29
+
30
+
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.
31
+
32
+
### Helm v3 vs Helm v4
33
+
34
+
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`.
35
+
36
+
However, note that minor (however potentially chart-breaking) differences were introduced on the Helm side when moving to Helm v4:
37
+
38
+
- (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`).
39
+
40
+
- treatment of unset values has changed. To clarify what is mean with 'unset', consider property `field_unset` in this snippet:
41
+
42
+
```
43
+
field_string: "some_text" # string text
44
+
field_int: 123 # number
45
+
field_bool: true # boolean
46
+
field_unset:
47
+
field_dict:
48
+
key_1: value_1
49
+
```
50
+
51
+
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.
52
+
53
+
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).
54
+
55
+
25
56
**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!**
26
57
27
58
The HULL library chart idea is partly inspired by the [common](
@@ -271,10 +302,12 @@ In contrast to the `config.specific` section, which should be populated with arb
271
302
| `render.emptyTemplateLabels` | If `true`, HULL renders out `labels: {}` in the `template` of pods ` if no labels exist for an object, if `false` the `labels` key is omitted. | `false` | `true`
272
303
| `render.emptyHullObjects` | If `true`, HULL renders out arrays as empty arrays if no elements exist for some fields processed by HULL. If false, the key-value pair is ommited. <br><br> This affects fields which are mapped from a dictionary in HULL configuration to a Kubernetes array in the rendered YAML. The following is a list of affected fields in HULL's object configuration:<br><br><ul><li>`data` in `secret` and `configmap` objects</li><li>`initContainers`, `containers`, `volumes` and `imagePullSecrets` in `cronjob`,`daemonset`, `deployment`, `job` and `statefulset` `pod` objects</li><li>`ports`, `env`, `envFrom` and `volumeMounts` in `initContainers`, `containers` and `volumes` in `cronjob`,`daemonset`, `deployment`, `job` and `statefulset` `pod` objects</li><li>`ports` in `service` objects</li><li>`rules` and `tls` in `ingress` objects</li><li>`http.paths` in `rules` in `ingress` objects</li><li>`webhooks` in `validatingwebhookconfiguration` and `mutatingwebhookconfiguration`</li><li>`rules` in `clusterrole` and `role`</li>| `false` | `true`
273
304
| `postRender` | After HULL has fully rendered an object it is possible to manipulate the resulting YAML string. Possibilities to do so are provided as `postRender` actions here. <br><br><b>WARNING: Use with caution as this may corrupt the YAML structure!</b> | | |
274
-
| `postRender.globalStringReplacements` | A dictionary of replacement possibilities that may be applied to the rendered object's YAML. The main use case for this is in combination with extensive defaulting in `_HULL_OBJECT_TYPE_DEFAULT_` and `sources` object instances where it allows to inject instance specific strings into the defaulted YAML. The preconfigured mappings provided may be `enabled: true` on demand. Each mapping consists of following fields:<ul><li>`enabled`: execute mapping if `true`</li><li>`string`: the exact string part to be replaced</li><li>`replacement`: the type of value inserted instead of `string`. Not a free string but one of the following values: `OBJECT_INSTANCE_KEY`, `OBJECT_INSTANCE_KEY_RESOLVED` or `OBJECT_INSTANCE_NAME`
305
+
| `postRender.globalStringReplacements` | A dictionary of replacement possibilities that may be applied to the rendered object's YAML. The main use case for this is in combination with extensive defaulting in `_HULL_OBJECT_TYPE_DEFAULT_` and `sources` object instances where it allows to inject instance specific strings into the defaulted YAML. Also, for down stream content that needs to preserve double curly braces as used in templating expressions, it allows to replace custonmizable placeholders with double curly opening and closing braces. The preconfigured mappings provided may be `enabled: true` on demand. Each mapping consists of following fields:<ul><li>`enabled`: execute mapping if `true`</li><li>`string`: the exact string part to be replaced</li><li>`replacement`: the type of value inserted instead of `string`. Can be one of the following static values `OBJECT_INSTANCE_KEY`, `OBJECT_INSTANCE_KEY_RESOLVED` and `OBJECT_INSTANCE_NAME` which are interpreted and resolved as explained below. Any other value is treated as a string value.
275
306
| `postRender.globalStringReplacements.instanceKey` | If `enabled`, the `string` value will be replaced with the actual object's `instance_key` as in `hull.objects.<object_type>.<instance_key>`. The value of `replacement` is `OBJECT_INSTANCE_KEY` for this mapping. | `instanceKey:`<br>  `enabled:` `false`<br>  `string:` `_HULL_OBJECT_TYPE_DEFAULT_`<br>  `replacement:` `OBJECT_INSTANCE_KEY` |
276
307
| `postRender.globalStringReplacements.instanceKeyResolved` | If `enabled`, the `string` value will be replaced with the actual object's `instance_key` as in `hull.objects.<object_type>.<instance_key>` or by `hull.objects.<object_type>.<instance_key>.metadataNameOverride` if this is defined. The value of `replacement` is `OBJECT_INSTANCE_KEY_RESOLVED` for this mapping. | `instanceKeyResolved:`<br>  `enabled:` `false`<br>  `string:` `_HULL_OBJECT_TYPE_DEFAULT_`<br>  `replacement:` `OBJECT_INSTANCE_KEY_RESOLVED`
277
308
| `postRender.globalStringReplacements.instanceName` | If `enabled`, the `string` value will be replaced with the actual object's rendered `metadata.name`. The value of `replacement` is `OBJECT_INSTANCE_NAME` for this mapping. | `instanceName:`<br>  `enabled:` `false`<br>  `string:` `_HULL_OBJECT_TYPE_DEFAULT_`<br>  `replacement:` `OBJECT_INSTANCE_NAME`
309
+
| `postRender.globalStringReplacements.openingDoubleCurlyBraces` | If `enabled`, the `string` value (default `{+{`) will be replaced with opening double curly braces `{{`. The value of `replacement` is thus `{{` for this mapping. | `openingDoubleCurlyBraces:`<br>  `enabled:` `false`<br>  `string:` `{+{`<br>  `replacement:` `{{`
310
+
| `postRender.globalStringReplacements.closingDoubleCurlyBraces` | If `enabled`, the `string` value (default `}+}`) will be replaced with closing double curly braces `}}`. The value of `replacement` is thus `}}` for this mapping. | `closingDoubleCurlyBraces:`<br>  `enabled:` `false`<br>  `string:` `}+}`<br>  `replacement:` `}}`
278
311
| `serialization` | General serialization options. |
279
312
| `serialization.configmap.enabled` | If `enabled`, the mapped file extensions under `fileExtensions` are serialized with the given serialization method by default. If the `data` key ends with one of the mapped extensions the serialization method in the value is used to write the content to string. A specific `serialization` field on a configmaps `data` entry overwrites any default settings. | `true`
280
313
| `serialization.configmap.fileExtensions` | A dictionary of mappings from file extensions to serialization methods. | `fileExtensions:`<br>  `json:` `toPrettyJson`<br>  `yaml:` `toYaml`<br>  `yml:` `toYaml`
0 commit comments