Helm packages a Kubernetes application into a chart: a directory of templated manifests plus a set of default values. This guide covers the folder structure every chart shares and the three concepts, chart, values, and release, that everything else in Helm builds on.

Why not just write plain manifests

A non-trivial application is rarely one Deployment. It’s a Deployment, a Service, a ConfigMap, maybe a Secret and an Ingress, and you want the same set deployed to dev, staging, and production with only a handful of values different between them: an image tag, a replica count, a namespace. Copy-pasting manifests per environment means every shared field can drift out of sync. A chart holds the manifests once, as templates, and lets each installation supply its own values.

The folder structure

helm create webapp

This scaffolds:

webapp/
├── Chart.yaml           # chart metadata: name, version, description
├── values.yaml          # default configuration values
├── charts/              # any charts this one depends on
├── .helmignore
└── templates/
    ├── deployment.yaml
    ├── service.yaml
    ├── _helpers.tpl      # reusable template snippets
    ├── NOTES.txt         # printed after install/upgrade
    └── tests/
        └── test-connection.yaml

Chart.yaml is metadata about the chart itself, mostly its name, version, and apiVersion (v2 for Helm 3 and current Helm 4). values.yaml holds the default configuration. templates/ holds Kubernetes manifests with Helm’s templating syntax mixed in. charts/ holds any charts this one depends on, which only comes up once you’re composing charts together. The generated example is a working nginx chart with more than you usually need; most teams either delete the scaffold and write their own three or four templates, or trim what doesn’t apply.

Values flow into templates

A template looks like a normal manifest with placeholders:

# templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Values.appName }}
spec:
  replicas: {{ .Values.replicaCount }}
  template:
    spec:
      containers:
        - name: {{ .Values.appName }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"

# values.yaml
appName: webapp
replicaCount: 2
image:
  repository: nginx
  tag: "1.25"

.Values is an object built from values.yaml, merged with anything supplied on the command line. Running helm install or helm template renders every file under templates/ with that object, producing plain Kubernetes YAML. The {{ }} syntax is Go templates, the same templating language used elsewhere in the Kubernetes ecosystem, so nothing proprietary to learn beyond it. Values can be overridden three ways, in increasing precedence: values.yaml’s defaults, an additional file passed with -f, and individual --set key=value flags on the command line.

A release is a specific deployment of a chart

Rendering a chart and applying the result to a cluster creates a release: a named, tracked installation with its own history.

helm install web-dev ./webapp
helm list

web-dev is the release name. You can install the same chart multiple times under different release names, in the same namespace or different ones, for example web-dev and web-staging. Every helm upgrade against a release adds a new revision to its history, which is exactly what makes helm rollback possible later: Helm isn’t just applying YAML, it’s tracking what was applied and when. The release-management guide in this series covers that workflow in full.

What NOTES.txt is for

templates/NOTES.txt is plain text, itself templated the same way, that Helm prints after install or upgrade. Use it to tell whoever installed the chart what to do next: a kubectl port-forward command, the URL a Service will be reachable at, or a first-run step. It has no effect on the cluster; it’s purely a message to the person running the command.

Where charts come from

You don’t have to write every chart yourself. Public charts for common software, databases, monitoring stacks, ingress controllers, are published on Artifact Hub and installable in one command. The rest of this series covers writing your own chart first, then finding and installing published ones.