Uninstalling Releases
1. Uninstalling Release
| Command | Description | Flags |
|---|---|---|
| helm uninstall | Uninstalls a release from the cluster | --dry-run, --no-hooks, --timeout, --wait |
Note: Uninstalling a release removes all resources associated with it, including ConfigMaps, Secrets, and Services.
2. Keeping Release History
| Option | Values | Notes |
|---|---|---|
| --keep-history | false |
Whether to keep release history after uninstalling |
| --dry-run | false |
Simulate uninstall without actually removing resources |
| --timeout | 300s |
Timeout for waiting for resources to be deleted |
Note: When
--keep-history is used, the release remains in the history and can be rolled back to using helm rollback.
Warning: If
--keep-history is not specified, the release history will be permanently deleted.
3. Waiting for Deletion
| Option | Values | Description |
|---|---|---|
| --timeout | 300s |
Timeout for waiting for the release to be deleted |
| --waitForJobs | false |
Wait for any jobs to complete before deleting the release |
| --no-hooks | false |
Prevent hooks from running during deletion |
Note: The
--timeout option ensures that Helm waits for the release to be fully deleted before returning control to the terminal.
4. Setting Deletion Timeout
| Option | Values | Description |
|---|---|---|
| --timeout | 300s |
Timeout for the uninstall operation in seconds |
| --wait | false |
Wait for all resources to be deleted before returning |
| --no-hooks | false |
Prevent hooks from running during uninstall |
Note: The timeout value must be a valid duration string (e.g.,
30s, 5m, 1h) and defaults to 300 seconds (5 minutes).
5. Performing Dry Run Uninstall
| Option | Values | Description |
|---|---|---|
| --dry-run | true |
Simulates the uninstall process without actually removing resources |
| --namespace | default |
Specifies the namespace from which to uninstall the release |
| --keep-history | false |
Preserves the uninstall history for the release (default is to delete it) |
Note: The
--dry-run flag is useful for verifying what would be removed before executing the actual uninstall command.6. Uninstalling with Cascade
When uninstalling a Helm release, you can use the --cascade flag to control how dependencies are handled.
| Flag | Description | Default Behavior |
|---|---|---|
| --cascade | Controls the deletion strategy for dependent resources | background |
The --cascade flag accepts the following values:
none: Only delete the release object, leaving dependent resources untouched.background: Delete the release and start deleting dependent resources in the background.foreground: Delete the release and wait for dependent resources to be deleted before returning.
Note: Using
--cascade foreground ensures all dependent resources are fully cleaned up before the release is removed.
7. Viewing Uninstall Output
| Field | Description | Example |
|---|---|---|
| release.name | Name of the release being uninstalled | my-app |
| status | Status of the uninstall operation | deleted |
| time | Timestamp of the uninstall | 2026-04-05T14:30:00Z |
| namespace | Kubernetes namespace where the release was installed | production |
Example: Uninstalling a Release and Viewing Output
helm uninstall my-app -n production
release "my-app" uninstalled
Note: The output will vary depending on whether the release was successfully uninstalled or if there were any errors during the process.
8. Uninstalling Multiple Releases
Uninstalling multiple Helm releases at once can be efficiently managed using the helm uninstall command with multiple release names or by leveraging shell scripting for automation.
| Command | Description | Notes |
|---|---|---|
| helm uninstall <release1> <release2> | Uninstalls multiple releases by name | Releases are uninstalled in the order specified |
| helm uninstall $(helm list -q) | Uninstalls all releases in the current namespace | Use with caution; this command removes all releases |
Note: Helm does not support uninstalling multiple releases in a single command with flags like
--all or -n. You must list each release explicitly or use shell expansion.
9. Handling Failed Uninstalls
Note: If a Helm release uninstall fails, it may leave behind partial resources. This can happen due to resource dependencies or permission issues.
| Scenario | Description | Action |
|---|---|---|
| Uninstall timeout | Uninstall operation times out before completion. | Use --timeout flag to extend the timeout period. Example: helm uninstall my-release --timeout 600s |
| Resource deletion failure | Some Kubernetes resources fail to delete due to finalizers or dependencies. | Manually delete the problematic resources using kubectl. Then retry uninstall with helm uninstall --dry-run to verify. |
| Permission denied | Insufficient RBAC permissions to delete resources. | Ensure the user or service account has delete permissions for all resources in the release. |
Example: Manual cleanup of stuck resources
kubectl delete deployment my-deployment --namespace my-namespace
kubectl delete service my-service --namespace my-namespace
helm uninstall my-release --dry-run
10. Cleaning Up Orphaned Resources
When uninstalling Helm releases, some Kubernetes resources may persist if they were not originally managed by the release. These are referred to as orphaned resources and can clutter your cluster.
| Resource Type | Description | Action |
|---|---|---|
| ConfigMap | Stores configuration data | Manually delete if not needed |
| Secret | Stores sensitive data | Manually delete if not needed |
| Service | Exposes application endpoints | Manually delete if not needed |
| PersistentVolumeClaim | Requests storage from the cluster | Manually delete if not needed |
Example: Identify Orphaned Resources
# List all resources in a namespace
kubectl get all -n <namespace>
# Check for resources not managed by Helm
kubectl get all -n <namespace> --no-headers | grep -v "helm"
Note: Use
kubectl get all -n <namespace> to list all resources in a namespace and manually verify which ones are not managed by Helm before deletion.
Warning: Deleting orphaned resources can lead to data loss or service disruption if they are still in use. Always verify the impact before deletion.