terraform-state-operations

# Terraform State Operations

## Overview

State operations modify Terraform's understanding of infrastructure without changing actual resources. These are dangerous because mistakes can orphan resources or cause Terraform to recreate existing infrastructure.

**Announce at start:** "I'm using the terraform-state-operations skill for safe state surgery."

## CRITICAL: Pre-Operation Safety

### 1. Create State Backup

**ALWAYS create a backup before ANY state operation:**

```bash
# Create timestamped backup
BACKUP_NAME="state-backup-$(date +%Y%m%d-%H%M%S).tfstate"

# For local state
cp terraform.tfstate "$BACKUP_NAME"

# For remote state (S3 example)
terraform state pull > "$BACKUP_NAME"

echo "Backup created: $BACKUP_NAME"
```

### 2. Document the Operation

Before proceeding, create a record:

```markdown
## State Operation Record

**Date:** [timestamp]
**Environment:** [env name]
**Operator:** [user]
**Reason:** [why this operation is needed]

### Planned Operations
1. [operation 1]
2. [operation 2]

### Backup Location
- Local: [path]
- Remote: [if applicable]

### Rollback Plan
[How to restore if something goes wrong]
```

### 3. Get User Approval

Present the plan and **require explicit approval** before executing.

## State Operations Guide

### terraform state mv

**Use case:** Rename resources, reorganize modules, refactor code

```bash
# List current resources
terraform state list

# Move/rename a resource
terraform state mv aws_instance.old_name aws_instance.new_name

# Move into a module
terraform state mv aws_instance.web module.web.aws_instance.this

# Move between modules
terraform state mv module.old.aws_instance.web module.new.aws_instance.web
```

**Verification after mv:**
```bash
# Should show no changes
terraform plan
```

### terraform state rm

**Use case:** Remove from state without destroying actual resource (adopting externally-managed resources)

```bash
# Remove single resource
terraform state rm aws_instance.legacy

# Remove module
terra