How to Write a Helm Chart (Deployment + Service Templates)

From static manifest to template

A plain Deployment hard-codes the image, replica count, and name. A Helm template replaces those with {{ .Values.* }} placeholders so one chart deploys any config. Helm renders the template + values.yaml into real Kubernetes YAML at install time.

values.yaml: the inputs

replicas: 3
image: ghcr.io/example/app:1.0.0
port: 8080

templates/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Chart.Name }}
  labels:
    app: {{ .Chart.Name }}
spec:
  replicas: {{ .Values.replicas }}
  selector:
    matchLabels:
      app: {{ .Chart.Name }}
  template:
    metadata:
      labels:
        app: {{ .Chart.Name }}
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image }}"
          ports:
            - containerPort: {{ .Values.port }}

templates/service.yaml

apiVersion: v1
kind: Service
metadata:
  name: {{ .Chart.Name }}
spec:
  selector:
    app: {{ .Chart.Name }}          # must match the Deployment's pod labels
  ports:
    - port: 80
      targetPort: {{ .Values.port }}

The templating rules that matter

• .Values.x reads from values.yaml; .Chart.Name reads from Chart.yaml.
• Quote interpolated strings (image: "{{ .Values.image }}") so YAML stays valid.
• The Service selector must match the Deployment's pod labels, or the Service will have no endpoints.
• Keep labels consistent (app: {{ .Chart.Name }}) across both.

Render and install

helm template .            # render to plain YAML and check it
helm install myapp .       # deploy to the cluster
helm upgrade myapp . --set replicas=5   # change a value, re-deploy

Template helpers and the gotchas that break a chart

Two helpers do most of the work. {{ include "chart.fullname" . }} pulls in a named template from templates/_helpers.tpl, so names and labels stay consistent across every manifest. And {{- toYaml .Values.resources | nindent 12 }} renders a nested block at the right indentation - forgetting nindent is the number-one cause of error converting YAML to JSON on install.

A few rules that save hours:

• Quote values that look like numbers or booleans: tag: {{ .Values.image.tag | quote }} - an unquoted 1.0 becomes a float.
• Use {{- and -}} to trim whitespace so blank lines don't break the YAML.
• Give every value a default: {{ .Values.replicas | default 1 }}.
• Gate optional blocks with {{- if .Values.ingress.enabled }}.

Run helm template . to see the rendered YAML before you touch a cluster - it catches indentation and templating bugs that helm install only surfaces as a cryptic error.