How to Write and Lint Kubernetes Helm Charts

Why Helm charts, and what a chart actually is

A raw Kubernetes Deployment hard-codes the image, tag, and replica count. Deploy the same app to staging and prod and you end up copy-pasting near-identical YAML. A Helm chart fixes that: it is a directory of templates plus a values.yaml of inputs, and Helm renders them into real manifests at deploy time. Change one value, get a new environment - no forked YAML.

A minimal chart needs exactly three files:

• chart/Chart.yaml - chart metadata
• chart/values.yaml - the default inputs
• chart/templates/deployment.yaml - a manifest that reads from those values

This project authors and validates that chart. It intentionally stops before helm install - helm lint and helm template prove the chart is correct without touching a cluster.

Step 1 - Chart.yaml metadata

Chart.yaml identifies the chart. apiVersion: v2 is required for Helm 3; name and version are what helm lint checks for.

apiVersion: v2
name: web
description: Web deployment
type: application
version: 0.1.0
appVersion: "1.0"

Note appVersion is quoted - "1.0" would otherwise parse as a float and drop the trailing zero.

Step 2 - values.yaml inputs

These are the defaults every template can reference. Override any of them at render time with --set.

image: nginx
tag: "1.27"
replicaCount: 2

Step 3 - the templated Deployment

In chart/templates/deployment.yaml, replace the hard-coded fields with Helm's {{ .Values.* }} syntax. {{ .Release.Name }} is a built-in Helm gives you at render time - it is the release name you pass to helm template/helm install.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}-web
  labels:
    app: {{ .Release.Name }}-web
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      app: {{ .Release.Name }}-web
  template:
    metadata:
      labels:
        app: {{ .Release.Name }}-web
    spec:
      containers:
        - name: web
          image: "{{ .Values.image }}:{{ .Values.tag }}"

Quote the image line so the rendered value comes out as a string (image: "nginx:1.27"), not a bare token.

Step 4 - lint and render

helm lint checks the chart structure - required Chart.yaml fields, valid template syntax, YAML that parses:

helm lint chart/
# 1 chart(s) linted, 0 chart(s) failed

helm template renders the chart to stdout so you can eyeball the actual manifest Helm would apply. This never contacts a cluster:

helm template web chart/

The rendered output should contain image: "nginx:1.27" and replicas: 2. To prove the values are wired correctly, override one and confirm the change:

helm template web chart/ --set replicaCount=5   # renders replicas: 5

If --set replicaCount=5 still shows replicas: 2, the template is not reading from .Values.replicaCount - it has the number hard-coded. That is the single most common mistake when writing a first chart.