About 10 years ago, I used SaltStack extensively and wrote my top 10 best practices for SaltStack formulas. Today, I do the same for the Helm chart, having led the development of the Camunda Self-Managed Helm chart over the last 3 years, which has polished both my Helm technical skills and product mindset.
This post is about the development (not operations) of an upstream chart used by other companies (customers), not just internally. So, some points here could be too much if you use the Helm chart within your company, but they are essential when the chart is used by 3rd parties, you don't have a direct contact with them. Yet, it's useful to be aware of these practices, and also for Platform Engineering, where the chart is consumed by multiple internal teams.
Let's go 👾
This post is mainly based on my experience with Helm 3. But it should work with Helm 4, since most of what's written focuses on general software engineering practices.
ToC
- 1. Product Mindset
- 2. Mastering Essentials
- 3. Chart Architecture and Design
- 4. Security and Compliance
- 5. Templating
- 6. Testing and Validation
- 7. Documentation and Annotation
- 8. Packaging and Distribution
- 9. Misc
- 10. Get ready for Helm 4
1. Product Mindset
To be honest, before diving into any technical details, there is a critical aspect I'd like to emphasize ... product mindset! When your chart is upstream, you need to work with Helm chart development as any other software product, not just a helper tool.
This affects a lot of your decisions and actions. You should think about your actions as a product manager, not just an engineer. If you have never had product management training or courses, I highly recommend starting.
2. Mastering Essentials
- Start with basics: Look at the default chart created by the helm create command and learn about what's considered the defaults.
- Extend the basics: Ensure to read the docs sepcially the essencial pages like "Named Templates", "Built-in Objects", and "Template Function List". They have a lot of useful information, and I keep getting back to them all the time, especially the function list.
- Read the project best practices: It's a good idea to read the The Chart Best Practices Guide by the Helm project, as this post extends that guide with more details.
3. Chart Architecture and Design
- Don't use sub-charts: The Helm sub-charts are really limited and serve narrow use case. The biggest issue with it is that, by design, each sub-chart cannot access the other sub-charts' data! You will run into many issues if your chart has more than one component/application.
- Use Helm chart libraries: No need to reinvent the wheel. Hello, there are many Helm charts that are used solely as libraries, with common, reusable tasks across charts. The most famous one is the Bitnami Common chart.
- Use proper nesting: Keep the values file shallow but not too shallow! Don't put everything at one level; well-structured chart parameters improve readability. Finally, if you are adding a new key, using a map makes it easier to extend later than a single value or an array (remember, Helm doesn't merge arrays by default, so an extra values file will override the whole array in the default values file).
- Use flat repository: If you need to handle multiple versions of the chart at the same time (e.g., due to SLA or support agreement), it's way much better to use a flat structure instead of using branches. Putting all versions in the main branch makes life much easier, especially for CI/CD changes. It was a nightmare to work with each version in its own branch.
4. Security and Compliance
- Enable security by default: Nowadays, you should think about security as a normal flow, not as an extra action. Follow all security practices when creating Kubernetes manifests. For example, use a read-only filesystem, drop capabilities, and run as a non-root user by default.
- Sign and verify chart: Another critical security aspect is integrity. Use Cosign to sign your chart daily and throughout the entire SDLC. The Cosign keyless sign made it super easy to apply this security practice.
5. Templating
- Use _helpers.tpl as a central boilerplate: Keep the manifests clean and utilize _helpers.tpl as a one-stop shop for processed data (you can split it into smaller files if needed).
- Use environment variables from ConfigMap: Don't hummer your manifests by setting the environment variables inside the Pod definitions; instead, use envFrom to load them from a ConfigMap.
- Include external files in ConfigMaps: Don't embed the content in ConfigMaps directly, but include them externally, which makes linting and syntax highlighting much better! Remember, the file name should start with underscore _ so Helm doesn't render it directly.
# templates/foo/configmap.yaml apiVersion: v1 kind: ConfigMap [...] data: application.yaml: | {{- (include (print $.Template.BasePath "/foo/files/_application.yaml") $) | indent 4 }} - Auto-reload Pods on ConfigMap/Secret change: Use hash functions in the Pods annotations to auto-reload the Pods once the ConfigMap/Secret changes. This guarantees that the Deployment will automatically pick up the new configuration.
# templates/foo/deployment.yaml apiVersion: apps/v1 kind: Deployment [...] spec: template: metadata: annotations: checksum/config: {{ include (print $.Template.BasePath "/foo/configmap.yaml") . | sha256sum }} - Use named templates with parameters: In most of the charts, you will find the named templates have one input. However, you can define multiple parameters for the named templates, which gives you great flexibility close to real programming languages' functions.
{{/* Create a default fully qualified app name for the component. Example: {{ include "renderComponentData" (dict "componentName" "foo" "componentValues" .Values.foo "context" $) }} */}} {{- define "renderComponentData" -}} {{- ## .context.Release.Name ## -}} {{- .componentName -}}: {{- .componentValues -}} {{- end -}} - Use tpl (wisely): Using the tpl function helps you to reference dynamic values and reduce redundancy. So you can easily cross-reference within your values.yaml file. However, don't use it for big data, as it could increase the complexity of your chart.
# values.yaml hostname: "{{ .Release.Name }}.example.com"{{ tpl (toYaml .Values.hostname) $ }} - Use safe nullable nested values: One of my favorite tricks all the time. If you don't know if the key exists or not, use this syntax to handle nullable nested values and fallback gracefully without throwing rendering errors.
# This will not fail if foo, bar, or baz are not defined. {{ $bazValue := (((.Values.foo).bar).baz) }} - Allow users to include raw manifests: By fact, Helm is a templating engine, and you cannot support all use cases. Hence, allow users to include additional manifests to easily extend the chart.
# values.yaml extraManifests: - | apiVersion: v1 kind: ConfigMap metadata: name: foo data: foo.json: '{"data": "value"}' - Fail fast: Use the constraints file to enforce requirements or mutually exclusive rules to prevent a defective deployment.
# constraints.tpl {{- if (.Values.name) }} {{- $errorMessage := printf "[foo][deprecation] %s %s" "The parameter \".name\" has been removed in favor of \".fullname\"." "For more details, please check the official documentation." -}} {{ printf "\n%s" $errorMessage | trimSuffix "\n"| fail }} {{- end }}
6. Testing and Validation
- Generate rendered snapshot: In your Git repo, store a rendered copy of the chart manifests that will make it easier to detect differences across changes. Those files are known as golden files.
- Test chart like code: Relying on the golden files only is not enough because it shows only the changes for the default values. So you need to test every value of the values file to ensure everything works as expected when the chart is applied. Think about it like a unit test in a programming language. For that, you can use a Golang library like Terratest, which has modules for helm and k8s.
- Enable schema validation: Another important safeguard is to define the schema of your values.yaml file. This will show an error to the users when they misspell the key name or value type. There are 2 ways to do that: the first is simple and limited, and involves setting the types in the file values.schema.yaml. Or directly auto-generate values.schema.json (which is basically an OpenAPI schema file) using a tool like bitnami/readme-generator-for-helm, which will save your time and ensure the schema is always up-to-date.
- Test chart packaged: For a long time (and till writing these words in 2026), Helm CLI behavior differs, due to many bugs, if the installation happens from a chart packaged (from the tgz file) or unpackaged (directly from the chart directory). As a rule of thumb, always test what the user will use, so always test against a packaged chart.
7. Documentation and Annotation
- Auto-generate docs: You can easily generate the readme file (or part of it) with all available chart parameters using bitnami/readme-generator-for-helm (the same tool used to generate the schema). It's super useful and helps keep your Helm chart docs up to date.
- Set chart metadata: Add any critical or useful information in the Chart.yaml file like keywords, maintainers, annotation, etc. An important annotation to add is the Helm CLI version used to test and package the chart (the Helm project is known for bugs and incompatibilities across minor versions). Also, add Artifact Hub annotations, which are important when you share the chart later.
8. Packaging and Distribution
- Decouple chart and app versioning: Usually, when you have an internal chart, it's easier to use the chart version the same as the application version. But when you have an upstream chart used by thousands of users, it's better to give the chart its own version, so you can fix issues without waiting for the next application release.
- Automate the release process: Use release-please to automate your chart release; it works pretty well with Helm, and it can make your life easier when you work with multiple charts at the same time.
- Promote artifacts, don't rebuild: Probably you know this as software best practice, but sometimes you think Helm doesn't need that. In reality, you should always do that for any artifact! With each build, there is a risk of change, so always promote that exact artifact across environments (Dev -> Staging -> Prod) rather than rebuilding it from source each time, to ensure you test the exact artifact that users will use.
- Package chart in OCI format: Historically, the chart artifact is a tar archive .tgz, but Helm supports OCI (Open Container Initiative) artifact where you can store it in a modern container registry. This should be the standard now.
- Publish to Artifact Hub: Adding your chart to Artifact Hub makes it easier to discover and use by the end-users. Even if your chart repository is public, end users should never use the chart directly from the repo, as it's primarily used for development. As mentioned above, there may be hidden bugs, or you may take extra steps when generating the chart, which the user will miss if they try to install from the Git repository directly.
9. Misc
- Use Helm hooks (wisly): Helm has hooks mechanism that allows you to run certain lifecycle tasks. For example, I used hooks to automatically generate initial credentials/secrets and store them in a K8S Secret object. You don't want that to be part of the chart to avoid accidentally deleting the secrets if the chart is uninstalled.
- Utilize Post-Rendering: In some cases, you could need to use the post-rendering feature to fix some of the issues out of your control (e.g., a bug in Helm CLI). You can also combine Helm and Kustomize; they are friends, not enemies. Use Helm to generate the base manifests and use Kustomize (via Helm's post-rendering features or wrapping Helm in a kustomization.yaml) for last-mile environment overlays.
- Maintain backward compatibility: Now your chart is used by many downstreams, always remember that you never break backward compatibility without a clear deprecation cycle. Always try to add the new feature, then remove the deprecated ones after a couple of releases.
10. Get ready for Helm 4
As mentioned at the beginning of this post, my experience is with Helm 3 (released on November 13, 2019), but most of what's written here should work with Helm 4, which was released a couple of months ago (released on November 12, 2025) ... that's exactly 6 years difference.
On the chart level, Helm 4 maintains backward compatibility, so it should work smoothly with the charts created by Helm 3. But at the operational level, there are a couple of changes that should be made, such as renaming the CLI flags, which will require review in the CI/CD pipelines.
The notable change of Helm 4 I really like is the new plugins system with three plugin types: CLI plugins, getter plugins, and post-renderer plugins, plus a system that enables new plugin types for customizing additional core functionality.
The migration to Helm v4 shouldn't be a big deal for most cases, but it should be done sooner or later.
That's it, it was a great journey... ⎈Happy Helming!⎈
