Uninstalling Charts

helm uninstall Release Cleanup Hooks Behavior

A comprehensive guide to uninstalling Helm charts covering helm uninstall, release cleanup, hooks behavior, and best practices for removing Helm releases.

helm uninstall Release Cleanup Hooks Behavior

Understanding Helm Uninstall

Helm uninstall removes a release from your Kubernetes cluster. It deletes all resources created by the chart and cleans up the release history.

helm uninstall: Remove a release (Helm v3)
helm delete: Legacy command (Helm v2)
Release Cleanup: Removes Kubernetes resources and secrets
Hooks: Pre-delete and post-delete hooks execute during uninstall

Key Concept: Helm v3 replaced helm delete with helm uninstall. The new command is more explicit about its purpose and behavior.

Uninstalling a Release

                # Basic uninstall
helm uninstall my-release

# Uninstall with keep history
helm uninstall my-release --keep-history

# Uninstall with timeout
helm uninstall my-release --timeout 5m

# Uninstall with dry-run
helm uninstall my-release --dry-run

# Uninstall with wait
helm uninstall my-release --wait

# Uninstall and ignore hooks
helm uninstall my-release --no-hooks

# Uninstall by name (Helm v3)
helm uninstall my-release

# Uninstall by name (Helm v2 legacy)
helm delete my-release

# Uninstall multiple releases
helm uninstall release1 release2 release3

# Uninstall all releases in a namespace
helm ls -n default -q | xargs -I {} helm uninstall {} -n default
            

--keep-history

Keep the release history after uninstall. Useful for auditing and rollback purposes.

--timeout

Set a timeout for the uninstall operation. Default is 5 minutes.

--dry-run

Preview what will be deleted without actually removing anything.

--no-hooks

Skip hook execution during uninstall. Useful for troubleshooting or force removal.

Uninstall Best Practices:

Use --dry-run to preview before uninstalling
Use --keep-history for auditing purposes
Set appropriate timeouts for large releases
Test uninstall in staging before production
Back up important data before uninstalling

Hooks Behavior During Uninstall

Hooks are executed during uninstall to perform cleanup tasks. Understanding hook behavior is essential for proper release cleanup.

                # Pre-delete hook (runs before deletion)
apiVersion: batch/v1
kind: Job
metadata:
  name: pre-delete-cleanup
  annotations:
    helm.sh/hook: pre-delete
    helm.sh/hook-delete-policy: hook-succeeded
spec:
  template:
    spec:
      containers:
      - name: cleanup
        image: busybox
        command: ['sh', '-c', 'echo "Pre-delete cleanup"']
      restartPolicy: Never

# Post-delete hook (runs after deletion)
apiVersion: batch/v1
kind: Job
metadata:
  name: post-delete-cleanup
  annotations:
    helm.sh/hook: post-delete
    helm.sh/hook-delete-policy: hook-succeeded
spec:
  template:
    spec:
      containers:
      - name: cleanup
        image: busybox
        command: ['sh', '-c', 'echo "Post-delete cleanup"']
      restartPolicy: Never

# Hook with delete policy
metadata:
  annotations:
    helm.sh/hook: pre-delete
    helm.sh/hook-delete-policy: before-hook-creation,hook-succeeded

# Skip hooks during uninstall
helm uninstall my-release --no-hooks
            

pre-delete

Executed before the release is deleted. Used for cleanup, backup, or validation.

post-delete

Executed after the release is deleted. Used for final cleanup or notifications.

hook-delete-policy

Controls when hooks are deleted. Options: hook-succeeded, hook-failed, before-hook-creation.

--no-hooks

Skip all hook execution during uninstall.

Hook Considerations:

Hooks can prevent uninstall if they fail
Use --no-hooks to bypass failing hooks
Set appropriate delete policies for hooks
Test hook behavior in non-production
Monitor hook execution during uninstall

Release Cleanup

                # List releases
helm list
helm list --all

# Show release status
helm status my-release

# Check release history
helm history my-release

# Clean up failed releases
helm uninstall my-release --keep-history

# Force remove pending releases
helm uninstall my-release --no-hooks

# Clean up all releases in namespace
helm list -n default -q | xargs -I {} helm uninstall {} -n default

# Clean up release secrets
kubectl get secrets -n default | grep sh.helm.release.v1

# Delete specific release secret
kubectl delete secret sh.helm.release.v1.my-release.v1

# Remove all release secrets
kubectl get secrets -n default -l owner=helm -o name | xargs kubectl delete
            

helm list

List all releases to identify what needs to be cleaned up.

helm status

Check the status of a release before uninstalling.

helm uninstall

Remove the release and clean up resources.

Secret Cleanup

Remove Helm release secrets from Kubernetes.

Cleanup Best Practices:

Always use helm uninstall to remove releases
Use --keep-history for auditing purposes
Clean up failed releases promptly
Remove release secrets when no longer needed
Document cleanup procedures

Troubleshooting Uninstall Issues

                # Check release status
helm status my-release

# View release history
helm history my-release

# Check for failed hooks
kubectl get jobs --all-namespaces | grep -E "pre-delete|post-delete"

# Check hook logs
kubectl logs <hook-job-pod>

# Force uninstall (skip hooks)
helm uninstall my-release --no-hooks

# Uninstall with keep history (for failed releases)
helm uninstall my-release --keep-history

# Clean up release secrets manually
kubectl get secrets -n default | grep sh.helm.release.v1.my-release
kubectl delete secret sh.helm.release.v1.my-release.v1

# Check Kubernetes events
kubectl get events --field-selector involvedObject.name=my-release

# Check pod status (if any resources remain)
kubectl get pods -l app=my-app
            

Common Issues:

Failed Hooks: Use --no-hooks to skip hook execution
Pending Release: Use --no-hooks or --force to remove
Resource Leaks: Check for orphaned resources
Timeout: Increase timeout with --timeout
Permission Issues: Check RBAC permissions

helm uninstall vs helm delete

                ┌────────────────────┬──────────────────────────┬──────────────────────────┐
│      Command       │         Helm v3          │         Helm v2          │
├────────────────────┼──────────────────────────┼──────────────────────────┤
│ Uninstall Release  │ helm uninstall <release> │ helm delete <release>    │
│ Keep History       │ --keep-history           │ --keep-history           │
│ Skip Hooks         │ --no-hooks               │ --no-hooks               │
│ Dry Run            │ --dry-run                │ --dry-run                │
│ Timeout            │ --timeout                │ --timeout                │
│ Default Behavior   │ Removes release          │ Removes release          │
│                    │ and history              │ (keeps history by default)│
│ History Storage    │ Secrets                  │ ConfigMaps               │
└────────────────────┴──────────────────────────┴──────────────────────────┘

# Helm v3 default: removes release and history
helm uninstall my-release

# Helm v2 default: removes release, keeps history
helm delete my-release

# Helm v3 with keep history
helm uninstall my-release --keep-history

# Helm v2 with purge (remove history)
helm delete my-release --purge
            

Helm v3 vs v2:

Helm v3 uses helm uninstall (more explicit)
Helm v3 stores release history as Secrets (more secure)
Helm v3 default behavior removes history (unlike v2)
Always use Helm v3 for new projects

Frequently Asked Questions

What is the difference between helm uninstall and helm delete?

helm uninstall is the Helm v3 command. helm delete is the Helm v2 legacy command. Helm v3 removes the release history by default, while Helm v2 keeps it.

How do I keep release history when uninstalling?

Use helm uninstall <release> --keep-history to keep the release history for auditing purposes.

What happens to hooks during uninstall?

Pre-delete hooks run before deletion, post-delete hooks run after deletion. Use --no-hooks to skip hook execution.

How do I uninstall a failed release?

Use helm uninstall <release> --no-hooks to skip hook execution and force removal. Use --keep-history to keep the history.

How do I clean up all releases in a namespace?

Use helm list -n <namespace> -q | xargs -I {} helm uninstall {} -n <namespace> to uninstall all releases in a namespace.

Where does Helm store release history?

Helm v3 stores release history as Kubernetes Secrets in the release namespace. Helm v2 stored history as ConfigMaps.

Can I recover a deleted release?

If you used --keep-history, you can rollback to the last revision. If history was removed, you cannot recover the release.

How do I remove orphaned Helm secrets?

Use kubectl get secrets -n <namespace> -l owner=helm -o name | xargs kubectl delete to remove all Helm release secrets.

Uninstalling Charts

--keep-history

--timeout

--dry-run

--no-hooks

pre-delete

post-delete

hook-delete-policy

--no-hooks

helm list

helm status

helm uninstall

Secret Cleanup

What is Helm?

Upgrade & Rollback

Chart Hooks

Testing Charts

Helm Best Practices