home / skills / first-fluke / fullstack-starter / terraform-state-manager

terraform-state-manager skill

This skill helps you safely manage Terraform state by importing, moving, or removing resources while preserving stability.

npx playbooks add skill first-fluke/fullstack-starter --skill terraform-state-manager

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.7 KB

---
name: terraform-state-manager
description: Manages Terraform state operations such as importing, moving, and removing resources. Use this skill when the user needs to refactor Terraform state, import existing infrastructure, fixing state drift, or migrate backends without destroying resources.
---

# Terraform State Manager

This skill guides you through safe Terraform state manipulation operations.

## When to Use

- Importing existing cloud resources into Terraform management (`terraform import`)
- Renaming resources or moving them into/out of modules (`terraform state mv`)
- Removing resources from Terraform control without destroying them (`terraform state rm`)
- Migrating state between backends (e.g., local to GCS/S3)
- Fixing state locks or corruption

## Critical Safety Rules

> [!IMPORTANT]
> **ALWAYS** follow these rules to prevent data loss or service downtime.

1.  **Backup First**: Create a backup of your state file (`.tfstate`) before ANY operation.
    ```bash
    terraform state pull > backup.tfstate
    ```
2.  **Plan After**: Run `terraform plan` immediately after any state change to verify the result is a "no-op" (no changes detected) or matches expectation.
3.  **One by One**: Perform operations incrementally rather than in bulk.
4.  **Communicate**: Ensure no one else is running Terraform during maintenance.

## Common Operations

### 1. Importing Resources

Use when you have a resource in the cloud but not in Terraform state.

1.  **Write Config**: Create the `resource` block in your `.tf` files.
2.  **Import**:
    ```bash
    terraform import <resource_address> <cloud_id>
    # Example: terraform import google_storage_bucket.my_bucket my-project-bucket-name
    ```
3.  **Verify**: Run `terraform plan`. It should be empty or show only minor metadata updates.

### 2. Moving Resources (Refactoring)

Use when renaming resources or moving them into modules.

```bash
terraform state mv <source_address> <destination_address>
# Example: terraform state mv google_storage_bucket.old_name module.storage.google_storage_bucket.new_name
```

### 3. Removing Resources

Use when you want to stop managing a resource with Terraform but keep it running.

```bash
terraform state rm <resource_address>
```

### 4. Migrating Backend

Use to change where state is stored.

1.  **Update Config**: Change the `backend` block in `versions.tf` or `backend.tf`.
2.  **Migrate**:
    ```bash
    terraform init -migrate-state
    ```
    Answer "yes" to copy the state to the new location.

## Troubleshooting

- **State Lock**: If a process crashed and left a lock:
    ```bash
    terraform force-unlock <LOCK_ID>
    ```
    *Warning: Be absolutely sure no other process is running.*

Overview

This skill manages Terraform state operations such as importing existing resources, moving resources between addresses or modules, removing resources from state without destroying them, and migrating state backends. It provides step-by-step commands and safety guardrails to refactor state safely in production environments. Use it to fix state drift, migrate backends, or reorganize resource layouts without unintended downtime.

How this skill works

The skill describes the precise Terraform CLI commands and workflow for common state tasks: terraform import, terraform state mv, terraform state rm, and terraform init -migrate-state. It emphasizes pre- and post-operation verification steps like pulling a backup of the .tfstate file and running terraform plan to confirm no unexpected changes. It also covers handling state locks and safe unlock procedures with terraform force-unlock when appropriate.

When to use it

Import existing cloud resources that aren’t yet in Terraform state
Refactor resources by renaming or moving them into or out of modules
Remove resources from Terraform control while leaving the infrastructure intact
Migrate state storage from local files to remote backends such as GCS or S3
Recover from state corruption or stalled locks preventing Terraform runs

Best practices

Always create a state backup before any operation: terraform state pull > backup.tfstate
Perform operations one at a time and validate with terraform plan after each change
Ensure no one else is running Terraform; coordinate maintenance windows
Use versioned remote backends for production state and enable locking when supported
Document each state change in changelogs or runbooks to aid audits and rollbacks

Example use cases

Import an existing Cloud Storage bucket into Terraform to begin lifecycle management
Move a resource into a module after refactoring to keep addresses stable for other resources
Remove a manually managed VM from state while preserving the VM itself
Migrate state from a local file to a GCS backend during team onboarding
Force-unlock state after a CI crash to restore normal deployment workflows

FAQ

What should I do before running terraform import or terraform state mv?

Pull and save a backup of the current state, update or add the matching resource block in your config, then run the CLI command and follow with terraform plan to verify no unintended changes.

Can I migrate state to a new backend without downtime?

Yes—update the backend configuration and run terraform init -migrate-state to copy state. Confirm the new backend and run terraform plan to ensure the migration succeeded.