Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 38 ยท Charts and Releases

Chart Structure and Chart.yaml

Learn the files and folders of a Helm chart: Chart.yaml fields, values.yaml, templates, charts, crds, .helmignore and how version and appVersion differ.

A chart is just a directory with a fixed layout. Helm looks for specific names, so the structure is a convention you must follow exactly. Once you know it, every chart you download becomes readable. This lesson tours the layout and then goes deep on Chart.yaml, the chart's identity card.

The directory layout

TEXT
webapp/
โ”œโ”€โ”€ Chart.yaml          required: name, version and metadata
โ”œโ”€โ”€ values.yaml         default configuration values
โ”œโ”€โ”€ values.schema.json  optional: JSON Schema that validates values
โ”œโ”€โ”€ .helmignore         files to leave out of the packaged chart
โ”œโ”€โ”€ charts/             dependency charts (subcharts)
โ”œโ”€โ”€ crds/               CustomResourceDefinitions installed first
โ””โ”€โ”€ templates/
    โ”œโ”€โ”€ _helpers.tpl    named templates (files starting with _ render nothing)
    โ”œโ”€โ”€ deployment.yaml
    โ”œโ”€โ”€ service.yaml
    โ”œโ”€โ”€ ingress.yaml
    โ”œโ”€โ”€ NOTES.txt       message printed after install
    โ””โ”€โ”€ tests/
        โ””โ”€โ”€ test-connection.yaml

Only Chart.yaml and the templates/ directory are essential in practice (a chart without templates installs nothing, though it can still carry dependencies). Everything else is optional. The folder name should equal the chart name, because helm package and repositories use that name.

flowchart TB
  C["Chart.yaml: identity"] --> H((helm))
  V["values.yaml: defaults"] --> H
  T["templates/: YAML with placeholders"] --> H
  D["charts/: subcharts"] --> H
  H --> M["Rendered manifests"]

Helm reads these four inputs and produces manifests.

Chart.yaml in detail

A complete example:

YAML
apiVersion: v2
name: webapp
description: A small web application with an optional ingress
type: application
version: 0.3.1
appVersion: "2.8.0"
kubeVersion: ">=1.27.0-0"
keywords: [web, example]
home: https://example.com/webapp
sources:
  - https://git.example.com/team/webapp
maintainers:
  - name: Ada Lovelace
    email: [email protected]
icon: https://example.com/webapp.svg
dependencies:
  - name: redis
    version: "19.x.x"
    repository: https://charts.example.com
    condition: redis.enabled
annotations:
  category: Web
Field Required Meaning
apiVersion yes v2 for Helm 3 and later charts (v1 is the old Helm 2 format)
name yes Chart name: lowercase letters, digits, dashes
version yes The chart version, a strict SemVer 2 string such as 1.4.0
appVersion no The version of the application inside; free text, quote it
description no One sentence shown in searches
type no application (default, installable) or library (only helpers, cannot be installed)
kubeVersion no A SemVer range of Kubernetes versions the chart supports
dependencies no Subcharts (see the Dependencies chapter)
keywords, home, sources, maintainers, icon, annotations no Metadata for humans and tools
deprecated no true marks the chart as no longer maintained

version versus appVersion

This is the most common confusion. version identifies the chart package and must be bumped every time anything in the chart changes, because repositories treat a published version as immutable. appVersion tells people which release of the software the chart deploys by default. Typical practice:

  • App released as 2.9.0, chart unchanged otherwise: bump appVersion to "2.9.0" and chart version to 0.3.2 (or 0.4.0).
  • Template bug fixed, same app: bump only version.

Quote appVersion: unquoted 1.10 is read by YAML as the number 1.1, silently losing the zero.

Library charts and kubeVersion

A chart with type: library provides helpers for other charts to include and cannot be installed itself. kubeVersion is checked at install time; note the trailing -0 in >=1.27.0-0, which lets managed-cluster versions like v1.29.4-eks-abc123 match the range, since SemVer treats those suffixes as pre-releases.

Validating Chart.yaml with a stand-in

helm lint checks these rules for you. The stand-in below implements the main ones, so you can see what is accepted.

Python Stand-in: lint Chart.yaml fields

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Other files in the chart

values.yaml holds defaults. It is documented in Values and Overrides. Keep every setting a user might need here, with comments.

templates/ contains Go-template YAML. Files ending .yaml, .yml or .tpl are processed; those starting with an underscore (_helpers.tpl) define reusable pieces but produce no manifest of their own. NOTES.txt is rendered and printed after install and upgrade, not applied to the cluster.

charts/ receives dependencies after helm dependency update, as .tgz files or unpacked folders.

crds/ holds CustomResourceDefinitions. Helm installs these before the rest, and never templates them, upgrades them or deletes them, a deliberate safety limit covered in the Dependencies and Hooks chapter.

.helmignore works like .gitignore and keeps files such as .git/, *.swp and test data out of the package.

Packaging a chart

Check, then pack:

Terminal
helm lint ./webapp
helm package ./webapp
TEXT
Successfully packaged chart and saved it to: /home/ada/webapp-0.3.1.tgz

The archive is named <name>-<version>.tgz, a name built from Chart.yaml. That is why two different edits cannot share one version in a repository. You can install straight from the archive or the directory:

Terminal
helm install demo ./webapp-0.3.1.tgz
helm install demo ./webapp

The next TryIt shows how the archive name is built and which files .helmignore excludes.

Python Stand-in: package name and .helmignore

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which two entries in a chart are essential for it to install anything?

    Chart.yaml identifies the chart and templates/ holds the manifests to render.
  2. 2. You fixed a bug in a template; the application version did not change. What do you bump?

    Repositories treat a published chart version as immutable, so any chart change needs a new version.
  3. 3. Why quote appVersion, e.g. "1.10"?

    YAML reads unquoted 1.10 as a float, dropping the zero.
  4. 4. What is a chart with type: library used for?

    Library charts only define named templates and cannot be installed by themselves.

Summary

  • A chart is a directory: Chart.yaml, values.yaml, templates/, optional charts/, crds/, .helmignore and values.schema.json.
  • version is the chart package version (SemVer, bumped on every change); appVersion is the software version and should be quoted.
  • Files starting with an underscore in templates/ define helpers and render no manifest.
  • helm lint checks the chart and helm package produces name-version.tgz.

Next: Creating a Chart with helm create