helm: v3: helm template does not render NOTES.txt

Unfortunately this requires an actual cluster, unlike helm template.

Bump. It would be useful to test this in template command by passing a --notes flag. For CI testig purposes.

This issue has been marked as stale because it has been open for 90 days with no activity. This thread will be automatically closed in 30 days if no further activity occurs.

+1 on this one. We have no way to test the code generated by NOTES.txt without a cluster connected (because install|upgrade requires a cluster, even if --dry-run and --debug are set)

For me this issue is still open

/reopen please

It is a relevant feature, but I think there is a need to help out drive development about it.

Current behavior of --render-subchart-notes

Its relevant to overview the current behavior if we consider changing it. I conclude that --render-subchart-notes is silently ignored when used in the helm template, but for helm install it is functioning correctly and as documented.

The documentation says if set, render subchart notes along with the parent, so practically, the documentation is also currently only valid for the helm install situation as the along with the parent part isn’t true anyhow for when used with helm template.

Steps to create a dummy chart for debugging

# create helm chart "a" with nested charts
# a has subchart b and c
# b has subchart d
cd /tmp
helm create a && echo "a FINDME" > a/templates/NOTES.txt
cd a/charts
helm create b && echo "b FINDME" > b/templates/NOTES.txt
helm create c && echo "c FINDME" > c/templates/NOTES.txt
cd b/charts
helm create d && echo "d FINDME" > d/templates/NOTES.txt
cd ../../..

Reproduction of broken helm template --render-subchart-notes .

Nothing is rendered when --render-subchart-notes is used with helm template.

# check for any NOTES.txt being rendered
helm template --render-subchart-notes . | grep FINDME

Output from helm install --dry-run --render-subchart-notes test .

Note that the ordering of these, the ordering seems random.

<CHART A TEMPLATES>
NOTES:
<NOTES FROM CHART B>
<NOTES FROM CHART A>
<NOTES FROM CHART D>
<NOTES FROM CHART C>

What UX makes sense?

In https://github.com/helm/helm/issues/6901#issuecomment-553010477 @bacongobbler asked for input on what UX to go for.

My short-term UX suggestion

• Add --render-notes flag for helm template and helm install alongside --render-subchart-notes to toggle if the root chart’s notes should be rendered. Let --render-notes be false by default for helm template, but true by default for helm install, to match current behavior.
• Update the help text for --render-subchart-notes note about its mention of along with the parent, something that should be controlled by render-notes now.
• For now, stick with current behavior from helm install with how notes are to be rendered for helm template. The current behavior is to render notes after all other templates has been rendered, with the separator line NOTES:. The notes are rendered one after the other in a random order without additional new-line spacing or titles.

My long-term UX suggestion

I think we should go for the short-term suggestion above at first and not go straight to this, as this involves breaking changes etc.

When helm template is used, we can see the following separators between templates.

• I think we should treat NOTES.txt as any other rendered template with separators that include a mention of where they come from.

  ---
  # Source: a/templates/tests/test-connection.yaml
  

• I think NOTES.txt templates should be rendered last.
• I think NOTES.txt from the main chart and its subcharts should be ordered deterministically when rendered, so that if we have a structure like a,b,c,d above the ordering would be a>b>d>c where d comes before c because it is a dependency of b which evaluates in full before c.

Now what?

• Everyone: please provide feedback to the short-term UX proposal above.
• Maintainers: please help with yes/no decisions - is there a proposal available that you encourage work towards at this point in time?
• Maintainers: please help with who-does-what decisions - do you wish for someone in the community to work towards this, or do you wish to do it yourself?

This is a non-breaking proposal that addresses this issue.

Add --render-notes to helm [template|install]

• --render-notes determines if top level chart NOTES.txt is rendered.
• --render-subchart-notes determines if subchart NOTES.txt are rendered.
• For backward compatibility, --render-notes is by default made false for helm template and true for helm install.

we should treat NOTES.txt as any other rendered template

If you mean to do so by default, this could break tooling which expects the output of helm template to be (multidocument) YAML. Would be safer to render it as comments (prepending # to every line):

---
# Source: xxx/templates/service-account.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: xxx
  namespace: xxx
---
# Source: xxx/templates/NOTES.txt
# Here is how you use this chart:
# Run: la la la

which seems to be tolerated

$ helm template xxx | yq e -ojson | jq -s
[
  {
    "apiVersion": "v1",
    "kind": "ServiceAccount",
    "metadata": {
      "name": "xxx",
      "namespace": "xxx"
    }
  },
  null
]

The trick proposed to render the NOTES.txt is not working using helm 3.5.4 with a local helm charts

Current folder ~/myproject/helm/rbac

ls -la templates   
total 56
drwxr-xr-x  9 cmoullia  staff   288 Apr 30 11:41 .
drwxr-xr-x  9 cmoullia  staff   288 Apr 30 11:42 ..
-rw-r--r--  1 cmoullia  staff   196 Apr 30 11:35 NOTES.txt
-rw-r--r--  1 cmoullia  staff  1752 Apr 30 10:45 _helpers.tpl
-rw-r--r--  1 cmoullia  staff   859 Apr 30 11:17 cluster-role-binding.yaml
...

helm template rbac ./ -s templates/NOTES.txt
Error: could not find template templates/NOTES.txt in chart

/reopen /cc @mattfarina

As a temporary workaround, you can run the following command :

helm install chart --dry-run  --generate-name

This will render the NOTES.txt file.

I’m keeping my fingers crossed for 3.0 fix 😃

Can we punt on subcharts and even the --notes option and just make

helm template $chart -s templates/NOTES.txt

render that file, so you can test or iteratively develop complex substitutions in it without needing a live cluster?

helm install chart --dry-run  --generate-name

Unfortunately this requires an actual cluster, unlike helm template.