Helm

The package manager for Kubernetes that uses charts to define, install, and upgrade applications on clusters.

Table of Contents#

Overview
Architecture
Installation
Command Reference
Chart Structure
Creating Charts
Values and Templating
Troubleshooting
See Also
Sources

1. Overview#

Helm simplifies Kubernetes application deployment by packaging related manifests into reusable charts. A chart is a collection of files describing a set of Kubernetes resources, with configurable values that allow customization without modifying templates directly.

Key features:

Charts - versioned packages of pre-configured Kubernetes resources
Repositories - shareable collections of charts (Artifact Hub, OCI registries)
Release management - tracks each installation as a named release with full history
Rollbacks - revert to any previous release revision
Dependency management - charts can depend on other charts
Templating - Go templates with Sprig functions for dynamic manifest generation

2. Architecture#

Helm 3 is a client-only tool (Tiller was removed in Helm 3). The helm CLI communicates directly with the Kubernetes API server using your kubeconfig credentials.

Concept	Description
Chart	A package containing templates, values, and metadata
Release	A specific installation of a chart in a cluster
Revision	A versioned snapshot of a release (created on install/upgrade)
Repository	An HTTP or OCI server hosting packaged charts
Values	User-supplied configuration that overrides chart defaults

3. Installation#

3.1 Prerequisites#

A Kubernetes cluster
kubectl configured for the target cluster

3.2 Install Helm#

Linux/macOS (binary):

curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

Linux (manual):

tar -zxvf helm-v3.16.4-linux-amd64.tar.gz
sudo mv linux-amd64/helm /usr/local/bin/helm

macOS (Homebrew):

brew install helm

Windows (Chocolatey):

choco install kubernetes-helm

3.3 Verify Installation#

helm version

4. Command Reference#

4.1 Repository Management#

Command	Description
`helm repo list`	List configured repositories
`helm repo add <name> <url>`	Add a chart repository
`helm repo update`	Refresh local cache of repository indexes
`helm repo remove <name>`	Remove a repository

Example:

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

4.2 Chart Search and Inspection#

Command	Description
`helm search repo <keyword>`	Search repositories for charts matching a keyword
`helm search hub <keyword>`	Search Artifact Hub for charts
`helm show chart <repo>/<chart>`	Display chart metadata
`helm show values <repo>/<chart>`	Display default values
`helm show all <repo>/<chart>`	Display all chart information
`helm show readme <repo>/<chart>`	Display chart README

4.3 Install and Delete#

Command	Description
`helm install <release> <repo>/<chart>`	Install a chart
`helm install <release> <repo>/<chart> -f <values.yaml>`	Install with custom values file
`helm install <release> <repo>/<chart> --set <key>=<value>`	Install with inline value overrides
`helm install <release> <repo>/<chart> -n <namespace> --create-namespace`	Install into a specific namespace
`helm install <release> <repo>/<chart> --dry-run --debug`	Simulate install and show rendered manifests
`helm status <release>`	Show release status
`helm uninstall <release>`	Delete a release
`helm uninstall <release> --keep-history`	Delete but preserve release history

4.4 Upgrade and Rollback#

Command	Description
`helm upgrade <release> <repo>/<chart>`	Upgrade a release to a new chart version
`helm upgrade <release> <repo>/<chart> -f <values.yaml>`	Upgrade with new values
`helm upgrade <release> <repo>/<chart> --install`	Install if not present, upgrade if it is
`helm get values <release>`	Show user-supplied values for a release
`helm get manifest <release>`	Show rendered manifests for a release
`helm history <release>`	Show revision history
`helm rollback <release> <revision>`	Roll back to a specific revision

4.5 Chart Development#

Command	Description
`helm create <name>`	Scaffold a new chart
`helm lint <chart-path>`	Validate chart syntax and best practices
`helm template <release> <chart-path>`	Render templates locally without installing
`helm package <chart-path>`	Package chart into a `.tgz` archive
`helm dependency list <chart-path>`	List chart dependencies
`helm dependency update <chart-path>`	Download and update dependencies
`helm dependency build <chart-path>`	Rebuild the `charts/` directory from `Chart.lock`

4.6 Release Information#

Command	Description
`helm list`	List releases in the current namespace
`helm list -A`	List releases across all namespaces
`helm list --filter <regex>`	Filter releases by name pattern
`helm get all <release>`	Show all information about a release
`helm get notes <release>`	Show release notes
`helm get hooks <release>`	Show release hooks

5. Chart Structure#

<chart-name>/
  Chart.yaml          # Chart metadata (name, version, dependencies)
  Chart.lock          # Locked dependency versions
  values.yaml         # Default configuration values
  values.schema.json  # Optional: JSON schema for values validation
  charts/             # Dependency charts (packaged .tgz files)
  crds/               # Custom Resource Definitions (applied before templates)
  templates/          # Kubernetes manifest templates
    deployment.yaml
    service.yaml
    ingress.yaml
    _helpers.tpl      # Template helper functions
    NOTES.txt         # Post-install usage notes (rendered on install)
  LICENSE             # Optional: chart license
  README.md           # Optional: chart documentation

Chart.yaml Example#

apiVersion: v2
name: <chart-name>
description: <chart-description>
type: application
version: 0.1.0        # Chart version (semver)
appVersion: "1.0.0"   # Application version
dependencies:
- name: <dependency-chart>
  version: <version-range>
  repository: <repo-url>
  condition: <dependency>.enabled

6. Creating Charts#

6.1 Scaffold a New Chart#

helm create <chart-name>

This generates a working chart with a Deployment, Service, Ingress, ServiceAccount, and HPA.

6.2 Development Workflow#

# Edit templates and values
vim <chart-name>/templates/deployment.yaml
vim <chart-name>/values.yaml

# Validate
helm lint <chart-name>

# Render locally to inspect output
helm template my-release <chart-name> -f custom-values.yaml

# Test install with dry-run
helm install my-release <chart-name> --dry-run --debug

# Install for real
helm install my-release <chart-name> -f custom-values.yaml

# Package for distribution
helm package <chart-name>

7. Values and Templating#

7.1 Value Precedence (lowest to highest)#

Chart's values.yaml
Parent chart's values.yaml
-f / --values file (last file wins)
--set and --set-string flags (last flag wins)

7.2 Common Template Functions#

# Access values
{{ .Values.image.repository }}

# Default values
{{ .Values.replicas | default 1 }}

# Conditionals
{{- if .Values.ingress.enabled }}
  ...
{{- end }}

# Loops
{{- range .Values.env }}
- name: {{ .name }}
  value: {{ .value | quote }}
{{- end }}

# Include named templates
{{- include "chart.fullname" . }}

# toYaml for complex values
{{- toYaml .Values.resources | nindent 12 }}

7.3 Helper Templates (_helpers.tpl)#

{{- define "chart.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}

Troubleshooting#

Issue	Cause	Solution
`Error: INSTALLATION FAILED: cannot re-use a name that is still in use`	Release name already exists	Use `helm upgrade --install` or `helm uninstall` first
`Error: rendered manifests contain a resource that already exists`	Resources created outside Helm own the same names	Use `helm install --adopt` or delete conflicting resources
Upgrade fails, need to roll back	Bad values or broken chart version	Run `helm rollback <release> <revision>` to a known-good state
`context deadline exceeded`	Kubernetes API unreachable or slow	Check kubeconfig, cluster connectivity, and API server health
Values not applied after upgrade	Helm merges values; old values persist	Pass all values explicitly with `-f` or use `--reset-values`
CRDs not updated on upgrade	Helm does not update CRDs after initial install	Apply CRD manifests manually with `kubectl apply`
Template render error	Syntax error or nil pointer in template	Run `helm template --debug` to see the exact error location
Dependency chart not found	Repository not added or cache stale	Run `helm repo update` then `helm dependency update`