Creating Kubernetes Deployments

Helm 3 is a single binary that runs on your machine. There is nothing to install into the cluster. It authenticates with your existing kubeconfig and talks to the Kubernetes API as you.

That means whatever Helm can do, you could already do with kubectl. If your kubeconfig cannot create Deployments in a namespace, neither can Helm.

Install

macOS

brew install helm

Linux

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

On Debian or Ubuntu you can use the apt repository instead, which gets you upgrades through the package manager. Piping a script to a shell is convenient but worth reading first on a machine you care about.

Windows

choco install kubernetes-helm

winget install Helm.Helm and scoop install helm both work too.

Verify

helm version

Confirm it is v3.x. Any guide telling you to run helm init or mentioning Tiller is describing Helm 2, which is end-of-life. Helm 3 has no cluster-side component and no initialisation step.

Helm uses the same kubeconfig and current context as kubectl, so check where you are pointed before installing anything:

kubectl config current-context

Repositories

A repository is an index of charts served over HTTP. Add one, then refresh the local cache:

helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update

helm repo list
helm search repo nginx

helm repo update is the step people forget. Without it you install whatever version was current when you added the repository, which can be months old. helm search repo only ever searches your local cache.

To search everything published publicly instead, use helm search hub.

Many projects now publish to OCI registries rather than classic repositories, in which case there is no repo add at all. You reference the chart directly:

helm install my-app oci://registry-1.docker.io/bitnamicharts/nginx

Read the values before you install

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

Do this every time. Charts commonly expose a hundred or more settings, and the defaults are tuned for a demo, usually one replica, no resource limits, and persistence switched off. Installing straight from defaults is how you end up with an unlimited pod that gets evicted under memory pressure.

Also worth a look before installing something unfamiliar:

helm show chart bitnami/nginx      # metadata and dependencies
helm show readme bitnami/nginx     # the chart's own documentation
helm template my-nginx bitnami/nginx -f nginx-values.yaml | less   # rendered manifests

Install a chart

helm install my-nginx bitnami/nginx -f nginx-values.yaml

my-nginx is the release name. Your name for this installation, not the chart's name. It must be unique within the namespace.

Namespaces are worth being explicit about, because Helm does not create them for you by default:

helm install monitoring prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --create-namespace

For anything automated, prefer the idempotent form. It installs if the release is absent and upgrades if it exists, so the same command works on first run and every run after:

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

Inspect what is installed

helm list

helm list is namespace-scoped. A release you cannot find is usually in another namespace:

helm list -A

helm status my-nginx          # status plus the chart's post-install notes
helm get values my-nginx      # the values you supplied
helm get manifest my-nginx    # exactly what was applied
helm history my-nginx         # every revision

helm get values my-nginx --all shows the merged result of your overrides and the chart defaults, which answers "why is this setting not what I expected" faster than anything else.

Upgrade and roll back

helm upgrade my-nginx bitnami/nginx -f nginx-values.yaml --atomic --timeout 5m

--atomic makes the upgrade all-or-nothing, if the new resources do not become ready within the timeout, Helm reverts the release rather than leaving it half-applied. Use it every time.

helm history my-nginx
helm rollback my-nginx 1

Uninstall

helm uninstall my-nginx

This removes the resources Helm created and the release history. Two things it does not remove:

• PersistentVolumeClaims, in most charts. Deliberately, so data survives. They keep costing money until you delete them.
• CRDs installed from the chart's crds/ directory, because removing them would delete every custom resource of that type in the cluster.

# Check for leftovers
kubectl get pvc -n <namespace>

Use --keep-history if you want the release history retained for reference after removal.

Quick reference

Key takeaways

• Helm 3 is a local binary. Nothing is installed into the cluster; it uses your kubeconfig and your permissions.
• helm init and Tiller are Helm 2. If a guide mentions them, it is out of date.
• Run helm repo update or you will install a stale chart version from your local cache.
• Always helm show values first. Chart defaults are demo defaults.
• helm upgrade --install is the idempotent form to use in automation.
• helm list is namespace-scoped: use -A when a release seems to have vanished.
• Uninstall leaves PVCs and CRDs behind, on purpose. Check for orphaned claims afterwards.

Check your understanding

<MCQExercise exercise={{ id: 'k8s-helm-install-missing-release', title: 'A release that disappeared', description: 'A colleague installed a release yesterday, but helm list on your machine shows nothing. Both of you use the same cluster and the same kubeconfig. What is the most likely explanation?', options: [ { id: 'a', text: 'The release is in a different namespace, helm list is namespace-scoped, so helm list -A will find it' }, { id: 'b', text: 'Release state is stored locally, so it is only visible on the machine that installed it' }, { id: 'c', text: 'The release expired because Helm history is retained for 24 hours' }, { id: 'd', text: 'helm repo update must be run before helm list can see existing releases' }, ], correctId: 'a', explanation: 'Helm 3 stores release state as Secrets in the release's own namespace, so helm list only reports the current namespace unless you pass -A or -n. Anyone with read access to that namespace sees the same releases; there is nothing machine-specific about it.', wrongExplanations: { b: 'That was closer to true in some Helm 2 configurations. Helm 3 keeps state in the cluster precisely so it is shared and survives losing a laptop.', c: 'Release history has no expiry. Revisions are kept until you uninstall the release or exceed --history-max.', d: 'helm repo update refreshes the local index of available charts. It has nothing to do with listing installed releases.', }, }} />

<MCQExercise exercise={{ id: 'k8s-helm-install-uninstall-pvc', title: 'Storage costs after an uninstall', description: 'You run helm uninstall on a database release. Weeks later the cloud bill still shows the volume. Why?', options: [ { id: 'a', text: 'Most charts deliberately leave PersistentVolumeClaims behind so data survives an uninstall; they must be deleted separately' }, { id: 'b', text: 'helm uninstall only removes the release record and leaves every resource running' }, { id: 'c', text: 'The volume is retained for 90 days before automatic deletion' }, { id: 'd', text: 'PVCs can only be removed by deleting the entire namespace' }, ], correctId: 'a', explanation: 'Removing a workload should not silently destroy its data, so charts generally exclude PVCs from deletion. The same reasoning that keeps StatefulSet claims after the StatefulSet is gone. The claim, and the cloud disk behind it, persist until someone deletes it. Check with kubectl get pvc after any uninstall that involved storage.', wrongExplanations: { b: 'Uninstall does delete the Deployments, Services and other resources Helm created. PVCs and CRDs are the deliberate exceptions.', c: 'Neither Helm nor Kubernetes has any timed deletion for volumes. Nothing will clean it up on its own.', d: 'kubectl delete pvc <name> removes a single claim. Deleting the namespace works but is a much broader action than needed.', }, }} />