HULL: Helm Uniform Layer Library

Abstractions need to be maintained - Kelsey Hightower

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.35). 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
      debug: true # a switch influencing creation of objects in this chart
      application_version: v23.1 # a shared image tag for multiple container
      myapp: # some exemplary configuration settings for the app, exposed here for transparency
        rate_limit: 100
        max_connections: 5
  objects: # all objects to create are defined here
    deployment: # create deployments
      myapp-frontend: # the base part of the object name for frontend deployment
        pod: # configure pod-related aspects
          containers: # non-init containers
            main: # one main container
              image: # provide image reference
                repository: mycompany/myapp-frontend # repository
                tag: _HT*hull.config.specific.application_version # reference to central tag value above
              ports: # exposed ports
                http: # port name is http
                  containerPort: 80 # the port number
              env: # environment variables
                SERVER_HOSTNAME: # name of variable
                  value: _HT^myapp-backend # value is dynamically rendered reference to myapp-backend service name
                SERVER_PORT: # name of variable
                  value: "8080" # backend service port
      myapp-backend: # the base part of the object name for backend deployment
        pod: # configure pod-related aspects
          containers: # non-init containers
            main: # one main container
              image: # image reference
                repository: mycompany/myapp-backend # repository
                tag: _HT*hull.config.specific.application_version # reference to central tag value above
              ports: # exposed ports
                http: # port name is http
                  containerPort: 8080 # the port number
              volumeMounts: # mounts of the container
                appconfig: # context key is appconfig
                  name: myappconfig # the name needs to match a volume
                  mountPath: /etc/config/appconfig.json # mountPath
                  subPath: backend-appconfig.json # subPath
          volumes: # volumes that may be mounted
            myappconfig: # key matching a volumeMounts name
              configMap: # configmap reference
                name: myappconfig # the configmap to load, simply referenced by key name   
    configmap: # create configmaps
      myappconfig: # the backend configuration
        data: #