Chart Layout and Chart.yaml

What lives where

A chart directory has a fixed shape. Chart.yaml holds metadata: apiVersion: v2 (for Helm 3 and later), name, version, appVersion, type, description and dependencies. values.yaml holds defaults. templates/ holds the manifest templates; files beginning with _ (such as _helpers.tpl) are not rendered as manifests and hold reusable named templates; templates/NOTES.txt is rendered and printed after install. charts/ holds packaged subcharts; crds/ holds CustomResourceDefinitions installed before everything else; values.schema.json optionally validates values; .helmignore excludes files from packaging. Two version fields confuse everyone: version is the chart's own SemVer version, bumped whenever the chart changes; appVersion is the version of the application it deploys, informational, often used as the default image tag. type is application (installable) or library (only helpers for other charts).

The chart directory

Metadata, defaults, templates and optional extras each have a fixed place.

A typical Chart.yaml

The chart is at version 1.4.0 and deploys application version 2.8.0.

apiVersion: v2
name: shop-api
description: Orders and catalogue API for the shop
type: application
version: 1.4.0        # chart version (SemVer) - bump on every chart change
appVersion: "2.8.0"   # version of the app being deployed
kubeVersion: ">=1.28.0-0"
maintainers:
  - name: platform-team
    email: platform@example.com
dependencies:
  - name: postgresql
    version: 1.2.x
    repository: oci://registry.example.com/charts
    condition: postgresql.enabled

Bump version even for template-only changes

Changing a template without bumping version means two different charts share one version number. Make CI fail if templates changed but Chart.yaml version did not.

Quick check: What does the `version` field in Chart.yaml describe?

• The version of the chart itself
• The Kubernetes version
• The application's container image tag only
• The Helm CLI version