HULL: Helm Uniform Layer Library

Abstractions need to be maintained - Kelsey Hightower

⚠️ Breaking change in 1.37.0: the default RBAC objects are opt-in

Up to and including HULL 1.36.0, every HULL based chart rendered a default ServiceAccount, a default Role and a default RoleBinding unless a global pod serviceAccountName was configured under hull.config.templates.pod.global. Pods that did not specify a serviceAccountName themselves were automatically wired to that default ServiceAccount.

Starting with 1.37.0 these three objects are not created anymore by default. They are opt-in via the new hull.config.general.createDefaultRbacTriplet switch:

hull:
  config:
    general:
      createDefaultRbacTriplet: true # restores the pre-1.37.0 behavior

What happens when upgrading without setting the switch to true:

• the default ServiceAccount, default Role and default RoleBinding are removed from the release on the next helm upgrade
• pods that do not set a serviceAccountName no longer get one rendered, so Kubernetes assigns the namespace's own default ServiceAccount to them instead
• if your chart customizes one of the three objects, rendering fails instead of silently dropping the configuration: this applies to annotations on the default ServiceAccount (for example an IRSA eks.amazonaws.com/role-arn), rules on the default Role and a changed roleRef or subjects on the default RoleBinding. Set createDefaultRbacTriplet: true to keep all three objects, or set enabled explicitly on each affected object to decide for it alone

Each of the three objects can also be enabled on its own by setting its enabled property explicitly, which takes precedence over the switch. Note that they are only connected as a triplet when all three are rendered: enabling only hull.objects.serviceaccount.default renders the ServiceAccount without the default Role and RoleBinding. Whenever the default ServiceAccount is rendered, pods without an explicit serviceAccountName are assigned to it automatically, as before. Set the new hull.config.general.assignDefaultServiceAccountToPods switch to false to opt out of this assignment while still rendering the ServiceAccount.

Note that the hull.config.general.rbac switch is unchanged, it still controls whether any Role, RoleBinding, ClusterRole and ClusterRoleBinding objects are rendered at all. With createDefaultRbacTriplet: true and rbac: false only the default ServiceAccount is created.

Introduction

One major design aspect of Helm is that it forces the user to create individual abstractions of the Kubernetes configuration of applications. For each individual Helm Chart that is realized in form of YAML templates in a Helm charts /templates folder. These template files, containing boilerplate Kubernetes YAML code blocks on the one hand and custom configuration mappings utilizing Go Templating expressions on the other hand, provide the glue between the configuration of the application via the central values.yaml configuration file and the desired Kubernetes YAML output. Arguably this approach of per-application abstraction is suited well to create tailormade configuration packages for even the most specialized applications but comes at a cost of having a large overhead for simpler, recurring and off-the-shelf application packaging use cases. Creating, maintaining and (often) understanding the abstractions introduced by Helm Charts - especially when facing a high number of individual Helm charts from various sources - can become tedious and challenging.

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 (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. 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 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.37). 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 and Helm Version Support Policy for Helm 3 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.

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 Helm chart concept and for testing

.

Quick Start - the hull-demo chart

Before diving into the details of HULL, here is a first glimpse at how it works. You can simply download the latest version of the hull-demo Helm chart from the Releases section of this page, it has everything bootstrapped for testing out HULL or setting up a new Helm Chart based on HULL with minimal effort.

The hull-demo chart wraps a fictional application myapp with a frontend and backend deployment and service pair. There is a config file for the server configuration that is mounted to the backend pods. The frontend pods need to know about the backend service address via environment variables. Moreover, the setup should by default be easily switchable from a debug setup (using a NodePort for accessing the frontend) to a production-like setup (using a ClusterIP service and an ingress).

A bare default structure to capture these aspects may look like this (with added line comments for explanation):

hull: # HULL is configured via subchart key 'hull'
  config: # chart setup takes place here for everything besides object definitions
    specific: # central place for shared values specific to this chart
      deb