Helm Charts: Writing Your Own

my-app/
├── Chart.yaml          # Chart metadata: name, version, appVersion, description, dependencies
├── values.yaml         # Default values — overridden per environment or at install time
├── values-staging.yaml # Environment-specific overrides (not loaded automatically — you pass -f)
├── values-prod.yaml
├── templates/          # Go template files — rendered into Kubernetes manifests
│   ├── _helpers.tpl    # Named templates (partials) — NOT rendered directly, only called
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   ├── configmap.yaml
│   ├── hpa.yaml
│   └── NOTES.txt       # Printed to stdout after helm install — usage instructions
├── charts/             # Dependency charts (subcharts) — populated by helm dependency update
└── .helmignore         # Files to exclude from the chart package (like .gitignore)

# Create the scaffolding for a new chart:
helm create my-app
# Generates a working chart with a sample Deployment, Service, Ingress, HPA, and ServiceAccount
# Start here, then strip out what you don't need and customise what you do

# Chart.yaml — chart metadata
apiVersion: v2                  # v2: Helm 3 format (v1 was Helm 2)
name: payment-api
description: Payment API service for dataplexa platform
type: application               # application: deployable. library: helpers only, not deployable
version: 1.4.2                  # Chart version — bump this when you change the chart
                                # Follows semver: major.minor.patch
appVersion: "3.0.0"             # Application version — what you're deploying (informational)
                                # Appears in 'helm list' output — helpful for audit
keywords:
  - payments
  - api
maintainers:
  - name: Platform Team
    email: platform@company.com
dependencies:                   # Charts this chart depends on (sub-charts)
  - name: postgresql
    version: "12.x.x"
    repository: https://charts.bitnami.com/bitnami
    condition: postgresql.enabled  # Only install if values.postgresql.enabled is true

# values.yaml — default values (safe for development)
replicaCount: 2

image:
  repository: 123456789012.dkr.ecr.us-east-1.amazonaws.com/payment-api
  tag: ""                       # Empty string: templates will use .Chart.AppVersion as fallback
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 80
  targetPort: 8080

ingress:
  enabled: false                # Feature flags control optional resources
  host: ""
  tlsSecretName: ""

resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 256Mi

autoscaling:
  enabled: false
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70

postgresql:
  enabled: false                # Subchart toggle — don't deploy postgres by default

config:
  logLevel: info
  featureFlags:
    newCheckoutFlow: false
    fraudDetectionV2: false

podAnnotations: {}              # Empty map — templates check if non-empty before rendering
nodeSelector: {}
tolerations: []
affinity: {}

# templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "payment-api.fullname" . }}      # Named template from _helpers.tpl
  namespace: {{ .Release.Namespace }}               # Namespace the chart is installed into
  labels:
    {{- include "payment-api.labels" . | nindent 4 }}
    # include: calls a named template and returns its output as a string
    # nindent 4: adds a newline then indents 4 spaces — critical for valid YAML
spec:
  {{- if not .Values.autoscaling.enabled }}          # Conditional: only set replicas if no HPA
  replicas: {{ .Values.replicaCount }}               # HPA manages replicas when enabled
  {{- end }}
  selector:
    matchLabels:
      {{- include "payment-api.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        {{- include "payment-api.selectorLabels" . | nindent 8 }}
      {{- with .Values.podAnnotations }}              # 'with' changes the dot scope to the value
      annotations:                                    # and skips the block if the value is empty/nil
        {{- toYaml . | nindent 8 }}                  # toYaml: converts the map to YAML string
      {{- end }}
    spec:
      containers:
        - name: payment-api
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
          # default: returns the fallback if the value is empty
          # So if image.tag is "", use Chart.AppVersion ("3.0.0")
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          ports:
            - containerPort: {{ .Values.service.targetPort }}
          env:
            - name: LOG_LEVEL
              value: {{ .Values.config.logLevel | quote }}
              # quote: wraps the value in double quotes — important for string values
              # that might look like numbers or booleans (e.g. "true", "80")
            - name: FEATURE_NEW_CHECKOUT
              value: {{ .Values.config.featureFlags.newCheckoutFlow | toString | quote }}
          resources:
            {{- toYaml .Values.resources | nindent 12 }}
      {{- with .Values.nodeSelector }}
      nodeSelector:
        {{- toYaml . | nindent 8 }}
      {{- end }}
      {{- with .Values.tolerations }}
      tolerations:
        {{- toYaml . | nindent 8 }}
      {{- end }}

# templates/ingress.yaml
{{- if .Values.ingress.enabled }}           # The entire file is gated — nothing rendered if disabled
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ include "payment-api.fullname" . }}
  namespace: {{ .Release.Namespace }}
  labels:
    {{- include "payment-api.labels" . | nindent 4 }}
spec:
  {{- if .Values.ingress.tlsSecretName }}   # Only render TLS block if a secret name is provided
  tls:
    - hosts:
        - {{ .Values.ingress.host | quote }}
      secretName: {{ .Values.ingress.tlsSecretName | quote }}
  {{- end }}
  rules:
    - host: {{ .Values.ingress.host | quote }}
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: {{ include "payment-api.fullname" . }}
                port:
                  number: {{ .Values.service.port }}
{{- end }}

# templates/_helpers.tpl

{{/*
Expand the name of the chart.
*/}}
{{- define "payment-api.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
{{- end }}
# trunc 63: Kubernetes names max at 63 chars
# trimSuffix "-": clean up any trailing hyphens after truncation

{{/*
Create a default fully qualified app name.
Release name + chart name, truncated to 63 characters.
If release name already contains the chart name, use only the release name.
*/}}
{{- define "payment-api.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- $name := default .Chart.Name .Values.nameOverride }}
{{- if contains $name .Release.Name }}
{{- .Release.Name | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}
{{- end }}

{{/*
Standard labels — applied to every resource for consistent identification.
These follow Kubernetes recommended labels (app.kubernetes.io/* namespace).
*/}}
{{- define "payment-api.labels" -}}
helm.sh/chart: {{ printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 }}
{{ include "payment-api.selectorLabels" . }}
{{- if .Chart.AppVersion }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
{{- end }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

{{/*
Selector labels — used in matchLabels (must be immutable after first deploy)
Keep this minimal: only labels that uniquely identify the Pod
*/}}
{{- define "payment-api.selectorLabels" -}}
app.kubernetes.io/name: {{ include "payment-api.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

# values-prod.yaml — only the keys that differ from values.yaml defaults
replicaCount: 5              # Higher replicas in prod

image:
  tag: "3.0.0"               # Pin a specific tag in prod (never use latest)

ingress:
  enabled: true              # Enable ingress in prod
  host: api.company.com
  tlsSecretName: api-tls-cert

resources:
  requests:
    cpu: 250m
    memory: 256Mi
  limits:
    cpu: 1
    memory: 512Mi

autoscaling:
  enabled: true
  minReplicas: 5
  maxReplicas: 20

config:
  logLevel: warn             # Less verbose in prod
  featureFlags:
    newCheckoutFlow: true    # Feature enabled in prod
    fraudDetectionV2: true

# Install or upgrade with environment-specific values
helm upgrade --install payment-api ./payment-api \
  --namespace payments \
  --create-namespace \
  -f values-prod.yaml \
  --set image.tag=3.1.0 \
  --atomic \
  --timeout 5m
# --upgrade --install: create if not exists, upgrade if exists (idempotent)
# -f values-prod.yaml: overlay prod values on top of defaults
# --set image.tag: --set overrides -f overrides values.yaml (rightmost wins)
# --atomic: rollback automatically if the upgrade fails (pods don't become Ready)
# --timeout: how long to wait for pods to become Ready before declaring failure

# Dry run — see exactly what would change without touching the cluster:
helm upgrade --install payment-api ./payment-api \
  -f values-prod.yaml \
  --set image.tag=3.1.0 \
  --dry-run

# Diff against what's currently deployed (requires helm-diff plugin):
helm diff upgrade payment-api ./payment-api \
  -f values-prod.yaml \
  --set image.tag=3.1.0