Skip to main content
Updated Feb 23, 2026

Introduction to Helm

When you deploy your Task API to Kubernetes using kubectl, you apply individual YAML files—one for the Deployment, one for the Service, one for the ConfigMap, maybe one for the Secret. That's 5-10 files for a single service.

Now imagine managing this across three environments: dev, staging, production. Each environment needs different resource limits, different image tags, different replicas. You copy and modify the same files ten times, creating drift and bugs.

Helm solves this problem. Helm is the package manager for Kubernetes. Instead of managing individual YAML files, you create a Helm chart—a templated package that parameterizes your deployment. Change one value file, and your entire Task API deployment adapts automatically.

This lesson teaches you to understand why Helm exists, install it, deploy a public chart, create your own custom chart for your Task API, and manage releases across environments.


Why Helm Exists: The Repetitive YAML Problem

Before Helm, deploying an application to Kubernetes meant writing YAML files by hand:

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: task-api
namespace: default
spec:
replicas: 3
selector:
matchLabels:
app: task-api
template:
metadata:
labels:
app: task-api
spec:
containers:
- name: task-api
image: your-registry/task-api:v1.0.0
ports:
- containerPort: 8000
env:
- name: DATABASE_URL
value: "postgresql://..."
- name: LOG_LEVEL
value: "INFO"
resources:
requests:
memory: "512Mi"
cpu: "250m"
limits:
memory: "1Gi"
cpu: "500m"
# service.yaml
apiVersion: v1
kind: Service
metadata:
name: task-api-service
spec:
type: ClusterIP
ports:
- port: 80
targetPort: 8000
selector:
app: task-api
# configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: task-api-config
data:
log_level: "INFO"
api_timeout: "30"

This works for one environment. But in production, you need:

  • Development: 1 replica, 256Mi memory, DEBUG logging
  • Staging: 2 replicas, 512Mi memory, INFO logging
  • Production: 5 replicas, 1Gi memory, WARN logging

Now you maintain three copies of the same files, edited manually. When you update the base deployment, you must remember to update all three copies. This is error-prone and doesn't scale.

Helm templating solves this. Instead of three copies, you write once with placeholders:

replicas: {{ .Values.replicaCount }}
image: your-registry/task-api:{{ .Values.image.tag }}

Then provide three values files—one for each environment:

# values-dev.yaml
replicaCount: 1
image:
tag: v1.0.0-dev
# values-prod.yaml
replicaCount: 5
image:
tag: v1.0.0

A single helm install task-api ./task-api-chart -f values-prod.yaml command deploys the entire stack to production with the correct configuration.


Installing Helm

Helm is a CLI tool you install on your machine. It then communicates with your Kubernetes cluster to deploy charts.

choco install kubernetes-helm

Or using Scoop:

scoop install helm

Verify Installation

helm version

Output:

version.BuildInfo{Version:"v3.14.0", GitCommit:"3fc9f4b2638e76077605842cc9038889c437f325", GitTreeState:"clean", GoVersion:"go1.22.0"}

Helm is now installed and ready to deploy charts.


Understanding Helm Charts: The Package Structure

A Helm chart is a directory with a specific structure:

task-api-chart/
├── Chart.yaml # Chart metadata (name, version, description)
├── values.yaml # Default configuration values
├── values-dev.yaml # Development-specific overrides
├── values-prod.yaml # Production-specific overrides
├── templates/ # Kubernetes manifests (Go templates)
│ ├── deployment.yaml # Pod deployment template
│ ├── service.yaml # Service template
│ ├── configmap.yaml # ConfigMap template
│ └── helpers.tpl # Template helper functions
└── README.md # Chart documentation

Each file serves a purpose:

  • Chart.yaml: Declares the chart's name, version, description. Think of it like package.json for Kubernetes.
  • values.yaml: Default values for all placeholders. These are overridable per environment.
  • templates/: Kubernetes YAML files with Go template syntax ({{ .Values.replicas }}).
  • values-dev.yaml, values-prod.yaml: Environment-specific value overrides.

When you run helm install, Helm:

  1. Reads Chart.yaml to understand the chart
  2. Loads values.yaml (default values)
  3. Merges in environment-specific values (e.g., values-prod.yaml)
  4. Processes templates/ files, substituting values into placeholders
  5. Applies the rendered YAML to Kubernetes

Deploying a Public Chart: Bitnami Redis

Before creating your own chart, let's deploy a public chart to understand how Helm works.

The Bitnami Helm repository provides production-ready charts for common applications. Let's add it and install Redis:

Step 1: Add the Bitnami Repository

helm repo add bitnami https://charts.bitnami.com/bitnami

Output:

"bitnami" has been added to your repositories

Step 2: Update Repository Index

helm repo update

Output:

Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "bitnami" chart repository
Update Complete. ⎉ Happy Helming!

Step 3: Search for Redis Chart

helm search repo bitnami/redis

Output:

NAME                 	CHART VERSION	APP VERSION	DESCRIPTION
bitnami/redis 18.6.0 7.2.4 Redis(TM) is an open source, advanced key-value ...

Step 4: Install the Chart

helm install my-redis bitnami/redis \
--set auth.enabled=false \
--set replica.replicaCount=1 \
--namespace default

Output:

NAME: my-redis
LAST DEPLOYED: Mon Dec 23 10:45:32 2024
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
CHART NAME: redis
CHART VERSION: 18.6.0
APP VERSION: 7.2.4
** Please be patient while the chart is being deployed **

Redis™ can be accessed via port 6379 on the following DNS name from within your cluster:

my-redis-master.default.svc.cluster.local

To get your Redis™ connection string:

export REDIS_URL="redis://my-redis-master.default.svc.cluster.local:6379"

To connect to your Redis™ instance, run the following commands:

kubectl run --namespace default redis-cli --rm --tty -i --restart='Never' -- redis-cli -h my-redis-master.default.svc.cluster.local -p 6379

Step 5: Verify the Deployment

kubectl get pods -n default

Output:

NAME                READY   STATUS    RESTARTS   AGE
my-redis-master-0 1/1 Running 0 45s
helm list

Output:

NAME     	NAMESPACE	REVISION	UPDATED                 	STATUS  	CHART           	APP VERSION
my-redis default 1 2024-12-23 10:45:32 +0000 UTC deployed redis-18.6.0 7.2.4

You deployed a production-grade Redis instance with a single helm install command. Helm templated all the Redis manifests, applied them to Kubernetes, and created a release called my-redis that you can upgrade, downgrade, or rollback.


Creating Your Own Helm Chart

Now you'll create a custom chart for your Task API from Chapter 49. Instead of managing raw YAML files, you'll use Helm's templating to create a reusable package.

Step 1: Generate Chart Scaffold

Helm provides a generator to create the basic chart structure:

helm create task-api-chart

Output:

Creating task-api-chart
tree task-api-chart

Output:

task-api-chart/
├── Chart.yaml
├── charts
├── templates
│ ├── NOTES.txt
│ ├── _helpers.tpl
│ ├── deployment.yaml
│ ├── hpa.yaml
│ ├── ingress.yaml
│ ├── service.yaml
│ ├── serviceaccount.yaml
│ └── tests
│ └── test-connection.yaml
└── values.yaml

Step 2: Examine Chart.yaml

cat task-api-chart/Chart.yaml

Output:

apiVersion: v2
name: task-api-chart
description: A Helm chart for Kubernetes
type: application
version: 0.1.0
appVersion: "1.16"

This declares the chart metadata. Update it for your Task API:

apiVersion: v2
name: task-api
description: "Helm chart for deploying Task API on Kubernetes"
type: application
version: 0.1.0
appVersion: "1.0.0"
keywords:
- task-api
- fastapi
- kubernetes
maintainers:
- name: "Your Name"
email: "your.email@example.com"

Step 3: Examine values.yaml

cat task-api-chart/values.yaml

Output:

replicaCount: 1

image:
repository: nginx
pullPolicy: IfNotPresent
tag: ""

imagePullSecrets: []
nameOverride: ""
fullnameOverride: ""

serviceAccount:
create: true
annotations: {}
name: ""

podAnnotations: {}

podSecurityContext: {}

securityContext: {}

service:
type: ClusterIP
port: 80

ingress:
enabled: false
className: ""
annotations: {}
hosts:
- host: chart-example.local
paths:
- path: /
pathType: ImplementationSpecific
tls: []

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

autoscaling:
enabled: false
minReplicas: 1
maxReplicas: 100
targetCPUUtilizationPercentage: 80

nodeSelector: {}

tolerations: []

affinity: {}

This is the template of all values. Each value is referenced by name in templates (e.g., {{ .Values.replicaCount }}). Update values.yaml for your Task API:

replicaCount: 3

image:
repository: your-registry/task-api
pullPolicy: Always
tag: "v1.0.0"

imagePullSecrets:
- name: registry-secret

service:
type: ClusterIP
port: 8000
targetPort: 8000

resources:
limits:
cpu: 500m
memory: 1Gi
requests:
cpu: 250m
memory: 512Mi

env:
- name: DATABASE_URL
value: "postgresql://localhost:5432/tasks"
- name: LOG_LEVEL
value: "INFO"
- name: API_TIMEOUT
value: "30"

Step 4: Examine the Deployment Template

cat task-api-chart/templates/deployment.yaml

Output:

apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "task-api-chart.fullname" . }}
labels:
{{- include "task-api-chart.labels" . | nindent 4 }}
spec:
{{- if not .Values.autoscaling.enabled }}
replicas: {{ .Values.replicaCount }}
{{- end }}
selector:
matchLabels:
{{- include "task-api-chart.selectorLabels" . | nindent 6 }}
template:
metadata:
{{- with .Values.podAnnotations }}
annotations:
{{- toYaml . | nindent 8 }}
{{- end }}
labels:
{{- include "task-api-chart.selectorLabels" . | nindent 8 }}
spec:
{{- with .Values.imagePullSecrets }}
imagePullSecrets:
{{- toYaml . | nindent 8 }}
{{- end }}
serviceAccountName: {{ include "task-api-chart.serviceAccountName" . }}
securityContext:
{{- toYaml .Values.podSecurityContext | nindent 8 }}
containers:
- name: {{ .Chart.Name }}
securityContext:
{{- toYaml .Values.securityContext | nindent 12 }}
image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
imagePullPolicy: {{ .Values.image.pullPolicy }}
ports:
- name: http
containerPort: 8000
protocol: TCP
livenessProbe:
httpGet:
path: /health
port: http
initialDelaySeconds: 30
periodSeconds: 10
readinessProbe:
httpGet:
path: /ready
port: http
initialDelaySeconds: 10
periodSeconds: 5
resources:
{{- toYaml .Values.resources | nindent 12 }}
env:
{{- if .Values.env }}
{{- toYaml .Values.env | nindent 10 }}
{{- end }}
{{- with .Values.nodeSelector }}
nodeSelector:
{{- toYaml . | nindent 8 }}
{{- end }}
{{- with .Values.affinity }}
affinity:
{{- toYaml . | nindent 8 }}
{{- end }}
{{- with .Values.tolerations }}
tolerations:
{{- toYaml . | nindent 8 }}
{{- end }}

This template uses Go template syntax:

  • {{ .Values.replicaCount }} — Substitutes the value of replicaCount from values.yaml
  • {{ include "task-api-chart.fullname" . }} — Calls a helper function (defined in _helpers.tpl)
  • {{- if .Values.autoscaling.enabled }} — Conditional: include this section only if autoscaling is enabled
  • {{ toYaml . | nindent 8 }} — Converts a value to YAML and indents it 8 spaces

Step 5: Test Template Rendering

Before deploying, preview what Helm will generate:

helm template my-release task-api-chart

Output:

---
# Source: task-api-chart/templates/serviceaccount.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
name: my-release-task-api-chart
labels:
helm.sh/chart: task-api-chart-0.1.0
app.kubernetes.io/name: task-api-chart
app.kubernetes.io/instance: my-release
app.kubernetes.io/version: "1.0.0"
app.kubernetes.io/managed-by: Helm
---
# Source: task-api-chart/templates/service.yaml
apiVersion: v1
kind: Service
metadata:
name: my-release-task-api-chart
labels:
helm.sh/chart: task-api-chart-0.1.0
app.kubernetes.io/name: task-api-chart
app.kubernetes.io/instance: my-release
app.kubernetes.io/version: "1.0.0"
app.kubernetes.io/managed-by: Helm
spec:
type: ClusterIP
ports:
- port: 8000
targetPort: http
protocol: TCP
name: http
selector:
app.kubernetes.io/name: task-api-chart
app.kubernetes.io/instance: my-release
---
# Source: task-api-chart/templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-release-task-api-chart
labels:
helm.sh/chart: task-api-chart-0.1.0
app.kubernetes.io/name: task-api-chart
app.kubernetes.io/instance: my-release
app.kubernetes.io/version: "1.0.0"
app.kubernetes.io/managed-by: Helm
spec:
replicas: 3
selector:
matchLabels:
app.kubernetes.io/name: task-api-chart
app.kubernetes.io/instance: my-release
template:
metadata:
labels:
helm.sh/chart: task-api-chart-0.1.0
app.kubernetes.io/name: task-api-chart
app.kubernetes.io/instance: my-release
app.kubernetes.io/version: "1.0.0"
app.kubernetes.io/managed-by: Helm
spec:
serviceAccountName: my-release-task-api-chart
containers:
- name: task-api-chart
image: "your-registry/task-api:v1.0.0"
imagePullPolicy: Always
ports:
- name: http
containerPort: 8000
protocol: TCP
livenessProbe:
httpGet:
path: /health
port: http
initialDelaySeconds: 30
periodSeconds: 10
readinessProbe:
httpGet:
path: /ready
port: http
initialDelaySeconds: 10
periodSeconds: 5
resources:
limits:
cpu: 500m
memory: 1Gi
requests:
cpu: 250m
memory: 512Mi
env:
- name: MODEL_NAME
value: "gpt-4"
- name: LOG_LEVEL
value: "INFO"
- name: API_TIMEOUT
value: "30"

Helm rendered the templates with values from values.yaml. The output is valid Kubernetes YAML.


Environment-Specific Values: Dev vs Production

Now create environment-specific value files to customize deployments:

values-dev.yaml

replicaCount: 1

image:
tag: "v1.0.0-dev"

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

env:
- name: DATABASE_URL
value: "postgresql://localhost:5432/tasks_dev"
- name: LOG_LEVEL
value: "DEBUG"
- name: API_TIMEOUT
value: "60"

values-prod.yaml

replicaCount: 5

image:
tag: "v1.0.0"

resources:
limits:
cpu: 1000m
memory: 2Gi
requests:
cpu: 500m
memory: 1Gi

env:
- name: DATABASE_URL
value: "postgresql://prod-db:5432/tasks"
- name: LOG_LEVEL
value: "WARN"
- name: API_TIMEOUT
value: "30"

autoscaling:
enabled: true
minReplicas: 3
maxReplicas: 10
targetCPUUtilizationPercentage: 70

Deploy to Development

helm install task-api task-api-chart -f task-api-chart/values-dev.yaml

Output:

NAME: task-api
LAST DEPLOYED: Mon Dec 23 11:05:22 2024
NAMESPACE: default
STATUS: deployed
REVISION: 1

Verify the deployment:

kubectl get deployment task-api

Output:

NAME                      READY   UP-TO-DATE   AVAILABLE   AGE
task-api 1/1 1 1 15s

Notice: 1 replica in dev (from values-dev.yaml).

Deploy to Production

helm install task-api-prod task-api-chart -f task-api-chart/values-prod.yaml

Output:

NAME: task-api-prod
LAST DEPLOYED: Mon Dec 23 11:06:45 2024
NAMESPACE: default
STATUS: deployed
REVISION: 1

Verify:

kubectl get deployment task-api-prod

Output:

NAME                          READY   UP-TO-DATE   AVAILABLE   AGE
task-api-prod 5/5 5 5 18s

Notice: 5 replicas in production (from values-prod.yaml).


Release Management: Upgrade, Rollback, Uninstall

A release is an instance of a chart deployed to your cluster. You manage releases with four operations: install, upgrade, rollback, and uninstall.

Install (Create a Release)

helm install task-api task-api-chart -f task-api-chart/values-prod.yaml

Output:

NAME: task-api
LAST DEPLOYED: Mon Dec 23 11:15:22 2024
NAMESPACE: default
STATUS: deployed
REVISION: 1

Upgrade (Update a Release)

You've pushed a new version of your agent image. Update the release to use it:

helm upgrade task-api task-api-chart \
-f task-api-chart/values-prod.yaml \
--set image.tag="v1.1.0"

Output:

Release "task-api" has been upgraded successfully
NAME: task-api
LAST DEPLOYED: Mon Dec 23 11:16:33 2024
NAMESPACE: default
STATUS: deployed
REVISION: 2

Notice the revision changed from 1 to 2. Helm tracks every release change.

Verify the rollout:

kubectl rollout status deployment/task-api

Output:

deployment "task-api" successfully rolled out

Check Release History

helm history task-api

Output:

REVISION	UPDATED                 	STATUS    	CHART                  	APP VERSION	DESCRIPTION
1 Mon Dec 23 11:15:22 2024 superseded task-api-chart-0.1.0 1.0.0 Install complete
2 Mon Dec 23 11:16:33 2024 deployed task-api-chart-0.1.0 1.0.0 Upgrade complete

Rollback (Revert to a Previous Release)

The new version has a bug. Rollback to revision 1:

helm rollback task-api 1

Output:

Rollback was a success
Release "task-api" has been rolled back to revision 1

Verify:

helm history task-api

Output:

REVISION	UPDATED                 	STATUS    	CHART                  	APP VERSION	DESCRIPTION
1 Mon Dec 23 11:15:22 2024 superseded task-api-chart-0.1.0 1.0.0 Install complete
2 Mon Dec 23 11:16:33 2024 superseded task-api-chart-0.1.0 1.0.0 Upgrade complete
3 Mon Dec 23 11:17:45 2024 deployed task-api-chart-0.1.0 1.0.0 Rollback to 1

A new revision (3) was created that rolls back to revision 1's configuration. The agent is now running the old image again.

Uninstall (Delete a Release)

helm uninstall task-api

Output:

release "task-api" uninstalled

All Kubernetes resources created by this release are deleted:

kubectl get deployment

Output:

No resources found in default namespace.

What You've Learned

You now understand:

  • Why Helm exists: It solves the repetitive YAML problem by templating deployments
  • How to install Helm: On macOS, Linux, and verify installation
  • How to deploy public charts: Using helm repo add, helm search, and helm install
  • Chart structure: Chart.yaml, values.yaml, templates/, and helper functions
  • Go template syntax: Substitution ({{ .Values.replicaCount }}), helpers, conditionals
  • Environment-specific values: Creating separate values files for dev/prod deployments
  • Release management: Install, upgrade, rollback, and uninstall operations

With these skills, you can package any Kubernetes application—including your Task API—into a reusable, versioned Helm chart that deploys consistently across environments.


Try With AI

Now you'll work with AI to create a multi-environment Helm configuration for your Task API.

Setup: You have your Task API container image from Chapter 49 pushed to a registry. You'll parameterize a Helm chart to support three environments (dev, staging, production) with different replicas, resources, and database configurations.

Prompts:

  1. Chart Creation with AI:

    I have my Task API image at your-registry/task-api:latest from Chapter 49.
    Create a Helm chart called 'task-api' with:
    - Deployment for the Task API (port 8000)
    - Service exposing the API (ClusterIP)
    - ConfigMap for configuration (DATABASE_URL, LOG_LEVEL)
    - Default values: 3 replicas, 500m CPU limit, 1Gi memory limit

    What does the Chart.yaml and values.yaml look like?
  2. Environment Values with AI:

    Now create three values files for the Task API chart:

    values-dev.yaml: 1 replica, 250m CPU, 512Mi memory, DEBUG logging
    values-staging.yaml: 2 replicas, 500m CPU, 1Gi memory, INFO logging
    values-prod.yaml: 5 replicas, 1Gi CPU, 2Gi memory, WARN logging

    Should I use separate files or one values file with conditionals?
  3. Refinement Based on Response: Ask the AI to clarify:

    • How would you handle the DATABASE_URL secret without storing it in values files?
    • Can I use Helm hooks to run database migrations before the Task API starts?

Expected: You'll discover that environment-specific values files are cleaner than conditionals, and learn about Helm's secret management and hooks—features you'll explore in later lessons.


Reflect on Your Skill

You built a helm-chart skill in Lesson 0. Test and improve it based on what you learned.

Test Your Skill

Using my helm-chart skill, generate a basic Helm chart for a web service.
Does my skill understand Chart.yaml structure and values.yaml defaults?

Identify Gaps

Ask yourself:

  • Did my skill include proper Chart.yaml metadata (apiVersion, name, version, description)?
  • Did it generate a sensible values.yaml with image, replicas, and service configuration?
  • Does it understand the templates/ directory structure and basic Go template syntax?

Improve Your Skill

If you found gaps:

My helm-chart skill is missing [proper Chart.yaml structure / values organization / template basics].
Update it to include best practices for:
- Chart.yaml metadata fields
- Default values.yaml structure
- Basic Deployment and Service templates
- Environment-specific values files (values-dev.yaml, values-prod.yaml)