Helm 3
delete deployment
namespace deletion
Kubernetes
DevOps

Helm 3 delete deployment by deleting the namespace

System Design practice on Codemia

Work through 120+ system design problems with detailed solutions, from rate limiters to multi-region storage.

Practice system design

Introduction

Yes, deleting the namespace will remove a Helm release if all of that release's namespaced resources live there. The problem is that namespace deletion is a blunt instrument. It removes everything in the namespace, not just the Helm-managed objects for one release.

The Safer Default: helm uninstall

In Helm 3, a deployed chart is a release. If you want to remove one release, the first command to reach for is usually helm uninstall.

bash
helm list -A
helm uninstall my-release -n my-namespace

This is safer because it targets one release instead of destroying the entire namespace. It also makes the intent clear to anyone reading your operational history.

If the namespace is dedicated to that application and contains nothing else, deleting the namespace can still be a valid cleanup shortcut. But it should be a deliberate choice, not the default answer.

When Deleting the Namespace Is Reasonable

Namespace deletion makes sense when all of the following are true:

  • the namespace exists only for that one environment or release
  • you want every namespaced object there gone
  • you understand that non-Helm resources in the namespace will also be deleted

Typical examples are short-lived preview environments or disposable test stacks.

The command is simple:

bash
kubectl delete namespace my-namespace

Kubernetes then deletes all namespaced resources inside that namespace, including Deployments, Services, ConfigMaps, Secrets, Jobs, and most PVCs that live there.

What Namespace Deletion Does Not Guarantee

This is the part many short articles skip. Deleting the namespace does not necessarily clean up every object a chart ever created.

Cluster-scoped resources are not part of the namespace, so namespace deletion will not remove things like:

  • 'ClusterRole'
  • 'ClusterRoleBinding'
  • 'CustomResourceDefinition'
  • other cluster-wide resources installed by the chart

If the chart created cluster-scoped objects, deleting the namespace only handles the namespaced part of the installation.

Storage also needs careful wording. A PVC inside the namespace is namespaced and will be deleted with the namespace. But the backing PV behavior depends on the storage class and reclaim policy. Some volumes are deleted automatically. Others are retained.

A Good Inspection Workflow

Before deleting anything, inspect what Helm and Kubernetes think exists.

bash
helm status my-release -n my-namespace
kubectl get all -n my-namespace
kubectl get pvc -n my-namespace

If the namespace contains unrelated workloads, stop there and use helm uninstall instead.

If you suspect the chart created cluster-scoped resources, inspect those too:

bash
kubectl get clusterrole,clusterrolebinding,crd

You usually would not scan the whole cluster in a large production environment casually, but the point stands: namespace deletion is not a universal uninstall mechanism.

What About Stuck Namespace Deletion

Sometimes a namespace enters Terminating and does not disappear quickly. That usually points to finalizers, controllers still reconciling resources, or custom resources that are not cleaning up properly.

In that situation, deleting the namespace is no longer the easy path people expect. You have to identify what is blocking deletion instead of repeatedly re-running the same command.

That is another reason helm uninstall is usually the cleaner starting point for one release.

Common Pitfalls

The most common mistake is deleting a shared namespace and accidentally removing unrelated applications.

Another mistake is assuming namespace deletion removes cluster-scoped objects. It does not.

A third pitfall is assuming persistent storage behavior is uniform. PVC deletion and PV cleanup are related, but not identical, and the storage reclaim policy matters.

Summary

  • 'helm uninstall is the safer default when you want to remove one Helm release.'
  • Deleting the namespace removes all namespaced resources inside it, not just Helm resources.
  • Namespace deletion is reasonable only when the namespace is dedicated and disposable.
  • Cluster-scoped resources are not removed by namespace deletion.
  • Check PVC and PV behavior separately if storage cleanup matters.

Related reading
Course
Beginner
27 lessons
10 hours
System Design Fundamentals

Build a strong foundation in designing scalable, reliable distributed systems.

View the course
Track what you have practised

A free account saves your progress, solutions and study plan across every problem on Codemia.

System Design practice on Codemia

Work through 120+ system design problems with detailed solutions, from rate limiters to multi-region storage.

Practice system design

All Rights Reserved.