Helm: A Practical Reference Guide

Luke Hebert

August 8, 2025 - 6 minutes read - 1241 words

A quick-reference guide covering Helm repository management, chart installation and upgrades, release management, chart development, debugging, and common deployment workflows. Use this as a day-to-day cheat sheet for working with Helm in Kubernetes environments.

Installation & Setup

Initialize Helm

Add Official Repositories:

helm repo add stable https://charts.helm.sh/stable
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

Repository Management

Basic Repository Commands

List Repositories:

helm repo list

Add Repository:

helm repo add <name> <url>
helm repo add nginx https://kubernetes.github.io/ingress-nginx

Update Repositories:

helm repo update

Remove Repository:

helm repo remove <name>

Search Commands

Search in Repositories:

helm search repo nginx
helm search repo nginx --versions   # Show all versions

Search Helm Hub:

helm search hub wordpress

Popular Repositories

helm repo add stable https://charts.helm.sh/stable
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo add nginx-stable https://helm.nginx.com/stable
helm repo add jetstack https://charts.jetstack.io
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo add grafana https://grafana.github.io/helm-charts

Chart Management

Install Charts

Basic Installation:

helm install <release-name> <chart>
helm install my-nginx bitnami/nginx

Install with Custom Values:

helm install my-app ./mychart -f values.yaml
helm install my-app bitnami/wordpress --set wordpressUsername=admin

Install in Specific Namespace:

helm install my-app bitnami/nginx -n production --create-namespace

Install and Wait:

helm install my-app bitnami/nginx --wait --timeout=300s

Dry Run (Test):

helm install my-app bitnami/nginx --dry-run --debug

Upgrade Releases

Basic Upgrade:

helm upgrade <release-name> <chart>
helm upgrade my-nginx bitnami/nginx

Upgrade with New Values:

helm upgrade my-app ./mychart -f new-values.yaml
helm upgrade my-app bitnami/nginx --set replicaCount=3

Upgrade Options:

helm upgrade my-app bitnami/nginx --reuse-values   # Keep existing values
helm upgrade my-app bitnami/nginx --force           # Force upgrade
helm upgrade my-app bitnami/nginx --reset-values    # Reset to defaults

Install or Upgrade

helm upgrade --install my-app bitnami/nginx
helm upgrade --install my-app ./mychart -f values.yaml

Uninstall Releases

Basic Uninstall:

helm uninstall <release-name>
helm uninstall my-nginx

Uninstall from Namespace:

helm uninstall my-app -n production

Keep History (for Rollback):

helm uninstall my-app --keep-history

Release Management

List Releases

All Releases:

helm list

Specific Namespace:

helm list -n production

All Namespaces:

helm list --all-namespaces

Include Uninstalled:

helm list --uninstalled
helm list --all   # Including failed

Release Information

Status:

helm status <release-name>
helm status my-nginx

History:

helm history <release-name>
helm history my-nginx

Values:

helm get values <release-name>
helm get values my-nginx --all   # Include defaults

Manifest:

helm get manifest <release-name>

Notes:

helm get notes <release-name>

All Information:

helm get all <release-name>

Rollback Releases

Rollback to Previous:

helm rollback <release-name>
helm rollback my-nginx

Rollback to Specific Version:

helm rollback <release-name> <revision>
helm rollback my-nginx 2

Rollback with Wait:

helm rollback my-nginx --wait

Chart Development

Create New Chart

helm create <chart-name>
helm create my-application

Chart Structure Created:

my-application/
├── Chart.yaml        # Chart metadata
├── values.yaml       # Default values
├── templates/        # Template files
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   └── _helpers.tpl
└── charts/           # Dependencies

Chart Validation

Lint Chart:

helm lint ./mychart
helm lint ./mychart --strict

Template Rendering:

helm template my-app ./mychart
helm template my-app ./mychart -f values.yaml

Render Specific Files:

helm template my-app ./mychart -s templates/deployment.yaml

Debug Rendering:

helm template my-app ./mychart --debug

Chart Testing

helm test <release-name>
helm test my-nginx --logs
helm test my-nginx --timeout=300s

Package Charts

Basic Package:

helm package ./mychart

With Version:

helm package ./mychart --version 1.2.3

With App Version:

helm package ./mychart --app-version 2.1.0

Chart Dependencies

Update Dependencies:

helm dependency update ./mychart

List Dependencies:

helm dependency list ./mychart

Build Dependencies:

helm dependency build ./mychart

Values and Configuration

Working with Values Files

Custom Values File:

helm install my-app ./mychart -f custom-values.yaml

Multiple Values Files:

helm install my-app ./mychart -f values1.yaml -f values2.yaml

Set Individual Values:

helm install my-app ./mychart --set key1=value1,key2=value2

Set Complex Values:

helm install my-app ./mychart --set image.tag=1.2.3 --set replicaCount=3

Set Array Values:

helm install my-app ./mychart --set servers[0]=primary --set servers[1]=secondary

Set from File:

helm install my-app ./mychart --set-file config=config.yaml

Set String Values:

helm install my-app ./mychart --set-string nodePort=3000

Example Values File:

# values.yaml
replicaCount: 2
image:
  repository: nginx
  tag: 1.21.0
  pullPolicy: IfNotPresent
service:
  type: ClusterIP
  port: 80
ingress:
  enabled: false
  annotations: {}
  hosts:
    - host: example.com
      paths: ["/"]
resources:
  limits:
    cpu: 100m
    memory: 128Mi
  requests:
    cpu: 100m
    memory: 128Mi
nodeSelector: {}
tolerations: []
affinity: {}

Debugging and Troubleshooting

Debug Commands

Dry Run Installation:

helm install my-app ./mychart --dry-run --debug

Template with Debug:

helm template my-app ./mychart --debug

Get Manifest:

helm get manifest my-app

Check Status:

helm status my-app

Installation Logs:

helm install my-app ./mychart --debug --wait

Lint for Issues:

helm lint ./mychart --strict

Common Debug Flags

Flag	Description
`--dry-run`	Simulate installation
`--debug`	Enable verbose output
`--wait`	Wait for resources to be ready
`--timeout 300s`	Set timeout
`--atomic`	Roll back on failure
`--cleanup-on-fail`	Delete resources on failure

Advanced Usage

Hooks

Available Hook Types:

pre-install, post-install
pre-delete, post-delete
pre-upgrade, post-upgrade
pre-rollback, post-rollback
test

Hook Example:

metadata:
  annotations:
    "helm.sh/hook": pre-install
    "helm.sh/hook-weight": "-5"
    "helm.sh/hook-delete-policy": before-hook-creation

Subchart Management

Chart.yaml Dependencies:

dependencies:
  - name: postgresql
    version: 11.1.3
    repository: https://charts.bitnami.com/bitnami
    condition: postgresql.enabled

Override Subchart Values:

postgresql:
  enabled: true
  auth:
    database: myapp
    username: myuser

Environment Management

Namespace Management

Install in Namespace:

helm install my-app ./mychart -n production

Create Namespace:

helm install my-app ./mychart -n production --create-namespace

List by Namespace:

helm list -n production
helm list --all-namespaces

Multiple Environments

Environment Files:

values-dev.yaml
values-staging.yaml
values-prod.yaml

Deploy to Environments:

helm install my-app-dev ./mychart -f values-dev.yaml -n development
helm install my-app-staging ./mychart -f values-staging.yaml -n staging
helm install my-app-prod ./mychart -f values-prod.yaml -n production

Security

RBAC Setup

kubectl create serviceaccount helm-user -n kube-system
kubectl create clusterrolebinding helm-user --clusterrole=cluster-admin --serviceaccount=kube-system:helm-user
helm install my-app ./mychart --service-account helm-user

Secrets Management

helm install my-app ./mychart --set-file secret.cert=./cert.pem

Common Workflows

Development Workflow

1. Create Chart:

helm create my-app

2. Develop and Test:

helm lint ./my-app
helm template test-release ./my-app --debug

3. Install for Testing:

helm install test-release ./my-app --dry-run
helm install test-release ./my-app -f values-dev.yaml

4. Iterate:

helm upgrade test-release ./my-app -f values-dev.yaml

5. Package and Deploy:

helm package ./my-app
helm install prod-release ./my-app-1.0.0.tgz -f values-prod.yaml

Production Deployment

1. Deploy:

helm upgrade --install my-app ./mychart \
  -f values-prod.yaml \
  -n production \
  --create-namespace \
  --wait \
  --timeout=300s

2. Verify:

helm status my-app -n production
kubectl get pods -n production

3. Monitor:

helm history my-app -n production

Useful Aliases

Add to ~/.bashrc or ~/.zshrc:

alias h='helm'
alias hl='helm list'
alias hi='helm install'
alias hu='helm upgrade'
alias hun='helm uninstall'
alias hs='helm status'
alias hh='helm history'
alias hr='helm rollback'
alias ht='helm template'

Deployment Patterns

Blue-Green Deployment

# Deploy new version
helm install my-app-green ./mychart -f values.yaml --set version=green

# Switch traffic
helm upgrade my-app-green ./mychart --set activeVersion=green

# Remove old version
helm uninstall my-app-blue

Canary Deployment

# Install canary with reduced replicas
helm install my-app-canary ./mychart --set replicaCount=1 --set version=canary

# Gradually increase traffic
helm upgrade my-app-canary ./mychart --set replicaCount=2

Quick Reference

Most Used Commands

Command	Purpose
`helm list`	List all releases
`helm install <name> <chart>`	Install chart
`helm upgrade <name> <chart>`	Upgrade release
`helm uninstall <name>`	Remove release
`helm status <name>`	Check release status
`helm rollback <name>`	Rollback release
`helm history <name>`	View release history

Quick Troubleshooting

Check status: helm status <release>
View logs: kubectl logs -l app=<app-name>
Check events: kubectl get events --sort-by=.metadata.creationTimestamp
Debug template: helm template <name> <chart> --debug
Lint chart: helm lint <chart-path>