Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 38 ยท Projects and Practice

Project: A Production-Ready Web App Chart

Build a complete Helm chart for a web application: Deployment, Service, Ingress, HPA, PDB, migration hook, schema, tests and CI, with a values-per-environment stand-in.

In this project you assemble everything from the course into one chart for a web service called notes-api: a stateless HTTP API that needs a database migration at upgrade time, an optional Ingress, autoscaling and a safe security posture. Read it as a blueprint you can copy and adapt. Helm cannot run on this site, so the YAML is read-only and the runnable stand-ins check the logic of the chart in Python.

Requirements

  1. One Deployment with probes, resource limits and a non-root security context.
  2. A Service, and an Ingress that is off by default.
  3. A HorizontalPodAutoscaler when autoscaling.enabled is true, replicas fixed otherwise.
  4. A PodDisruptionBudget when more than one replica runs.
  5. A pre-upgrade migration Job as a hook.
  6. A values.schema.json, a test hook, and per-environment values files.
  7. CI that lints, unit-tests and publishes.

Layout

TEXT
notes-api/
  Chart.yaml
  values.yaml
  values.schema.json
  .helmignore
  ci/
    default-values.yaml
    ingress-values.yaml
  templates/
    _helpers.tpl
    deployment.yaml
    service.yaml
    ingress.yaml
    hpa.yaml
    pdb.yaml
    migrate-job.yaml
    configmap.yaml
    tests/test-connection.yaml
  tests/
    deployment_test.yaml
  envs/
    values-dev.yaml
    values-prod.yaml

Chart.yaml and defaults

YAML
apiVersion: v2
name: notes-api
description: HTTP API for notes
type: application
version: 0.1.0
appVersion: "2.4.0"
keywords: [api, notes]
YAML
# values.yaml
replicaCount: 2
image:
  repository: registry.example.com/notes-api
  tag: ""              # defaults to .Chart.AppVersion
  pullPolicy: IfNotPresent
service:
  type: ClusterIP
  port: 80
containerPort: 8080
ingress:
  enabled: false
  className: nginx
  host: ""
  tls: false
autoscaling:
  enabled: false
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70
resources:
  requests: { cpu: 100m, memory: 128Mi }
  limits: { memory: 256Mi }
migration:
  enabled: true
config:
  LOG_LEVEL: info
existingSecret: ""     # name of a Secret with DATABASE_URL
podSecurityContext:
  runAsNonRoot: true
  seccompProfile: { type: RuntimeDefault }
securityContext:
  allowPrivilegeEscalation: false
  readOnlyRootFilesystem: true
  capabilities: { drop: ["ALL"] }

Helpers

YAML
{{/* templates/_helpers.tpl */}}
{{- define "notes-api.fullname" -}}
{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" -}}
{{- end -}}

{{- define "notes-api.labels" -}}
app.kubernetes.io/name: {{ .Chart.Name }}
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
helm.sh/chart: {{ printf "%s-%s" .Chart.Name .Chart.Version }}
{{- end -}}

{{- define "notes-api.selectorLabels" -}}
app.kubernetes.io/name: {{ .Chart.Name }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end -}}

{{- define "notes-api.image" -}}
{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}
{{- end -}}

Selector labels are kept separate from the full label set: selectors are immutable, while labels like the chart version change on every release.

The Deployment

YAML
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "notes-api.fullname" . }}
  labels: {{- include "notes-api.labels" . | nindent 4 }}
spec:
  {{- if not .Values.autoscaling.enabled }}
  replicas: {{ .Values.replicaCount }}
  {{- end }}
  selector:
    matchLabels: {{- include "notes-api.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      annotations:
        checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
      labels: {{- include "notes-api.selectorLabels" . | nindent 8 }}
    spec:
      securityContext: {{- toYaml .Values.podSecurityContext | nindent 8 }}
      containers:
        - name: api
          image: {{ include "notes-api.image" . | quote }}
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          ports:
            - name: http
              containerPort: {{ .Values.containerPort }}
          envFrom:
            - configMapRef:
                name: {{ include "notes-api.fullname" . }}
            {{- if .Values.existingSecret }}
            - secretRef:
                name: {{ .Values.existingSecret }}
            {{- end }}
          readinessProbe:
            httpGet: { path: /healthz, port: http }
          livenessProbe:
            httpGet: { path: /healthz, port: http }
            initialDelaySeconds: 10
          resources: {{- toYaml .Values.resources | nindent 12 }}
          securityContext: {{- toYaml .Values.securityContext | nindent 12 }}

Three details to copy: replicas are omitted when the HPA owns them (otherwise every upgrade would reset the autoscaler's choice), the checksum annotation rolls Pods when config changes, and the image tag falls back to appVersion.

The migration hook

YAML
{{- if .Values.migration.enabled }}
apiVersion: batch/v1
kind: Job
metadata:
  name: {{ include "notes-api.fullname" . }}-migrate
  annotations:
    "helm.sh/hook": pre-install,pre-upgrade
    "helm.sh/hook-weight": "0"
    "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded
spec:
  backoffLimit: 0
  activeDeadlineSeconds: 300
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: migrate
          image: {{ include "notes-api.image" . | quote }}
          command: ["./notes-api", "migrate"]
          envFrom:
            - secretRef:
                name: {{ required "existingSecret is required when migration.enabled" .Values.existingSecret }}
{{- end }}

Environment values

YAML
# envs/values-prod.yaml
replicaCount: 4
autoscaling: { enabled: true, minReplicas: 4, maxReplicas: 20 }
ingress: { enabled: true, host: notes.example.com, tls: true }
config: { LOG_LEVEL: warn }
existingSecret: notes-api-prod

The layering is: chart defaults, then envs/values-<env>.yaml, then --set image.tag=... from CI. The stand-in applies the rules the templates implement so you can see what each environment gets.

Python Stand-in: what does each environment render?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Test hook, schema and unit tests

The test Pod from the testing lesson curls /healthz. The schema from values validation restricts replicaCount to 1-50, pullPolicy to the three legal values, and sets additionalProperties: false on image and autoscaling. Unit tests assert at least:

  • replicas appear only when autoscaling is off,
  • the image falls back to appVersion,
  • the Ingress is absent by default and has a TLS block when ingress.tls is true,
  • the PDB is absent for a single replica,
  • the migration Job fails with a clear message without existingSecret.
Python Stand-in: unit tests for the chart's rules

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

CI and release

Wire the chart into the pipeline from Helm in CI: unit tests, ct lint with version check, a kind install using both files in ci/, then publish to the registry. Deploy production with:

Terminal
helm upgrade --install notes oci://ghcr.io/my-org/charts/notes-api --version 0.1.0 \
  -n prod -f envs/values-prod.yaml --set image.tag=$GITHUB_SHA \
  --atomic --wait --timeout 10m --history-max 10

Extension ideas

  • Add a NetworkPolicy template and a values.networkPolicy.enabled switch.
  • Add a ServiceMonitor behind a condition for Prometheus users.
  • Move the helpers into a library chart shared with the next service.
  • Sign the package and verify it in the deploy job.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Why is spec.replicas omitted when autoscaling is enabled?

    If the chart sets replicas, every upgrade overwrites what the HPA scaled to.
  2. 2. Why are selector labels defined separately from all labels?

    Changing a Deployment selector fails the upgrade, so keep it stable.
  3. 3. What does the checksum/config annotation achieve?

    A changed annotation changes the Pod template, causing a rolling update.

Summary

  • A production chart is the sum of small decisions: stable selectors, optional resources behind values, safe defaults, a migration hook and a checksum annotation.
  • Layer values: chart defaults, environment file, CI --set.
  • Test rules in unit tests, validate values with a schema, and ship through a pipeline with version gates.

Next: Project: An Umbrella Chart for a Shop