Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 38 ยท Getting Started

Your First Helm Release: Install, Inspect and Uninstall

Add a chart repository, search for a chart, customize it, install your first release, inspect it with status and get, then uninstall it cleanly.

Time to use Helm for real. In this lesson you will walk the whole loop with a public chart: find it, look at what it can be configured with, install it as a release, check that it works and remove it. The commands are read-only on this page, but each one is explained, and the stand-ins reproduce the logic so you know what happens behind them.

A chart repository is a web server that publishes an index.yaml listing its charts. You add it once and give it a short local name:

Terminal
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update
helm search repo bitnami/nginx
TEXT
NAME                CHART VERSION   APP VERSION   DESCRIPTION
bitnami/nginx       18.2.4          1.27.3        NGINX Open Source is a web server...

Two version numbers appear on purpose. The chart version is the version of the packaging (templates and defaults). The app version is the version of the software inside. They change independently: a chart can gain a new template without the app changing. Read more in Chart Structure and Chart.yaml.

helm search hub nginx searches Artifact Hub, a public directory of charts from many publishers, instead of your configured repositories. Treat any public chart like any third-party software: check who publishes it and how recently it was updated.

Step 2: read what you can configure

Before installing, look at the chart's default values, which are the complete list of knobs:

Terminal
helm show values bitnami/nginx | head -40
helm show chart bitnami/nginx
helm show readme bitnami/nginx

show values is the single most useful command for learning a chart. Save it to a file to use as a starting point for your own overrides:

Terminal
helm show values bitnami/nginx > my-values.yaml

Step 3: install

Terminal
helm install web bitnami/nginx --namespace demo --create-namespace --set replicaCount=2

Read the arguments from left to right: web is the release name you choose, bitnami/nginx is the chart, --namespace demo is where it goes, --create-namespace creates that namespace if missing, and --set replicaCount=2 overrides one default value.

Helm prints a summary:

TEXT
NAME: web
LAST DEPLOYED: Tue Mar 11 10:21:08 2025
NAMESPACE: demo
STATUS: deployed
REVISION: 1
NOTES:
  ...instructions from the chart author...

The NOTES come from a template in the chart (templates/NOTES.txt). Good charts use it to tell you how to reach the application. Read it, and run helm get notes web -n demo to see it again later.

Here is what the command does, in order:

sequenceDiagram
  participant You
  participant Helm
  participant API as Kubernetes API
  You->>Helm: helm install web bitnami/nginx
  Helm->>Helm: download chart, merge values
  Helm->>Helm: render templates to manifests
  Helm->>API: create Deployment, Service, ...
  Helm->>API: store release Secret (revision 1)
  Helm-->>You: summary and NOTES

The release record is stored last, after the resources were submitted.

Step 4: inspect the release

Terminal
helm list -n demo
helm status web -n demo
kubectl get all -n demo
helm get values web -n demo
helm get manifest web -n demo
Command Shows
helm list Releases and their current revision and status
helm status Status, last deployed time and notes
helm get values The values you supplied (--all adds defaults)
helm get manifest The exact YAML Helm applied

kubectl get all shows what Kubernetes made of it: a Deployment, ReplicaSet, Pods and a Service. Helm adds labels such as app.kubernetes.io/managed-by: Helm and annotations meta.helm.sh/release-name, so you can tell which objects belong to a release.

A stand-in for the install loop

The program below mimics the bookkeeping: a "cluster" that remembers releases per namespace, refusing duplicate names, and an uninstall that removes everything the release created.

Python Stand-in: install, list and uninstall

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The duplicate-name failure is a real Helm behavior; helm upgrade --install (next chapter) avoids it by installing when the release is new and upgrading when it exists.

Step 5: upgrade or uninstall

Change a value and apply it to the running release:

Terminal
helm upgrade web bitnami/nginx -n demo --set replicaCount=3
helm history web -n demo

When you are done, remove the release:

Terminal
helm uninstall web -n demo

Uninstall deletes every Kubernetes object that Helm created for the release and removes its history. Things Helm did not create are untouched: the namespace made by --create-namespace, and PersistentVolumeClaims created by StatefulSets (Kubernetes keeps those on purpose). Clean them up manually if you want a fully empty namespace.

Use --dry-run while learning. helm install web bitnami/nginx --dry-run --debug renders everything and prints the manifests without touching the cluster, so you can see what would be created.

Common first-time problems

  1. Error: INSTALLATION FAILED: cannot re-use a name that is still in use: the release name already exists in that namespace. Choose another name, upgrade, or uninstall.
  2. Kubernetes cluster unreachable: kubeconfig or network problem; check kubectl cluster-info.
  3. Pods stay Pending or ImagePullBackOff: the chart installed fine but the cluster cannot schedule or pull. Debug with kubectl describe pod; see Troubleshooting.
  4. A value seems to be ignored: the key name or nesting is wrong (replicas versus replicaCount). helm get values shows what Helm received, and helm show values shows the keys the chart understands.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which command lists every configurable value a chart supports, with defaults?

    helm show values prints the chart's values.yaml; helm get values shows what a release received.
  2. 2. In helm install web bitnami/nginx, what is web?

    The first argument is the release name; the second is the chart.
  3. 3. What does helm uninstall NOT remove by default?

    Helm removes only objects of the release; the namespace and PVCs kept by StatefulSets stay.
  4. 4. What does --dry-run do?

    --dry-run renders (and with --debug prints) the result without applying it.
  5. 5. What is the difference between chart version and app version?

    They change independently; a template fix bumps the chart version without changing the app.

Summary

  • helm repo add, helm search repo and helm show values find and explain a chart.
  • helm install NAME CHART creates a release; -n, --create-namespace and --set are the everyday flags.
  • helm list, status, get values and get manifest show what was deployed.
  • helm uninstall removes the release's objects and history but not namespaces or retained volumes.
  • Use --dry-run --debug to preview without risk.

Next: Chart Structure and Chart.yaml