terraform import, and finally applying a state‑only change to clean up the release.Helm releases that remain in a pending-install or failed state block further upgrades and can cause CI/CD pipelines to stall. Traditional fixes—such as helm uninstall or helm rollback—often fail because Helm’s internal secret that tracks the release is corrupted or missing. By bringing the release under Terraform’s control, you gain a deterministic way to edit or delete the problematic metadata without touching the live workloads.
In this guide you will learn how to identify a stuck release, map its resources to Terraform configuration, import those resources into the Terraform state file, and then either purge the release or correct its status. The steps work with Helm 3 (the version shipped with most Kubernetes distributions as of 2026) and Terraform 1.9+.
What You’ll Learn
- How to diagnose a Helm release that is stuck in a pending state.
- How to generate Terraform code that mirrors Helm‑managed resources.
- How to import existing Kubernetes objects into Terraform state.
- How to safely delete or fix the release using only Terraform.
- Common pitfalls and how to avoid them.
Prerequisites
- A working
kubectlcontext with cluster‑admin rights. - Helm 3 installed (official install guide).
- Terraform 1.9 or later installed (download page).
- The Terraform Kubernetes provider configured (see provider docs).
- Access to the Helm release’s namespace (commonly
defaultor a custom namespace).
Pro Tip: Keep a backup of the current
.tfstatefile (or enable remote state versioning) before you start importing. A simplecp terraform.tfstate terraform.tfstate.backupcan save hours of debugging.
Diagnose the Stuck Release
Check Helm status
helm status my-app -n production
If the output shows STATUS: pending-install or STATUS: failed for an extended period, the release is stuck.
Inspect Helm secret
Helm stores release information in a secret named sh.helm.release.v1.<release-name>.v<revision> in the release’s namespace.
kubectl get secret -n production -l "owner=helm" -o jsonpath="{.items[?(@.metadata.name=='sh.helm.release.v1.my-app.v1')].metadata.name}"
If the secret is missing or corrupted (e.g., empty data field), Helm cannot complete the operation.
Identify orphaned resources
kubectl get all -n production -l "app.kubernetes.io/instance=my-app"
Orphaned Deployments, Services, or PVCs indicate that Helm created objects but could not record the release state.
Export Helm Release Manifests
Use helm get manifest to retrieve the rendered YAML that Helm attempted to apply.
helm get manifest my-app -n production > helm-manifest.yaml
This file will serve as the source for the Terraform configuration.
Create Terraform Configuration
Initialize a new Terraform module
mkdir tf-helm-recovery && cd tf-helm-recovery
cat > main.tf <<EOF
terraform {
required_providers {
kubernetes = {
source = "hashicorp/kubernetes"
version = "~> 2.0"
}
}
}
provider "kubernetes" {
config_path = "~/.kube/config"
}
EOF
Translate the Helm manifest to Terraform resources
For each object in helm-manifest.yaml, create a matching kubernetes_* resource. Below is a minimal example for a Deployment and a Service.
resource "kubernetes_deployment" "my_app" {
metadata {
name = "my-app"
namespace = "production"
labels = {
"app.kubernetes.io/name" = "my-app"
"app.kubernetes.io/instance" = "my-app"
}
}
spec {
replicas = 3
selector {
match_labels = {
"app.kubernetes.io/name" = "my-app"
}
}
template {
metadata {
labels = {
"app.kubernetes.io/name" = "my-app"
}
}
spec {
container {
name = "my-app"
image = "myrepo/my-app:1.2.3"
port {
container_port = 8080
}
}
}
}
}
}
resource "kubernetes_service" "my_app" {
metadata {
name = "my-app"
namespace = "production"
labels = {
"app.kubernetes.io/name" = "my-app"
}
}
spec {
selector = {
"app.kubernetes.io/name" = "my-app"
}
port {
port = 80
target_port = 8080
}
type = "ClusterIP"
}
}
EOF
Repeat for all objects (ConfigMaps, Secrets, Ingress, etc.). You can automate this translation with kpt or terraform-provider-kubernetes scripts, but manual creation ensures precise control.
Import Resources into Terraform State
Initialize Terraform
terraform init
Import each resource
Use the terraform import command with the Kubernetes resource identifier <namespace>/<name>.
# Example for the Deployment
terraform import kubernetes_deployment.my_app production/my-app
# Example for the Service
terraform import kubernetes_service.my_app production/my-app
Run the import for every resource defined in main.tf. After each import, run terraform plan to verify that the imported state matches the live object. Resolve any drift by editing the Terraform code or by applying a -target plan.
Clean Up or Repair the Stuck Release
Option 1 – Delete the Helm secret
If the secret is the only corrupted piece, you can let Terraform delete it as a kubernetes_secret resource.
resource "kubernetes_secret" "helm_release" {
metadata {
name = "sh.helm.release.v1.my-app.v1"
namespace = "production"
}
}
terraform apply -target=kubernetes_secret.helm_release
This removes the stale Helm metadata, allowing a fresh helm install or helm upgrade --install to succeed.
Option 2 – Force‑remove the entire release
If you prefer to start from scratch, import the secret, then delete it with Terraform.
terraform import kubernetes_secret.helm_release production/sh.helm.release.v1.my-app.v1
terraform destroy -target=kubernetes_secret.helm_release
After the secret is gone, run helm install my-app ./chart -n production to redeploy.
Option 3 – Patch the release status
When the underlying objects are healthy but Helm thinks the release failed, you can patch the secret’s status field directly via Terraform.
resource "kubernetes_secret" "helm_release" {
metadata {
name = "sh.helm.release.v1.my-app.v1"
namespace = "production"
}
data = {
"release" = base64encode(yamldecode(file("patched-release.yaml")))
}
}
Generate patched-release.yaml by copying the existing secret data, changing the status field to deployed, and re‑encoding it. Apply with terraform apply.
Verify the Cluster Is Healthy
# Verify Helm now reports a healthy release
helm status my-app -n production
# Ensure all objects are running
kubectl get all -n production -l "app.kubernetes.io/instance=my-app"
If the Helm status shows deployed and all pods are Running, the recovery succeeded.
Frequently Asked Questions
Why does Helm get stuck in the first place?
Helm stores release metadata in a Kubernetes secret. If the secret is corrupted, missing, or if the API server returns a timeout during the install, Helm cannot mark the release as successful, leaving it in pending-install or failed.
Can I use helm uninstall instead of Terraform?
Yes, but helm uninstall relies on the secret to locate resources. When the secret is broken, the command may report “release not found” while the resources remain, leading to orphaned objects.
Do I need to import every single Kubernetes object?
Only the objects that Helm created (those with the Helm label set) need to be imported. Core cluster resources (e.g., namespaces) are managed separately.
Is it safe to run terraform destroy on imported resources?
Terraform will delete the live objects, just like kubectl delete. Ensure you have backups or that the resources can be recreated from the Helm chart before destroying.
What if the cluster uses a custom provider (e.g., OpenShift)?
The Kubernetes provider works with any conformant API server, including OpenShift. You may need to add extra provider arguments for authentication (e.g., client_certificate, client_key).
How do I prevent this situation in the future?
Enable Helm’s --atomic flag during installs; it rolls back automatically on failure, keeping the secret consistent. Additionally, store Terraform state remotely with versioning (e.g., Terraform Cloud, S3 with DynamoDB lock) to recover from accidental deletions.
Can I automate the import step?
Yes. Scripts that parse helm get manifest and generate matching kubernetes_* resources are available on GitHub (search for “helm-to-terraform”). Automation reduces manual errors but still requires review before applying.



