Question: Calling Hull replacement from regular helm yaml

[stephenpope]

Hi .. first of all Hull has been fantastic and a massive time-saver for the whole of my development process on my current (very large) project and it has done everything I've asked of it so I suppose I am getting to a more edge-case scenario so any advice would be welcome :)

In basic terms I want to ask: how to call a hull template/function to trigger _HT*global.versions.thing from a normal helm template not created by Hull.

For context, i have a helm chart based on Hull .. all resources are created as Hull objects except for an ArgoRollouts CRD but it is in the same chart.

I am moving to a more centralised version management approach, as they share the same version I share the version between the services like:

values.yaml

  hull:
    config:
      specific:
        services:
          thingApi:
            image:
              tag: &appVersion "_HT*global.versions.thing"
          thingManagementApi:
            image:
              tag: *appVersion
          thingService:
            image:
              tag: *appVersion

.. in the ArgoRollout CRD I use ..

{{ .Values.hull.config.specific.services.thingService.image.tag }}

This worked fine when i specified the version but now (obviously) I get an error as the _HT*global.versions.thing is not parsed/understood by the normal helm yaml file.

Is it possible to call a Hull template/function to trigger the replacement from this CRD yaml ?

[gre9ory]

Hi @stephenpope,

first of all Hull has been fantastic and a massive time-saver for the whole of my development process on my current (very large) project and it has done everything I've asked of it so I suppose I am getting to a more edge-case scenario so any advice would be welcome :)

Thank you so much for the kind words, it is an appreciated recognition for the work that goes into it.

Given that it is inserted into a rather closed off processing pipeline (between reading values.yaml and rendering YAMLs) and written in a language that is not made for any larger scale programming, I do think HULL works remarkably well and can extend the scope and usability of Helm significantly. Hopefully significantly enough so that some people don't have to change to other ecosystems because they are frustrated with the way Helm itself is designed. Contrary to what some people complain about, the problem is not with YAML as a language in my opinion but with painful need to rebuild everything over and over again ... but enough about that, I assume you know what I am talking about :)

In basic terms I want to ask: how to call a hull template/function to trigger _HT*global.versions.thing from a normal helm template not created by Hull.

Had written a lot of text already but scratched it due to my findings below. I think I need to know your use case a bit better to proceed with options. So first a couple of questions:

1. Are CRDs with variable content allowed? I thought CRDs are static objects without dynamic values but maybe I am wrong. Would be good to know a little about your use case and why you need to put variables into CRDs.

2. How do you put the CRD into the chart? Do you store them as an additional template in the /templates folder or do you use the Helm /crds mechanism? If you have it in as a /template template and have control over it there may be more options available.

3. Which HULL version are you currently using?

Thanks!

---

Sidenote:

I did a little test and put an example CRD fragment in the templates folder with this content (see last line):

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  annotations:
    api-approved.kubernetes.io: https://github.com/kubernetes-sigs/gateway-api/pull/3328
    gateway.networking.k8s.io/bundle-version: v1.3.0
    gateway.networking.k8s.io/channel: experimental
  creationTimestamp: null
  name: referencegrants.gateway.networking.k8s.io
spec:
  group: gateway.networking.k8s.io
  names:
    categories:
    - gateway-api
    kind: ReferenceGrant
    listKind: ReferenceGrantList
    plural: referencegrants
    shortNames:
    - refgrant
    singular: referencegrant
  scope: Namespaced
  versions:
  - additionalPrinterColumns:
    - jsonPath: .metadata.creationTimestamp
      name: Age
      type: date
    name: v1beta1
    schema:
      openAPIV3Schema:
        description: |-
          ReferenceGrant identifies kinds of resources in other namespaces that are
          trusted to reference the specified kinds of resources in the same namespace
          as the policy.

          Each ReferenceGrant can be used to represent a unique trust relationship.
          Additional Reference Grants can be used to add to the set of trusted
          sources of inbound references for the namespace they are defined within.

          All cross-namespace references in Gateway API (with the exception of cross-namespace
          Gateway-route attachment) require a ReferenceGrant.

          ReferenceGrant is a form of runtime verification allowing users to assert
          which cross-namespace object references are permitted. Implementations that
          support ReferenceGrant MUST NOT permit cross-namespace references which have
          no grant, and MUST respond to the removal of a grant by revoking the access
          that the grant allowed.
        properties:
          apiVersion:
            description: |-
              APIVersion defines the versioned schema of this representation of an object.
              Servers should convert recognized schemas to the latest internal value, and
              may reject unrecognized values.
              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
            type: string
            default: {{ .Values.hull.config.specific.the_value_target }}

With the values.yaml containing this structure:

hull:
  config:
    specific:
      the_version_source: 1.2.3.4.5
      the_value_target: _HT*hull.config.specific.the_version_source

it rendered this (a bit to my own surprise ...):

---
# Source: hull-test/templates/example.yaml
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  annotations:
    api-approved.kubernetes.io: https://github.com/kubernetes-sigs/gateway-api/pull/3328
    gateway.networking.k8s.io/bundle-version: v1.3.0
    gateway.networking.k8s.io/channel: experimental
  creationTimestamp: null
  name: referencegrants.gateway.networking.k8s.io
spec:
  group: gateway.networking.k8s.io
  names:
    categories:
    - gateway-api
    kind: ReferenceGrant
    listKind: ReferenceGrantList
    plural: referencegrants
    shortNames:
    - refgrant
    singular: referencegrant
  scope: Namespaced
  versions:
  - additionalPrinterColumns:
    - jsonPath: .metadata.creationTimestamp
      name: Age
      type: date
    name: v1beta1
    schema:
      openAPIV3Schema:
        description: |-
          ReferenceGrant identifies kinds of resources in other namespaces that are
          trusted to reference the specified kinds of resources in the same namespace
          as the policy.

          Each ReferenceGrant can be used to represent a unique trust relationship.
          Additional Reference Grants can be used to add to the set of trusted
          sources of inbound references for the namespace they are defined within.

          All cross-namespace references in Gateway API (with the exception of cross-namespace
          Gateway-route attachment) require a ReferenceGrant.

          ReferenceGrant is a form of runtime verification allowing users to assert
          which cross-namespace object references are permitted. Implementations that
          support ReferenceGrant MUST NOT permit cross-namespace references which have
          no grant, and MUST respond to the removal of a grant by revoking the access
          that the grant allowed.
        properties:
          apiVersion:
            description: |-
              APIVersion defines the versioned schema of this representation of an object.
              Servers should convert recognized schemas to the latest internal value, and
              may reject unrecognized values.
              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
            type: string
            default: 1.2.3.4.5

which seems to contradict your finding somewhat. But there may be differences to your use case hence the questions first.

Honestly I have to admit I am a bit surprise that worked ... I wouldn't have thought that this HULL Get reference would get resolved under the hood before that custom template got resolved but my tests showed it did.

[stephenpope]

Hey @gre9ory .. sorry for the delay, had to wait until i could get round to getting a clearer repro for you :) Thanks so much for taking the time to lay it out.

1. I think when I said CRD i just meant a non-kubernetes custom resource, I am using Argo Rollouts (i'll show an example below)
2. Verison is 1.31.5
3. Helm version: 3.18.2

Apprecaite you taking the time to help.

Here is the full example:

Structure looks like this :

./Chart.yaml

apiVersion: v2
appVersion: 0.1.0
description: MyApp
name: app
type: application
version: 0.1.0
dependencies:
  - name: hull
    repository: https://vidispine.github.io/hull
    version: 1.31.x

./templates/hull.yaml

{{- include "hull.objects.prepare.all" (dict "HULL_ROOT_KEY" "hull" "ROOT_CONTEXT" $) }}

./versions.yaml

The idea of this file is that it is added at deploy time - so not part of the chart - I could of course use conditional access and use .Values.global.versions.thing in the rollout file - but i was more curious why using it via _HT didnt work.

global:
  versions:
    thing: 1.5.3

./templates/rollouts/app-rollout.yaml

apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
  name: app-rollout
spec:
  revisionHistoryLimit: 2
  selector:
    matchLabels:
      app: app-rollout
template:
    metadata:
      labels:
        app: app-rollout
    spec:
          image: {{ .Values.hull.config.specific.services.appRollout.image.repository }}:{{ .Values.hull.config.specific.services.appRollout.image.tag }}
          name: app-rollout

./values.yaml

#file: noinspection SpellCheckingInspection
hull:
  config:
    general:
      rbac: false
      noObjectNamePrefixes: true
    specific:
      services:
        appRollout:
          name: app-rollout
          image:
            tag: _HT*global.versions.thing
            repository: app-rollout

  objects:
    serviceaccount:
      default:
        enabled: false
    deployment:
      app-with-hull:
        pod:
          containers:
            app-api:
              image:
                repository: _HT*hull.config.specific.services.appRollout.image.repository
                tag: _HT*hull.config.specific.services.appRollout.image.tag

Executing with

helm template --output-dir out . --values versions.yaml

This produces: out/app/templates/rollouts/app-rollout.yaml

#SNIP
template:
    metadata:
      labels:
        app: app-rollout
    spec:
          image: app-rollout:_HT*global.versions.thing
          name: app-rollout
#SNIP

In hull.yaml the deployment values are replaced correctly

#SNIP
    spec:
      containers:
      - image: app-rollout:1.5.3
        name: app-api
#SNIP

If you need any more info let me know.

[gre9ory]

Hello @stephenpope,

thank you for the files and additional information, it was easy to do a full repro of your problem with that. Compared to my working example above I was confused as to why mine is working and yours isn't - even though the preconditions seem to be identical. So I did some testing around and found the differences in the structure of the templates folder (filenames and subfolders). There is some sequence of how template files and subfolders are read by Helm and the placement of the hull.yaml matters here because after processing of the hull.yaml, the in-memory .Values are modified - so files being read after hull.yaml are subject to the changes HULL made and the ones read before are not.

Based on that observation I conducted quite a lot of tests to learn more about Helm inner workings and concluded the following:
alphanumerical filenames and folders matter. It looks as if Hem reads files and folders in the templates folder in reverse alphanumerical fashion and subfolders seem to be processed before files.

The general question whether subfolders in templates folder are legit or not is touched upon here on this SO issue where one person claims it works for files in a library chart (ergo functions) so I'd consider this a different scenario. Helm doc states "All template files are stored in a chart's templates/ folder" so that may be the most official word on not strongly supporting subfolders.

On a general note, combining "standard" Helm template files with HULL logic wasn't really a proclaimed goal of HULL. But it is also definitively not a non-goal so if it helps people achieve their goals I'd like to support it as good as I can. Extending the reach of HULL into external subcharts and templates would be maybe the last big topic to explore and I am happy when people like you try out things like that, At the moment it is a bit experimantal as you have also stated.

---

To conclude, you should be able to do this. I suggest to create a subfolder like zzz in your templates folder and put the hull.yaml in there. In my tests I could render all template files correctly:

This way it should be safe to have one level of subfolders. If you want to leave out the subfolders completely you should rename hull.yaml to zzz-hull.yaml for example to make sure it is alphanumerically last and processed first.

---

Thanks again for bringing this interesting issue up, will document this extended use case for the next release .

Have a good day!

[stephenpope]

Amazing. I had a thought it seemed to be an order-of-operation thing but thank you for digging into the guts of Helm!

Again, Hull is such a great and useful tool for our project and saved us so much time and complexity for when we have simple services that just need a deployment and an ingress but also can do some way more complex things as the project went on.

You can close this as solved :)

[gre9ory]

Small addendum:

Don't know anything about Helm's source code but I thought I'd have a look out of interest. I think I found the line where it reads in the templates:

https://github.com/helm/helm/blob/3ebad60d3c6d72a3d61d700e8616b6557a540bee/pkg/engine/engine.go#L431

Also don't know any Go really but seems to be some reverse sorting going on and it utilizes some lookup function that considers / directory seperator ....

So I think this confirms the assumption that the best bet is to have the hull.yaml in a zzz...something folder with same or highest level of folder nesting to read it in first and make the rest work.