Helm

NOTES.txt File, Post-Install Upgrade Instructions for Helm Chart Users

Documentation is an essential part of any software development project. The importance of documentation cannot be overstated, as it serves as a guide for developers, users, and stakeholders throughout the software development process. In Helm charts, application information is stored in the NOTES.txt file.

In this blog, we will look at what a NOTES.txt file is and how to create it.

What is a NOTES.txt File?

Some Helm charts can get pretty complex, such as installing and interconnecting many objects in your Kubernetes cluster. As such, it can be pretty confusing for users how they should continue after installing a chart. 

For instance, a user may ask, “How do I connect to this Kubernetes package/app? How do I manage it? What are the username and password? What do I need to do during an upgrade?” All such questions can be answered immediately after a chart is installed or upgraded by displaying helpful information to the user. This can be done by adding a special file named NOTES.txt to the chart’s templates/ directory.

The NOTES.txt file is rendered just like Helm's regular template file. The only difference is that after it’s rendered, it’s not sent out to Kubernetes; rather, the content is displayed in the command line window/terminal for the user to see. Since it’s treated as a regular template, it means we can use the same techniques and tricks we used up until now. 

For instance, we can fetch values from the charts and release names, add conditional blocks, use flow control, functions, pipelines, etc. But, as usual, theory can sound a bit mysterious, so let’s see this in practice.

Learn more about Helm charts from this blog: Writing a Helm Chart: A Comprehensive Guide for Beginners.

Creating a NOTES.txt File

Let’s create the NOTES.txt file using your favorite text editor, and we can add instructions on how users can connect to the Nginx web server after installing this chart. Paste this content into your NOTES.txt file.

Please wait a few seconds until the {{ .Chart.Name }} chart is fully installed.

After installation is complete, you can access your website by running this command:

kubectl get --namespace {{ .Release.Namespace }} service {{ .Release.Name }}-nginx

and then entering the IP address you get, into your web browser's address bar.

Now, when we install this chart using the command helm install test ./nginx we’ll see this output:

user@debian:~$ helm install test ./nginx
NAME: test
LAST DEPLOYED: Sat Jun 12 00:17:11 2021
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
Please wait a few seconds until the nginx chart is fully installed.

After installation is complete, you can access your website by running this command:

kubectl get --namespace default service test-nginx

and then entering the IP address you get, into your web browser's address bar.

Great! Now, our chart users have all the info they need.

Enroll in our Helm for the Absolute Beginners course to learn more Helm concepts.

Helm for Beginners | KodeKloud
Learn and get certified with simple and easy hands-on labs
KodeKloud logo

Conclusion

When you package your Helm chart, the contents of the NOTES.txt file will be included in the chart's README file. This makes it easy for users to access important information about the chart without having to dig through the chart's files. Overall, the NOTES.txt file is a simple but useful tool for providing documentation and improving the usability of your Helm chart.

More on Helm:

Mumshad Mannambeth

• 3 min read