Helm Basics

Helm is the package manager for Kubernetes. This page walks through charts, releases, values.yaml, and the day-to-day install and upgrade workflow.

Prerequisites

• Helm 3 installed (helm version should report v3.x).
• A working kubeconfig pointing at a Kubernetes 1.36.2 cluster (kubectl get nodes succeeds).
• Basic familiarity with Deployments and Services.

Quick install on macOS or Linux:

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

Basic Examples

1. Create a starter chart

Scaffold a working chart you can inspect and edit.

helm create myapp

• Generates Chart.yaml, values.yaml, templates/, and a charts/ directory for dependencies.
• templates/ holds a Deployment, Service, ServiceAccount, and an optional Ingress.
• _helpers.tpl defines reusable naming templates.
• The scaffold installs as-is, giving you a known-good baseline.

2. Inspect chart metadata

Chart.yaml describes the chart itself.

# Chart.yaml
apiVersion: v2
name: myapp
description: A Helm chart for my app
type: application
version: 0.1.0        # chart version (semver)
appVersion: "1.8.3"   # version of the app it deploys

• version is the chart's own semver, bumped when the chart changes.
• appVersion tracks the application image version and is informational.
• apiVersion: v2 marks a Helm 3 chart.
• type: application (vs library) means it renders installable objects.

3. Render templates locally

See the exact YAML Helm will send to the cluster - no cluster needed.

helm template myapp ./myapp

• Renders templates with default values.yaml and prints manifests.
• Add -f prod-values.yaml to preview a specific environment.
• Great for CI checks and code review.
• Does not contact the API server or create a release.

4. Install a release

A release is a named, tracked installation of a chart.

helm install web ./myapp --namespace demo --create-namespace

• web is the release name; one chart can be installed many times under different names.
• Helm stores release state as a Secret in the target namespace.
• --create-namespace makes the namespace if it does not exist.
• helm list -n demo shows the release and its revision.

5. Override values at install

Change behavior without editing the chart.

helm install web ./myapp -n demo \
  --set replicaCount=3 \
  --set image.tag=1.8.4

• --set overrides single values inline.
• -f custom-values.yaml overrides many values from a file.
• Later -f files and --set flags win over earlier ones and the chart defaults.
• Keep environment values in files under version control rather than long --set chains.

6. Understand values precedence

values.yaml is the default configuration surface of a chart.

# values.yaml
replicaCount: 1
image:
  repository: registry.example.com/myapp
  tag: "1.8.3"
resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    memory: 256Mi

• Templates read these as .Values.replicaCount, .Values.image.tag, and so on.
• User-supplied files and --set merge over these defaults.
• Setting resource requests and limits here keeps every install schedulable and bounded.
• Document each value so consumers know what is tunable.

7. Upgrade a release

helm upgrade applies a new chart version or new values to an existing release.

helm upgrade web ./myapp -n demo -f prod-values.yaml

• Creates a new revision; helm history web -n demo lists them.
• Add --install to install if the release does not yet exist (idempotent CI deploys).
• Add --atomic to auto-rollback on failure.
• Add --wait to block until resources report ready.

Intermediate Examples

8. Roll back a bad release

Every upgrade is versioned, so recovery is one command.

helm history web -n demo
helm rollback web 1 -n demo

• helm history shows each revision, its status, and chart version.
• helm rollback web 1 restores the state captured at revision 1.
• Rollback itself creates a new revision rather than deleting history.
• Combine with --atomic on upgrades so failed changes never linger.

9. Manage chart dependencies

Charts can depend on other charts (subcharts).

# Chart.yaml
dependencies:
  - name: postgresql
    version: "15.5.x"
    repository: https://charts.example.com
    condition: postgresql.enabled

helm dependency update ./myapp

• dependencies pins each subchart by name, version range, and repository.
• helm dependency update fetches them into charts/ and writes Chart.lock.
• condition lets consumers disable a subchart via values.
• Commit Chart.lock so builds are reproducible.

10. Lint and package for distribution

Validate a chart, then produce a versioned artifact.

helm lint ./myapp
helm package ./myapp        # produces myapp-0.1.0.tgz

• helm lint catches template and schema problems early.
• helm package creates a versioned .tgz you can push to an OCI registry.
• helm push myapp-0.1.0.tgz oci://registry.example.com/charts publishes it.
• Consumers then run helm install web oci://registry.example.com/charts/myapp --version 0.1.0.

11. Inspect and safely remove a release

Check what a release actually deployed, then clean it up.

helm get values web -n demo          # values used for this release
helm status web -n demo              # current state and notes
helm uninstall web -n demo --keep-history

• helm get values shows the effective values, which is invaluable when debugging drift.
• helm status reports the release phase and any NOTES.txt output.
• helm uninstall removes the release and its objects; --keep-history retains the revision records.
• Prefer letting a GitOps controller own installs in shared clusters rather than uninstalling by hand.

Stack versions: This page was written for Kubernetes 1.36.2, Docker Engine 29.6.1 (BuildKit default), containerd (CRI runtime on nodes), Helm 3, Compose v2, Argo CD (latest - verify at build), and Gateway API (GA - verify controller support at build).