Helm Basic Commands with Practical Examples: An Operations Guide

Intro

Helm is the package manager for Kubernetes, but its real value appears only when you use it with operational discipline. A chart is not a magic bullet; it is a set of Kubernetes manifests wrapped with configuration and lifecycle hooks. Every helm install or helm upgrade changes the state of a cluster, so operators need to know exactly what a command will do, what it will produce, and how to recover when something goes wrong.

This guide is for developers, DevOps engineers, and technical startup teams who already know what Kubernetes is but want to use Helm safely and effectively. It walks through the basic commands you will use every day, with concrete examples, expected output, failure signals, and recovery steps. The focus is on command-line operations, not chart development. We will cover version and environment inventory, safe configuration paths, verification and diagnostics, failure modes, and a practical checklist. Each section includes real commands and sample output so you can follow along in your own cluster.

Before you start, ensure you have:

• A running Kubernetes cluster (local like Minikube or a managed service)
• kubectl configured to talk to that cluster
• Helm v3 installed (v2 is deprecated and out of scope)
• Basic understanding of Kubernetes objects like Pods, Deployments, and Services

To check your Helm version, run:

helm version --short

Sample output:

v3.12.0+g5e8c1e6

If you see a version starting with v2, upgrade to Helm v3 before continuing.

Version and Environment Inventory

Before running any Helm command, know your environment. This means checking the Helm client version, the Kubernetes server version, and the current state of any existing releases. A read-only inventory protects you from making changes based on stale assumptions.

Start by verifying that Helm can talk to your cluster:

helm list --all-namespaces

Expected output:

NAME    NAMESPACE       REVISION UPDATED                                 STATUS   CHART           APP VERSION
myapp   default         1        2023-10-01 10:20:30.123456 +0000 UTC deployed myapp-0.1.0     1.16.0

If you get an error like Error: Kubernetes cluster unreachable, check your kubeconfig and ensure kubectl get nodes works. If the command returns an empty output, no releases are currently installed.

Next, compare the Helm client and server versions. Helm v3 removed the server-side component (Tiller), so only the client version matters:

helm version

Sample output:

version.BuildInfo{Version:"v3.12.0", GitCommit:"5e8c1e6", GitTreeState:"clean", GoVersion:"go1.20.4"}

To see the Kubernetes version:

kubectl version --short

Sample output:

Client Version: v1.27.3
Kustomize Version: v5.0.1
Server Version: v1.27.3

Helm v3 supports Kubernetes versions from 1.16 onward, but if your cluster is older, upgrade it or use an older Helm version from the compatibility matrix. Keep a written note of these versions for every environment; they are the first thing support teams ask for when a deployment fails.

Helm Repositories and Chart Search

Helm charts are stored in repositories. The most common is the official Helm stable repo, but many vendors host their own. Add a repository once and reuse it. For example, to add the Bitnami repository (a popular source of production-ready charts):

helm repo add bitnami https://charts.bitnami.com/bitnami

Then update the local cache:

helm repo update

Now search for charts:

helm search repo bitnami/wordpress

Sample output:

NAME                    CHART VERSION   APP VERSION DESCRIPTION
bitnami/wordpress       15.2.7          6.2.2       WordPress is the world's most popular blogging...

Note the chart version and app version: the chart version tracks the packaging, while the app version tracks the application inside. When you install, be explicit about the chart version to avoid surprises from upstream changes.

Common pitfall: Repositories change over time. If you see Error: no repositories found, run helm repo add and helm repo update. If a chart disappears from a repo, pin the version you need in your CI/CD pipeline to avoid broken deployments.

Installing a Chart

The helm install command deploys a chart as a release. A release is a specific instance of a chart with its own configuration. Always name your release explicitly; otherwise Helm generates a random name that is hard to track.

Basic syntax:

helm install <release-name> <chart> [flags]

Example: install WordPress from the Bitnami repo with a release name my-blog in the default namespace:

helm install my-blog bitnami/wordpress --version 15.2.7

Expected output (truncated):

NAME: my-blog
LAST DEPLOYED: Mon Oct  2 10:00:00 2023
NAMESPACE: default
STATUS: deployed
REVISION: 1
NOTES:
1. Get the application URL by running these commands:
  export POD_NAME=$(kubectl get pods --namespace default -l "app.kubernetes.io/name=wordpress,app.kubernetes.io/instance=my-blog" -o jsonpath="{.items[0].metadata.name}")
  kubectl port-forward --namespace default $POD_NAME 8080:80
  echo "Visit http://127.0.0.1:8080 to use your application"

Prerequisites for this command:

• You have added the Bitnami repo and run helm repo update.
• Your namespace exists (create with kubectl create namespace default if needed).
• You have sufficient RBAC permissions to create resources in that namespace.

Blast radius: This command creates multiple Kubernetes resources: Deployments, Services, PVCs, Secrets, etc. In a shared cluster, always install into a dedicated namespace to isolate your application.

Verification: After install, check the release status:

helm status my-blog

This shows the resources created and any notes. Also run kubectl get pods to see if the Pods are running.

Recovery: If the install fails, Helm will not leave a broken release. Check the error message, fix the issue (e.g., insufficient resources), and retry. You can also use helm uninstall my-blog to clean up any partial resources.

Inspecting Releases

After installation, you need to inspect releases regularly. The helm list command shows all releases in the current namespace or across all namespaces:

helm list --namespace default

Sample output:

NAME    NAMESPACE REVISION UPDATED                                 STATUS   CHART           APP VERSION
my-blog default   1        2023-10-02 10:00:00.000000 +0000 UTC deployed wordpress-15.2.7 6.2.2

For more details on a specific release, use helm status:

helm status my-blog

This shows the current revision, the namespace, and the resources created. To see the computed Kubernetes manifests without applying them, use helm get manifest:

helm get manifest my-blog | less

This is a read-only command that can help you understand what Helm actually deployed.

To see the values used for a release, combine helm get values:

helm get values my-blog

Sample output:

USER-SUPPLIED VALUES:
null

If no custom values were supplied, it shows null. This is important for debugging configuration problems.

Upgrading and Rolling Back

Upgrades change the live application. Before you upgrade, back up the current release configuration. Helm stores the configuration as a Secret in the cluster, but you can also export it:

helm get values my-blog -o yaml > my-blog-values-backup.yaml

Then perform the upgrade with new values from a file:

helm upgrade my-blog bitnami/wordpress --version 15.2.7 -f my-new-values.yaml

If you omitted --version, Helm would use the latest chart version, which might introduce breaking changes. Always pin the version or use a range with --version.

Verification after upgrade:

helm history my-blog

Sample output:

REVISION UPDATED                 STATUS     CHART           DESCRIPTION
1        Mon Oct  2 10:00:00 2023 superseded wordpress-15.2.7 Install complete
2        Mon Oct  2 11:00:00 2023 deployed   wordpress-15.2.7 Upgrade complete

If the upgrade fails, Helm automatically rolls back to the previous revision. You can also manually roll back to a specific revision:

helm rollback my-blog 1

This reverts to revision 1. Verify with helm status my-blog.

Common pitfall: Upgrades can change the compute resources (CPU/memory) of Pods, causing them to be recreated. Ensure your application handles rolling updates gracefully. Use kubectl rollout status deployment/my-blog to monitor progress.

Uninstalling Releases

When you no longer need a release, remove it cleanly:

helm uninstall my-blog

This deletes all Kubernetes resources associated with the release, but it does not delete the namespace itself or any persistent volume claims (PVCs) that were dynamically provisioned, unless you specify --keep-history or the chart uses a cleanup hook. To remove the namespace as well:

kubectl delete namespace default

Caution: Uninstalling is irreversible for the resources managed by Helm. Ensure you have backups and that no other services depend on them. For example, if you have a database release and another release uses it, uninstalling the database will break the dependent application.

Helm Configuration and Values

Helm charts are configured through values. The default values are defined in the chart's values.yaml file. You can override them with your own values file or --set flags.

Example values file my-values.yaml:

replicaCount: 2
image:
  tag: "6.2.2"
service:
  type: LoadBalancer

Install with custom values:

helm install my-blog bitnami/wordpress --version 15.2.7 -f my-values.yaml

To see what values a chart expects, use helm show values:

helm show values bitnami/wordpress --version 15.2.7 | less

This is essential before overriding; many charts have nested configurations that are easy to miss.

Secret handling: Never store real credentials in values files that you commit to version control. Use Kubernetes Secrets and reference them via existingSecret or use environment-specific values files. For example:

existingSecret: my-blog-secret

Then create the Secret separately:

kubectl create secret generic my-blog-secret --from-literal=password='S3cret!'

Helm will use the existing Secret instead of generating a new one.

Verification and Diagnostics

Verification is a continuous process. After any change, check the actual state against the expected state. Commands like helm test can run chart-defined tests:

helm test my-blog

This executes the test hooks defined in the chart. It may run a Pod that checks the application is responding. Output will show pass/fail status.

For deeper diagnostics, use kubectl to inspect resources managed by Helm:

kubectl get pods --namespace default -l app.kubernetes.io/instance=my-blog

Sample output:

NAME                        READY   STATUS    RESTARTS   AGE
my-blog-wordpress-0         1/1     Running   0          5m
my-blog-mariadb-0          1/1     Running   0          5m

If Pods are not running, use kubectl describe pod <pod-name> and kubectl logs <pod-name> to investigate. Helm itself also has a debug flag:

helm install my-blog bitnami/wordpress --debug --dry-run

The --dry-run flag shows the manifests that would be sent to Kubernetes without applying them. This is a critical safety step for any change.

Expected output for --dry-run: the generated YAML manifests. Review them for correctness before the actual run.

Failure Modes and Recovery

Helm failures can occur at different stages. Here are common failure modes and how to recover:

1. Chart not found

Error: Error: chart "bitnami/wordpress" not found

Why: The repository is not added or the chart name is misspelled.

Recovery: Add the repo and update: helm repo add bitnami https://charts.bitnami.com/bitnami then helm repo update. Verify with helm search repo bitnami/wordpress.

2. Release name already exists

Error: Error: cannot re-use a name that is still in use

Why: You are trying to install a release with a name that already exists.

Recovery: Either uninstall the old release (helm uninstall my-blog) or use a different name. If you want to upgrade, use helm upgrade instead of install.

3. Upgrade failed due to invalid values

Error: Error: UPGRADE FAILED: cannot patch "my-blog" with kind Deployment: Deployment.apps "my-blog-wordpress" is invalid: spec.template.spec.containers[0].image: Required value

Why: The values file omitted a required field or provided an invalid type.

Recovery: Helm automatically rolls back to the last successful revision. Fix the values file, verify with helm upgrade --dry-run, then retry.

4. Pending Pods due to resource constraints

Symptom: kubectl get pods shows Pending status.

Why: Not enough CPU/memory in the cluster.

Recovery: Reduce resource requests in values or add nodes. Then kubectl delete pod <pending-pod> to reschedule.

5. Lost release secrets

Symptom: helm list shows nothing, but resources exist.

Why: The Helm release secret (a Kubernetes Secret) was accidentally deleted.

Recovery: You can recover by creating a new release with the same name and using helm adopt if available, or reinstall from backups. Prevention: do not delete Helm release secrets; use helm uninstall instead.

Safe Configuration Path

Follow a safe path for any configuration change:

1. Observe current state with read-only commands: helm list, helm status, helm get values.
2. Backup current configuration: helm get values my-blog -o yaml > backup.yaml.
3. Change one scoped item at a time. Use a values file and --dry-run to preview.
4. Apply the change with helm upgrade or helm install.
5. Verify with helm test, kubectl get pods, and application-level checks.
6. Document the change and the recovery steps.

For example, to change the replica count from 1 to 3:

• Observe: helm get values my-blog (note current replicaCount)
• Backup: helm get values my-blog -o yaml > my-blog-values-$(date +%Y%m%d).yaml
• Modify values file: set replicaCount: 3
• Dry-run: helm upgrade my-blog bitnami/wordpress --version 15.2.7 -f my-values.yaml --dry-run
• Apply: helm upgrade my-blog bitnami/wordpress --version 15.2.7 -f my-values.yaml
• Verify: kubectl get deployment my-blog-wordpress -o jsonpath='{.spec.replicas}' should output 3.

Operations Checklist

Use this checklist before any Helm operation in a production environment:

• [ ] Confirm Helm client version (helm version --short) matches expected range.
• [ ] Confirm kubeconfig points to the correct cluster (not staging vs production).
• [ ] List current releases (helm list --all-namespaces) and note the target release.
• [ ] Backup current values (helm get values <release> -o yaml > backup.yaml).
• [ ] Review chart changes with helm show values and helm show readme.
• [ ] Run a dry-run: helm upgrade <release> <chart> --dry-run or helm install --dry-run.
• [ ] Set explicit --namespace and --version to avoid ambiguity.
• [ ] If using --set, double-check quotes and YAML syntax.
• [ ] Have a rollback plan: know the previous revision (helm history <release>).
• [ ] Designate an owner for the change (e.g., Priya Shah, Engineering Lead) and a review time (e.g., weekly release review).
• [ ] After apply, verify with helm status, helm test, and application health checks.
• [ ] Document the change, owner, and any issues in the team's change log.

Pitfall to avoid: Running helm install instead of helm upgrade on an existing release. This causes an error; always check helm list first.

Common Pitfalls Summary

Here is a quick reference of common mistakes and how to avoid them:

Conclusion

Helm basic commands become safe operations when you apply the principles of observation, minimal change, verification, and recovery. The commands covered here—repo add, install, list, status, get, upgrade, rollback, uninstall, and test—are the daily toolkit for any Kubernetes operator. Use them with dry-runs, version pinning, and backups to maintain control over your deployments.

As a next step, pick one low-risk verification: run helm list --all-namespaces to inventory your current releases, then choose a release and run helm get values to understand its configuration. Review any recent changes and ensure you have a rollback plan. Then, adopt the operations checklist for your team. Helm is a tool that rewards discipline: the more you observe before changing, the fewer surprises you will encounter.