Anatomy of a chart

Create a chart and look at what Helm generates:

helm create api
tree api

api/
  Chart.yaml
  values.yaml
  charts/
  templates/
    _helpers.tpl
    deployment.yaml
    service.yaml
    serviceaccount.yaml
    hpa.yaml
    ingress.yaml
    NOTES.txt
    tests/
  .helmignore

Chart.yaml

apiVersion: v2
name: api
description: Orders API for the shop
type: application
version: 0.3.0        # chart version, bump on every chart change
appVersion: "1.5.0"   # version of the application it deploys

Two versions, two meanings. version follows semantic versioning for the chart itself. appVersion is informational, usually the default image tag. Mixing them up leads to charts that change without a version bump, which breaks caching in registries.

values.yaml

Defaults that users override. Treat it as the chart's public interface:

replicaCount: 2
image:
  repository: ghcr.io/example/orders-api
  tag: ""            # defaults to appVersion
  pullPolicy: IfNotPresent
resources:
  requests: {cpu: 100m, memory: 128Mi}
  limits: {memory: 256Mi}

Every value you add is a promise to support it. Start small.

templates/

Kubernetes manifests with Go template expressions:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "api.fullname" . }}
  labels:
    {{- include "api.labels" . | nindent 4 }}
spec:
  replicas: {{ .Values.replicaCount }}
  template:
    spec:
      containers:
        - name: api
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
          resources:
            {{- toYaml .Values.resources | nindent 12 }}

_helpers.tpl

Files starting with an underscore are not rendered as manifests. They hold named templates such as api.fullname and api.labels, reused across files so names and labels stay consistent.

Trim what you do not need

helm create generates an Ingress template, test hooks and options you may never use. Delete them. A chart with only the templates your application needs is easier to review and maintain. You can always add features later when a real user asks.

See the output

helm template demo ./api | less

Rendering locally is the single most useful Helm command. Run it after every change.