# Chart Layout and Chart.yaml — Helm

Source: https://www.skillbyai.com/en/helm/c-structure

> Describe every file in a chart and the difference between version and appVersion.

## 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 folder tree: one root folder branching into a metadata file, a defaults file, a templates folder with several files, and a subcharts folder.](assets/figures/helm/section-3-map.svg) — Figure 3.1 — Files and folders of a Helm chart.

## A typical Chart.yaml

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

```yaml
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.

**Quiz:** What does the `version` field in Chart.yaml describe?

- [x] The version of the chart itself
- [ ] The Kubernetes version
- [ ] The application's container image tag only
- [ ] The Helm CLI version

*Answer:* The version of the chart itself. version is the chart's SemVer; appVersion describes the application being deployed.