Helm Package Management

Introduction

Early in my Kubernetes journey, I maintained hundreds of YAML files for deploying applications across multiple environments. Every configuration change required editing multiple files, and keeping development, staging, and production in sync was a nightmare. Then I discovered Helm, and it completely transformed how I managed Kubernetes applications.

Over the years, I've built custom Helm charts for complex microservices architectures, contributed to open-source charts, and designed chart repositories for enterprise organizations. I've debugged chart template issues, optimized upgrade strategies, and learned the hard way about the importance of proper versioning and rollback procedures.

In this comprehensive guide, I'll share everything I've learned about Helm—from basic concepts to advanced templating techniques and production-ready deployment patterns.

Table of Contents

1. Understanding Helm

2. Helm Architecture and Components

3. Installing and Configuring Helm

4. Working with Helm Charts

5. Creating Custom Charts

6. Helm Templating

7. Managing Releases

8. Values and Configuration

9. Chart Repositories

10. Helm Hooks and Lifecycle

11. Advanced Patterns

12. Troubleshooting Helm Issues

13. Best Practices

14. What I Learned

Understanding Helm

Helm is the package manager for Kubernetes, often called "the apt/yum/homebrew for Kubernetes." It solves the problem of managing complex Kubernetes applications by packaging multiple resources into reusable, versioned units called charts.

The Problem Helm Solves

Without Helm, deploying a typical application requires managing numerous YAML files for deployments, services, ConfigMaps, secrets, ingresses, and more. Each environment needs different configurations, leading to file duplication or complex templating scripts. Helm provides a standardized solution for packaging, versioning, and distributing Kubernetes applications.

Traditional Approach Problems

• Duplication: Separate files for dev, staging, prod

• Inconsistency: Manual edits lead to drift between environments

• Versioning: No standard way to version application releases

• Rollback: Manual process to revert changes

• Dependency Management: No tracking of component versions

How Helm Helps

• Packaging: Bundle all Kubernetes resources into a single chart

• Templating: Single template with environment-specific values

• Versioning: Semantic versioning for releases

• Rollback: Built-in rollback to previous versions

• Dependency Management: Charts can depend on other charts

• Distribution: Share charts via repositories

Helm Architecture and Components

Helm 3 architecture is simpler than Helm 2 (which had Tiller):

Key Components

1. Helm CLI: Command-line tool for managing charts and releases

2. Chart: Package containing all resource definitions and templates

3. Repository: Collection of charts (like npm registry or Docker Hub)

4. Release: Instance of a chart running in a cluster

5. Values: Configuration that customizes a chart

Installing and Configuring Helm

Installation

# macOS
brew install helm

# Linux (script)
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# Windows (Chocolatey)
choco install kubernetes-helm

# Verify installation
helm version

Basic Configuration

# Add official Helm stable repository
helm repo add stable https://charts.helm.sh/stable

# Add Bitnami repository (actively maintained)
helm repo add bitnami https://charts.bitnami.com/bitnami

# Add Prometheus community charts
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts

# Update repository index
helm repo update

# List repositories
helm repo list

# Search for charts
helm search repo nginx
helm search repo postgres

# Search Helm Hub
helm search hub wordpress

Working with Helm Charts

Installing a Chart

# Install chart with default values
helm install my-nginx bitnami/nginx

# Install with custom release name
helm install my-release bitnami/nginx

# Install in specific namespace
helm install my-nginx bitnami/nginx --namespace web --create-namespace

# Install with custom values
helm install my-nginx bitnami/nginx \
  --set service.type=LoadBalancer \
  --set replicaCount=3

# Install with values file
helm install my-nginx bitnami/nginx -f custom-values.yaml

# Dry run (template only, don't install)
helm install my-nginx bitnami/nginx --dry-run --debug

# Generate manifests without installing
helm template my-nginx bitnami/nginx > nginx-manifests.yaml

Listing Releases

# List releases in current namespace
helm list

# List across all namespaces
helm list --all-namespaces
helm list -A

# List uninstalled releases
helm list --uninstalled

# List all (including failed)
helm list --all

Viewing Release Info

# Get release status
helm status my-nginx

# Get release history
helm history my-nginx

# Get values used in release
helm get values my-nginx

# Get all release information
helm get all my-nginx

# Get manifest (actual YAML deployed)
helm get manifest my-nginx

Upgrading Releases

# Upgrade with new values
helm upgrade my-nginx bitnami/nginx -f new-values.yaml

# Upgrade and install if not exists (useful for CI/CD)
helm upgrade --install my-nginx bitnami/nginx -f values.yaml

# Upgrade with individual value changes
helm upgrade my-nginx bitnami/nginx \
  --set replicaCount=5 \
  --set resources.requests.cpu=200m

# Force upgrade (recreate resources)
helm upgrade my-nginx bitnami/nginx --force

# Wait for upgrade to complete
helm upgrade my-nginx bitnami/nginx --wait --timeout 5m

# Atomic upgrade (rollback on failure)
helm upgrade my-nginx bitnami/nginx --atomic

Rolling Back

# Rollback to previous version
helm rollback my-nginx

# Rollback to specific revision
helm rollback my-nginx 2

# Dry run rollback
helm rollback my-nginx 2 --dry-run

Uninstalling

# Uninstall release
helm uninstall my-nginx

# Uninstall and keep history
helm uninstall my-nginx --keep-history

# Uninstall from specific namespace
helm uninstall my-nginx --namespace web

Creating Custom Charts

Chart Structure

# Create new chart
helm create myapp

# Chart directory structure:
myapp/
├── Chart.yaml          # Chart metadata
├── values.yaml         # Default configuration values
├── charts/             # Dependencies
├── templates/          # Template files
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   ├── _helpers.tpl   # Template helpers
│   ├── NOTES.txt      # Post-installation notes
│   └── tests/         # Test hooks
└── .helmignore        # Files to ignore

Chart.yaml

apiVersion: v2
name: myapp
description: A Helm chart for my application
type: application  # or 'library' for shared templates
version: 1.0.0     # Chart version (SemVer)
appVersion: "2.5.1"  # Application version

maintainers:
- name: Your Name
  email: [email protected]
  url: https://example.com

home: https://github.com/example/myapp
sources:
- https://github.com/example/myapp

keywords:
- webapp
- microservice

dependencies:
- name: postgresql
  version: 11.x.x
  repository: https://charts.bitnami.com/bitnami
  condition: postgresql.enabled
- name: redis
  version: 16.x.x
  repository: https://charts.bitnami.com/bitnami
  condition: redis.enabled

values.yaml

# Default values for myapp
replicaCount: 2

image:
  repository: myapp
  pullPolicy: IfNotPresent
  tag: ""  # Defaults to Chart.appVersion

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

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

podAnnotations: {}

podSecurityContext:
  runAsNonRoot: true
  runAsUser: 1000
  fsGroup: 2000

securityContext:
  capabilities:
    drop:
    - ALL
  readOnlyRootFilesystem: true
  allowPrivilegeEscalation: false

service:
  type: ClusterIP
  port: 80
  targetPort: 8080

ingress:
  enabled: false
  className: nginx
  annotations: {}
  hosts:
  - host: myapp.example.com
    paths:
    - path: /
      pathType: Prefix
  tls: []

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

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

nodeSelector: {}

tolerations: []

affinity: {}

# Application-specific configuration
config:
  logLevel: info
  database:
    host: postgres
    port: 5432
  cache:
    enabled: true
    ttl: 3600

# Dependencies
postgresql:
  enabled: true
  auth:
    username: myapp
    database: myapp
  primary:
    persistence:
      size: 10Gi

redis:
  enabled: true
  architecture: standalone
  auth:
    enabled: false

Helm Templating

Template Syntax

Helm uses Go templates with additional functions:

# templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "myapp.fullname" . }}
  labels:
    {{- include "myapp.labels" . | nindent 4 }}
spec:
  {{- if not .Values.autoscaling.enabled }}
  replicas: {{ .Values.replicaCount }}
  {{- end }}
  selector:
    matchLabels:
      {{- include "myapp.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      annotations:
        checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
        {{- with .Values.podAnnotations }}
        {{- toYaml . | nindent 8 }}
        {{- end }}
      labels:
        {{- include "myapp.selectorLabels" . | nindent 8 }}
    spec:
      {{- with .Values.imagePullSecrets }}
      imagePullSecrets:
        {{- toYaml . | nindent 8 }}
      {{- end }}
      serviceAccountName: {{ include "myapp.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: {{ .Values.service.targetPort }}
          protocol: TCP
        env:
        - name: LOG_LEVEL
          value: {{ .Values.config.logLevel | quote }}
        - name: DATABASE_HOST
          value: {{ .Values.config.database.host | quote }}
        - name: DATABASE_PORT
          value: {{ .Values.config.database.port | quote }}
        {{- if .Values.config.cache.enabled }}
        - name: CACHE_ENABLED
          value: "true"
        - name: CACHE_TTL
          value: {{ .Values.config.cache.ttl | quote }}
        {{- end }}
        livenessProbe:
          httpGet:
            path: /healthz
            port: http
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /ready
            port: http
          initialDelaySeconds: 5
          periodSeconds: 5
        resources:
          {{- toYaml .Values.resources | nindent 12 }}
      {{- with .Values.nodeSelector }}
      nodeSelector:
        {{- toYaml . | nindent 8 }}
      {{- end }}
      {{- with .Values.affinity }}
      affinity:
        {{- toYaml . | nindent 8 }}
      {{- end }}
      {{- with .Values.tolerations }}
      tolerations:
        {{- toYaml . | nindent 8 }}
      {{- end }}

Template Functions

# Common functions
{{ .Values.name | upper }}           # Uppercase
{{ .Values.name | lower }}           # Lowercase
{{ .Values.name | quote }}           # Add quotes
{{ .Values.name | default "default" }} # Default value
{{ .Values.list | toYaml }}          # Convert to YAML
{{ .Values.dict | toJson }}          # Convert to JSON
{{ .Values.name | b64enc }}          # Base64 encode
{{ .Values.number | int }}           # Convert to integer

# String manipulation
{{ printf "%s-%s" .Release.Name .Chart.Name }}
{{ .Values.name | trunc 63 | trimSuffix "-" }}

# Conditionals
{{- if .Values.ingress.enabled }}
kind: Ingress
{{- else }}
# Ingress disabled
{{- end }}

# Loops
{{- range .Values.hosts }}
- host: {{ . }}
{{- end }}

# With (change scope)
{{- with .Values.service }}
type: {{ .type }}
port: {{ .port }}
{{- end }}

_helpers.tpl

{{/*
Expand the name of the chart.
*/}}
{{- define "myapp.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
{{- end }}

{{/*
Create a default fully qualified app name.
*/}}
{{- define "myapp.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 }}

{{/*
Common labels
*/}}
{{- define "myapp.labels" -}}
helm.sh/chart: {{ include "myapp.chart" . }}
{{ include "myapp.selectorLabels" . }}
{{- if .Chart.AppVersion }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
{{- end }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

{{/*
Selector labels
*/}}
{{- define "myapp.selectorLabels" -}}
app.kubernetes.io/name: {{ include "myapp.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

{{/*
Create chart name and version as used by the chart label.
*/}}
{{- define "myapp.chart" -}}
{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
{{- end }}

{{/*
Create the name of the service account to use
*/}}
{{- define "myapp.serviceAccountName" -}}
{{- if .Values.serviceAccount.create }}
{{- default (include "myapp.fullname" .) .Values.serviceAccount.name }}
{{- else }}
{{- default "default" .Values.serviceAccount.name }}
{{- end }}
{{- end }}

Managing Releases

Release Lifecycle

# 1. Install
helm install myapp ./myapp -f values-dev.yaml

# 2. Check status
helm status myapp

# 3. Upgrade
helm upgrade myapp ./myapp -f values-dev.yaml

# 4. View history
helm history myapp
# REVISION  UPDATED                   STATUS      CHART         DESCRIPTION
# 1         Mon Dec 30 10:00:00 2025  superseded  myapp-1.0.0   Install complete
# 2         Mon Dec 30 11:00:00 2025  deployed    myapp-1.0.1   Upgrade complete

# 5. Rollback if needed
helm rollback myapp 1

# 6. Uninstall
helm uninstall myapp

Atomic Deployments

# Automatically rollback on failure
helm upgrade myapp ./myapp --atomic --timeout 5m

# If any pod fails to start within 5m, automatic rollback occurs

Testing Releases

# Run chart tests
helm test myapp

# Chart test example (templates/tests/test-connection.yaml)
apiVersion: v1
kind: Pod
metadata:
  name: "{{ include "myapp.fullname" . }}-test-connection"
  annotations:
    "helm.sh/hook": test
spec:
  containers:
  - name: wget
    image: busybox
    command: ['wget']
    args: ['{{ include "myapp.fullname" . }}:{{ .Values.service.port }}']
  restartPolicy: Never

Values and Configuration

Environment-Specific Values

# values-dev.yaml
replicaCount: 1
resources:
  limits:
    cpu: 200m
    memory: 256Mi
ingress:
  enabled: true
  hosts:
  - host: myapp-dev.example.com

# values-staging.yaml
replicaCount: 2
resources:
  limits:
    cpu: 500m
    memory: 512Mi
ingress:
  enabled: true
  hosts:
  - host: myapp-staging.example.com

# values-prod.yaml
replicaCount: 5
resources:
  limits:
    cpu: 1000m
    memory: 1Gi
autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
ingress:
  enabled: true
  hosts:
  - host: myapp.example.com
  tls:
  - secretName: myapp-tls
    hosts:
    - myapp.example.com

Installing per environment:

# Development
helm install myapp ./myapp -f values-dev.yaml -n development

# Staging
helm install myapp ./myapp -f values-staging.yaml -n staging

# Production
helm install myapp ./myapp -f values-prod.yaml -n production

Values Priority

Values are merged in this order (highest priority last):

1. Chart's values.yaml

2. Parent chart's values.yaml (if subchart)

3. Values file specified with -f (can be multiple)

4. Individual values set with --set

# Multiple values files (later files override earlier)
helm install myapp ./myapp \
  -f values.yaml \
  -f values-prod.yaml \
  -f values-override.yaml

# --set has highest priority
helm install myapp ./myapp \
  -f values-prod.yaml \
  --set replicaCount=10

Complex Values with --set

# Simple values
--set name=value

# Nested values
--set server.port=8080

# Arrays
--set servers[0].port=8080,servers[0].host=server1

# Lists
--set "hosts={host1,host2,host3}"

# Null values
--set service.type=null

# Multiple values
--set key1=val1 --set key2=val2

Chart Repositories

Creating a Repository

# 1. Package charts
helm package myapp/
# Successfully packaged chart and saved it to: myapp-1.0.0.tgz

# 2. Create index
helm repo index . --url https://example.com/charts

# 3. Upload to web server or object storage
# index.yaml and .tgz files

# Repository structure:
charts/
├── index.yaml
├── myapp-1.0.0.tgz
├── myapp-1.0.1.tgz
└── otherapp-2.0.0.tgz

Using GitHub Pages

# 1. Create gh-pages branch
git checkout --orphan gh-pages

# 2. Package and index charts
helm package charts/myapp -d ./
helm repo index . --url https://username.github.io/charts

# 3. Commit and push
git add index.yaml *.tgz
git commit -m "Publish charts"
git push origin gh-pages

# 4. Add repository
helm repo add my-charts https://username.github.io/charts
helm repo update
helm install myapp my-charts/myapp

OCI Registry Support

Helm 3.8+ supports OCI registries:

# Login to registry
echo $GITHUB_TOKEN | helm registry login ghcr.io -u USERNAME --password-stdin

# Push chart
helm push myapp-1.0.0.tgz oci://ghcr.io/username/charts

# Install from OCI
helm install myapp oci://ghcr.io/username/charts/myapp --version 1.0.0

# List versions
helm show all oci://ghcr.io/username/charts/myapp

Helm Hooks and Lifecycle

Available Hooks

• pre-install: Before any resources are created

• post-install: After all resources are created

• pre-delete: Before any resources are deleted

• post-delete: After all resources are deleted

• pre-upgrade: Before upgrade

• post-upgrade: After upgrade

• pre-rollback: Before rollback

• post-rollback: After rollback

• test: When helm test is run

Hook Example

# Database migration job
apiVersion: batch/v1
kind: Job
metadata:
  name: {{ include "myapp.fullname" . }}-migration
  annotations:
    "helm.sh/hook": pre-upgrade,pre-install
    "helm.sh/hook-weight": "-5"
    "helm.sh/hook-delete-policy": before-hook-creation
spec:
  template:
    metadata:
      name: {{ include "myapp.fullname" . }}-migration
    spec:
      restartPolicy: Never
      containers:
      - name: migration
        image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
        command: ["/app/migrate"]
        env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: {{ include "myapp.fullname" . }}
              key: database-url

Hook Deletion Policies

• before-hook-creation: Delete previous hook before new one

• hook-succeeded: Delete after successful execution

• hook-failed: Delete if hook fails

Advanced Patterns

Subcharts

# Chart.yaml dependencies
dependencies:
- name: postgresql
  version: "11.x.x"
  repository: https://charts.bitnami.com/bitnami
- name: redis
  version: "16.x.x"
  repository: https://charts.bitnami.com/bitnami

# Update dependencies
helm dependency update

# Override subchart values
# values.yaml
postgresql:
  primary:
    persistence:
      size: 20Gi
  auth:
    password: mypassword

redis:
  master:
    persistence:
      size: 5Gi

Library Charts

# Chart.yaml for library
apiVersion: v2
name: common-library
type: library  # Not deployable

# Use in application chart
dependencies:
- name: common-library
  version: 1.0.0
  repository: https://example.com/charts

# Use library templates
{{ include "common-library.deployment" . }}

Named Templates for Reuse

# _helpers.tpl
{{- define "myapp.deployment" -}}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "myapp.fullname" . }}
spec:
  replicas: {{ .Values.replicaCount }}
  # ... rest of deployment
{{- end -}}

# Use in deployment.yaml
{{ include "myapp.deployment" . }}

Troubleshooting Helm Issues

Common Issues

1. Release not found:

# Check all namespaces
helm list -A

# Specify correct namespace
helm list -n production

2. Values not applying:

# Debug rendered templates
helm install myapp ./myapp --dry-run --debug

# Check actual values used
helm get values myapp

3. Template errors:

# Lint chart
helm lint ./myapp

# Template without installing
helm template myapp ./myapp

# Debug specific template
helm template myapp ./myapp -s templates/deployment.yaml

4. Upgrade failures:

# Check release history
helm history myapp

# Rollback
helm rollback myapp

# Force upgrade
helm upgrade myapp ./myapp --force

5. Hook failures:

# Check hook pods
kubectl get pods -l 'helm.sh/hook'

# View hook logs
kubectl logs job/myapp-pre-upgrade-hook

# Clean up failed hooks manually
kubectl delete job myapp-pre-upgrade-hook

Best Practices

1. Version Everything

# Chart.yaml
version: 1.2.3  # Chart version
appVersion: "2.5.1"  # Application version

# Use semantic versioning
# MAJOR.MINOR.PATCH

2. Document Charts

# README.md in chart directory
## Parameters

| Parameter | Description | Default |
|-----------|-------------|---------|
| `replicaCount` | Number of replicas | `2` |
| `image.repository` | Image repository | `myapp` |

3. Use Linting

# Lint before packaging
helm lint ./myapp

# Fix common issues
# - Indentation
# - Missing required fields
# - Invalid templates

4. Test Charts

# templates/tests/
# Create comprehensive tests
- Connection tests
- API health checks
- Database connectivity

5. Security

# Don't commit secrets to values.yaml
# Use separate secrets file (not in git)
helm install myapp ./myapp -f values.yaml -f secrets.yaml

# Or use external secrets
# - Sealed Secrets
# - External Secrets Operator

What I Learned

Key lessons from years of working with Helm:

1. Start Simple: Don't over-engineer charts initially. Start with basic templates and add complexity as needed.

2. Values Schema: Well-designed values.yaml is crucial. Think carefully about structure and defaults.

3. Version Strategy: Maintain separate chart versions from app versions. Chart version tracks template changes.

4. Testing Matters: Always test charts in non-production first. Use --dry-run and helm template extensively.

5. Documentation: Good documentation is essential. Future you (and your team) will thank you.

6. Upgrade Strategy: Use --atomic for production upgrades. Automatic rollback saves you from many disasters.

7. Dependencies: Pin dependency versions. Floating versions cause unexpected breaks.

8. Secrets Management: Never store secrets in charts or values files. Use external secret management.

9. Lint Always: Make helm lint part of CI pipeline. Catch errors before deployment.

10. Keep Charts Simple: Resist the urge to make charts too configurable. Sometimes separate charts are better than one complex chart.

Helm transformed how I deploy to Kubernetes. It eliminated hundreds of duplicate YAML files, made environment management trivial, and enabled proper versioning and rollback. The investment in learning Helm pays back quickly in reduced deployment complexity and increased reliability.