skip to content

How does a chart's templates/NOTES.txt reach the user, and how do you read it later?

level: middleimportance: nice to knowfreq 32%

answer

  1. Rendered, but never applied
  2. The operator reads it, not the cluster
  3. It survives the terminal scrolling away
  4. Kept per revision with the release
  5. helm get notes, with --revision

basics

~20 s

templates/NOTES.txt is rendered like any other template, but its output is printed to the operator after install or upgrade instead of being applied to the cluster. Helm stores it with the release, so helm get notes returns it later.

solid answer

~50 s

`NOTES.txt` lives under `templates/` and is rendered with the same context as every other file there — `.Values`, `.Release`, `.Chart` are all available — but its result is text for a human, not a manifest. Helm prints it at the end of `helm install` and `helm upgrade`, and stores the rendered string in the release record, so `helm get notes pdfsign` returns it afterwards and `helm status pdfsign` includes it. Because the notes are stored per revision, `helm get notes pdfsign --revision 31` shows what a specific revision printed — useful when a release has 34 revisions and you want to know what the operator was told two upgrades ago. `helm install --dry-run=client` renders it without installing. The corollary matters: never render a generated password into the notes, because anyone who can read the release can read them.

code

text · 13 lines
text
PDF signing service {{ .Chart.AppVersion }} is installed as {{ .Release.Name }}.

Reach it from inside the cluster:
  http://{{ include "pdfsign.fullname" . }}.{{ .Release.Namespace }}.svc:{{ .Values.service.port }}

{{- if .Values.postgresql.enabled }}
A bundled database was installed with this release.
{{- else }}
Supply your own database via pdfsign.database.url.
{{- end }}

Read the API token when you need it:
  kubectl -n {{ .Release.Namespace }} get secret {{ include "pdfsign.fullname" . }} -o jsonpath='{.data.token}' | base64 -d

go deeper

for a junior

Recall that this file holds the message printed after an install or upgrade, that it is a template rather than fixed text, and that Helm can show it again for an existing release.

for a middle

Explain the mechanics: same rendering context as any template, output stored with the release rather than sent to Kubernetes, retrievable per revision, and rendered by a client-side dry run for iteration.

for a senior

Demonstrate the judgement: notes are durable and readable by anyone who can read the release, so they carry retrieval commands rather than secrets, and a template error in them fails the whole release.

for a principal

Own the convention across many charts: what the notes are for versus the README, how long they may be, and what changes when delivery is automated and no operator is watching the output.

### The one file under templates/ that is not a manifest Everything Helm renders from `templates/` is normally sent to Kubernetes. There are two exceptions. Files whose names begin with an underscore, such as `_helpers.tpl`, define partials and produce no output of their own. And `NOTES.txt` is rendered, but its output is a message for the person running the command rather than an object for the cluster. It is a full template. `.Values`, `.Release.Name`, `.Release.Namespace`, `.Release.Revision`, `.Chart.Name`, `.Chart.AppVersion` and any named template the chart defines are all reachable, and the usual conditionals work, so a chart can print different instructions depending on how it was configured. `helm create` scaffolds one that branches on which service type was chosen and prints the matching way to reach the application. ### Where the output goes Three places, and knowing all three is the point of the question: 1. **Standard output**, at the end of a successful `helm install` or `helm upgrade`. This is the copy most people see, and the reason it is written at all. 2. **The release record.** Helm stores the rendered notes alongside the manifest and the values for that revision. That is what makes them retrievable rather than a one-time console message. 3. **Retrieval commands.** `helm get notes <release>` prints them, and `helm status <release>` includes them in its output. Both accept `--revision`, so on a release with 34 revisions you can ask what revision 31 told the operator without reinstalling anything. `helm install --dry-run=client` renders and shows the notes without touching a cluster, which is how you iterate on the text. ### What it is good for The useful notes answer "what do I do now?" for the specific installation that just happened, using values only Helm knows: the actual service name, the namespace, the port the chart chose, the command that fetches the generated admin URL. For a PDF-signing service whose chart can optionally bundle a database subchart, the notes are the natural place to say which mode this release ended up in and what the operator must supply themselves in the other mode. The unhelpful notes are the ones that restate the chart's README, or print a wall of ASCII art, or give instructions that were true for the author's cluster only. Notes are printed on every upgrade — a long block that nobody reads is worse than no block at all. ### The trap: notes are stored, not ephemeral Because the rendered text is kept with the release, anything the chart prints there is retrievable by anyone who can read the release. A chart that generates a password and helpfully prints it in the notes has written that password into the release record in addition to wherever the manifest put it. The safe pattern is to print the *command* that retrieves the value at need, not the value itself. This is a real review point on shared charts and a good way to distinguish a candidate who has authored charts from one who has only installed them. A second, milder trap: notes are rendered with the same strictness as any other template. A reference to a value that does not exist will render as an empty string or fail depending on how it is written, and a template error in `NOTES.txt` fails the whole render, exactly like an error in a manifest. It is easy to forget because the file does not look like code. ### Rendering, and what does not include it Because the notes are not a manifest, tools that consume the *rendered manifest* of a chart do not consume them. If your pipeline renders a chart and applies the YAML through some other path, the notes are simply not part of that stream; nothing is broken, but nobody is going to read them either. That is worth knowing when a team's charts are delivered by a controller rather than by a person at a terminal: the notes stop being a delivery mechanism for instructions and become documentation that only shows up if someone asks for it. In that world the same content belongs in the chart's README or in the platform's own docs, and the notes stay short. ### A reasonable house style Keep it under a screen. Lead with how to reach the thing. Use `.Release.Name` and `.Release.Namespace` rather than hard-coded names, so a second release of the same chart prints correct instructions. Print retrieval commands, never secrets. And render it in CI with a couple of representative value sets so a template error in the notes is caught before the first user hits it.

  • Why is printing a generated password in NOTES.txt a bad idea?
    The rendered notes are stored with the release, so the password is retrievable by anyone who can read that release, and it stays in the history for every revision that printed it. Print the command that fetches the value instead. The same reasoning applies to anything else sensitive the chart computes: the notes are a durable record, not a transient message.
  • What happens if NOTES.txt contains a template error?
    It fails the render exactly like an error in a manifest template — the install or upgrade does not proceed. The file is easy to forget because it looks like prose, so a value reference that is fine in the author's configuration and missing in someone else's breaks the whole chart. Render it in CI against a few representative value sets.
  • Do the notes appear when a chart is delivered by an automated controller rather than a person?
    They are still rendered and stored with the release, but nobody is watching a terminal, so they stop being an effective way to hand instructions to an operator. In that setup keep the notes short and put the real documentation where people actually look — the chart's README or the platform docs — while leaving the notes useful for anyone who later runs a status or notes command.

saying these in an interview costs you the question

  • Thinks NOTES.txt is applied to the cluster as a resource
  • Says the notes are printed once and then lost
  • Believes it is plain text and not a rendered template
  • Prints generated credentials in the notes
  • Assumes a template error there is harmless
  • Cannot name a command that retrieves the notes later

context

resolving links…