How to Recover a Stuck Helm Release in Kubernetes Using Terraform State

Step‑by‑step guide to fix a stuck Helm release in Kubernetes by importing and correcting the Terraform state, with commands and best practices.

How to Recover a Stuck Helm Release in Kubernetes Using Terraform State - Cloud & DevOps
Short answer: A stuck Helm release can be rescued by importing the release’s Kubernetes resources into Terraform state, then using Terraform to delete or modify the release metadata. The process involves locating the Helm‑managed objects, creating matching Terraform resources, running 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 kubectl context 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 default or a custom namespace).

Pro Tip: Keep a backup of the current .tfstate file (or enable remote state versioning) before you start importing. A simple cp terraform.tfstate terraform.tfstate.backup can 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.

Official documentation