terraform-state-recovery

Identify and remove orphaned Kubernetes and Helm resources from Terraform state.

Updated Sep 23, 2025
One-click install
npx skills add https://github.com/Matchpoint-AI/matchpoint-github-runners-helm --skill terraform-state-recovery
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: terraform-state-recovery
Source: https://github.com/Matchpoint-AI/matchpoint-github-runners-helm/tree/main/.claude/skills/terraform-state-recovery
Command: npx skills add https://github.com/Matchpoint-AI/matchpoint-github-runners-helm --skill terraform-state-recovery

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

When a Kubernetes cluster is recreated, Terraform state can become stale, referencing resources that no longer exist. This leads to terraform apply failures and resource conflicts, blocking infrastructure deployments. This Skill provides a systematic procedure to recover from such orphaned state issues.

Core Features & Use Cases

  • Orphaned Resource Identification: Automatically lists Kubernetes and Helm resources in state that are no longer present in the cluster.
  • Safe State Removal: Guides through terraform state rm commands to clean up stale entries without affecting active infrastructure.
  • Automated Recovery Script: Provides a Bash script to streamline the process of identifying and removing orphaned state.
  • Prevention Strategies: Recommends using data sources, letting ArgoCD manage application resources, and remote state locking to prevent future issues.
  • Use Case: If your terraform apply fails with "Resource already exists in state" after a Rackspace Spot cloudspace was deleted and recreated, use this Skill to identify and remove the orphaned Kubernetes and Helm resources from your Terraform state, allowing you to successfully re-apply your infrastructure.

Quick Start

Use the terraform-state-recovery skill to identify and remove orphaned Kubernetes namespaces and Helm releases from the Terraform state after a cluster recreation. Explain how to verify the state is clean before re-applying.

Frequently Asked Questions about terraform-state-recovery

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I recover Terraform state after recreating a Kubernetes cluster?

Recover Terraform state by identifying orphaned resources using `terraform state list` and `terraform state show`, then remove stale entries with `terraform state rm` before re-applying. This clears references to resources that no longer exist in the recreated cluster, unblocking deployments.

What causes Terraform apply failures when a Kubernetes cluster is recreated?

Recreating a Kubernetes cluster leaves stale state entries for resources that no longer exist. Terraform apply then fails with resource-already-exists errors because it tries to manage orphaned Kubernetes namespaces and Helm releases still referenced in state but absent from the cluster.

How do I identify orphaned Kubernetes resources in Terraform state?

Use `terraform state list` to enumerate all Kubernetes and Helm resources in state, then verify each exists in the cluster using kubectl. Resources present in state but missing from the cluster are orphaned and should be removed with `terraform state rm` before re-applying.

Can I automate removal of stale Terraform state entries after cluster recreation?

Yes, a provided Bash script automates orphaned resource detection and state removal by comparing state entries against cluster resources, eliminating manual `terraform state rm` commands and reducing error risk during recovery.

What precautions should I take when removing entries from Terraform state?

Verify state is clean by running `terraform plan` after removal to confirm no active infrastructure is affected. Use remote state locking to prevent concurrent modifications. Remove only confirmed orphaned entries; incorrect removals can break active resource management.

How can I prevent stale Terraform state after cluster recreation in the future?

Use Terraform data sources for read-only cluster discovery, let GitOps tools like ArgoCD manage application resources independently, and enable remote state locking to enforce safe concurrent state operations across team members.