Chart Structure | DevOps Peach

Docker & Kubernetes · Helm – The Package Manager for Kubernetes · Lesson 3 of 5

Chart Structure

A chart is a folder with Chart.yaml, values.yaml and templates/; helm create scaffolds one, helm lint checks it, helm template renders it.

mychart/
  Chart.yaml           # name, version (chart), appVersion (app), dependencies
  values.yaml          # default values
  values.schema.json   # (optional) JSON Schema that checks values
  charts/              # dependent subcharts
  crds/                # Custom Resource Definitions
  templates/
    deployment.yaml
    service.yaml
    _helpers.tpl       # helpers, renders no manifest
    NOTES.txt          # printed after install
    tests/             # test hooks
  .helmignore          # files skipped when packaging

flowchart LR
  V["values.yaml<br/>+ -f / --set"] --> E["Template engine"]
  T["templates/*.yaml"] --> E
  C["Chart.yaml"] --> E
  E --> M["Kubernetes manifests"]
  M --> K["kube-apiserver"]

# Chart.yaml
apiVersion: v2
name: mychart
version: 0.1.0        # chart version, bump on every chart change
appVersion: "1.27.0"  # version of the app inside

Common traps

Mixing up version (chart) and appVersion (app): changing the app image should still bump the chart version.
Putting CRDs in templates/ instead of crds/: Helm installs crds/ first, so templates that use the CRD do not fail with "no matches for kind".
The helper file is _helpers.tpl (files starting with _ render no manifest).

Command	Meaning
`helm create mychart`	Scaffold a sample chart
`helm lint mychart`	Check syntax errors and best practices
`helm template myrel ./mychart`	Render manifests to the screen without installing
`helm package mychart`	Package as `mychart-0.1.0.tgz`

More Chart.yaml fields

apiVersion: v2
name: mychart
description: Web front end for the shop
type: application          # or library
version: 0.3.1
appVersion: "1.27.0"
kubeVersion: ">=1.28.0-0"
keywords: [web, nginx]
maintainers:
- name: Platform Team
  email: platform@example.com

A library chart (type: library) holds only reusable template helpers and cannot be installed by itself; application charts depend on it to share labels, probes, or a standard Deployment layout. kubeVersion makes Helm refuse to install on clusters that are too old.

Designing good values

Group values by component (web.replicaCount, worker.resources), use camelCase, and document every key with a comment in values.yaml, because that file is the chart's user interface.
Provide safe defaults: resource requests, probes, a non-root security context.
Avoid forcing users to edit templates; expose a value instead, or an extraEnv or extraVolumes escape hatch.

Validating values

A values.schema.json file rejects bad input before anything reaches the cluster:

{
  "type": "object",
  "required": ["image"],
  "properties": {
    "replicaCount": { "type": "integer", "minimum": 1 },
    "image": { "type": "object", "required": ["repository"] }
  }
}

helm install, upgrade, lint, and template all apply the schema.

Testing and publishing

helm lint --strict treats warnings as errors in CI.
The chart-testing tool (ct lint, ct install) checks changed charts in a pull request, including whether the version was bumped.
The helm-unittest plugin asserts on rendered output without a cluster.
helm package --sign creates a provenance file so users can verify the chart with helm verify.

Public charts are indexed on Artifact Hub, where you can compare maintainers, versions, and security reports before choosing one.