State Surgery: State List, MV, RM & Native Import Blocks

The Big Idea

As a codebase grows, you will inevitably need to refactor: rename a resource, split a monolithic configuration into child modules, or bring existing legacy infrastructure created by previous teams under Terraform management.

If you simply rename aws_instance.server to aws_instance.frontend_server in your code, Terraform does not know it is the same machine. It plans to destroy the existing server and create a new one from scratch, causing catastrophic production downtime.

State Surgery gives you the tools to guide the engine. With terraform state mv, you rename the internal address in the state file so Terraform realizes the physical server already exists. With Terraform 1.5+ declarative import {} blocks, importing brownfield infrastructure is now version-controlled, auditable, and automated.

Surgical State Operations & Modern Declarative Import

# CLI Command: List all resources tracked in current state
# $ terraform state list
# aws_vpc.core
# aws_subnet.public_a

# CLI Command: Rename resource in state without recreation
# $ terraform state mv aws_vpc.core aws_vpc.main

# CLI Command: Untrack resource from state without deleting cloud resource
# $ terraform state rm aws_s3_bucket.legacy_archive

# Modern Terraform 1.5+ Declarative Import Block:
# Imports an unmanaged existing AWS S3 bucket directly into code
import {
  to = aws_s3_bucket.imported_assets
  id = "existing-company-assets-bucket-2024"
}

# The target resource definition in your code:
resource "aws_s3_bucket" "imported_assets" {
  bucket = "existing-company-assets-bucket-2024"

  tags = {
    MigratedBy  = "terraform"
    Environment = "production"
  }
}