Safely Rename a Terraform Resource Without Destroying AWS Infrastructure

Core Safety Highlights

The Complete Terraform Example

Suppose the existing resource is named aws_instance.webserver and you want to rename it to aws_instance.app. Change the resource block and add a declarative moved block in main.tf.

# Before:
# resource "aws_instance" "webserver" {
#   ...
# }

# Fetch dynamic AMI
data "aws_ami" "amazonlinux" {
  most_recent = true
  owners      = ["amazon"]

  filter {
    name   = "name"
    values = ["al2023-ami-2023.*-x86_64"]
  }
}

# Declarative Moved Block - safely redirects state tracking address
moved {
  from = aws_instance.webserver
  to   = aws_instance.app
}

# Renamed Resource Block
resource "aws_instance" "app" {
  ami                         = data.aws_ami.amazonlinux.id
  instance_type               = "t2.micro"
  associate_public_ip_address = true
  vpc_security_group_ids      = [aws_security_group.webserver_ig.id]
  key_name                    = aws_key_pair.shankey.key_name
}

Code Breakdown

The moved block

The moved block tells Terraform that the object previously tracked at aws_instance.webserver is now tracked at aws_instance.app. It is a state-address change, not an instruction to destroy and recreate the EC2 instance.

moved {
  from = aws_instance.webserver
  to   = aws_instance.app
}

Why this protects the real AWS resource

Terraform maintains a mapping between configuration addresses and real cloud infrastructure. A resource rename changes the configuration address. The moved block preserves the mapping by explicitly telling Terraform that the old address and new address refer to the exact same physical object.

Deployment & Execution Commands

Follow these steps in sequence to format, validate, plan, apply, and inspect your renamed resource state address:

# 1. Format the configuration
$ terraform fmt

# 2. Validate the configuration syntax
$ terraform validate

# 3. Review the proposed state move (verify no destroy/create)
$ terraform plan

# 4. Apply the state rename
$ terraform apply

# 5. Confirm the new resource address exists in state list
$ terraform state list

# 6. Optional: inspect the specific state entry details
$ terraform state show aws_instance.app

Expected Plan Output

A safe rename should show a move operation rather than a destroy/create operation. Depending on Terraform version and configuration, the plan will describe the resource as moving from the old address to the new address:

# Conceptually:
# aws_instance.webserver has moved to aws_instance.app

# You should NOT see:
# -/+ aws_instance.webserver
# +   aws_instance.app

Alternative & Important Safety Checks

Alternative — terraform state mv

For a one-time manual state operation, you can move the state address directly via CLI:

$ terraform state mv aws_instance.webserver aws_instance.app
$ terraform plan

Use this approach when you intentionally want to update the state immediately. For a rename that should be represented in version-controlled Terraform configuration, a moved block is usually easier for a team to review and reproduce.

Important Safety Checks

• Backup State Back up or protect your Terraform state before manual state operations, especially when using remote state.
• Plan First Always run terraform plan before applying the change to verify Terraform's intent.
• Verify Identity Confirm the old and new addresses refer to the exact same logical infrastructure.
• Scope Changes Do not change unrelated resource arguments during the rename unless you intend to modify the AWS resource too.
• Stop on Destroy If Terraform proposes a destroy/create replacement, stop and investigate before applying!

Quick Reference Guide