Lab: state mv and state rm

Objective

By the end of this lab, you will have:

• Used state mv to rename a resource in state.
• Used state rm to remove a resource from state.
• Verified the plan is empty after each operation.
• Recognised the production risks of state-mutating commands.

Requirements

• A Linux or macOS workstation with shell access.
• The Terraform CLI 1.9.x or later installed.

Scenario

You have a configuration that needs to rename a resource and remove a resource from state. The state-mutating commands are production tools that require careful planning.

Tasks

Task 1: Create the working directory

mkdir -p ~/rb-state-mv-rm-lab
cd ~/rb-state-mv-rm-lab

Task 2: Initial configuration

Create main.tf:

terraform {
  required_version = ">= 1.9.0"
  required_providers {
    local = {
      source  = "hashicorp/local"
      version = "~> 2.5"
    }
  }
}

resource "local_file" "one" {
  filename = "${path.module}/one.txt"
  content  = "One\n"
}

resource "local_file" "two" {
  filename = "${path.module}/two.txt"
  content  = "Two\n"
}

Task 3: Apply the configuration

terraform init
terraform apply

Verify the state:

terraform state list

Expected:

local_file.one
local_file.two

Task 4: Rename the resource with state mv

terraform state mv local_file.one local_file.first

The state is updated.

terraform state list

Expected:

local_file.first
local_file.two

Task 5: Update the configuration to match the state

Update main.tf:

resource "local_file" "first" {
  filename = "${path.module}/one.txt"
  content  = "One\n"
}

Task 6: Verify the plan is empty

terraform plan

The plan should be empty.

Task 7: Remove the resource with state rm

terraform state rm local_file.two

The state is updated.

terraform state list

Expected:

local_file.first

Task 8: Update the configuration

Update main.tf:

resource "local_file" "first" {
  filename = "${path.module}/one.txt"
  content  = "One\n"
}

# Note: local_file.two is removed; it will be created on next apply

Wait, this would make terraform apply recreate local_file.two. We want to remove two from state but NOT from the real world.

terraform plan

The plan should NOT propose to create local_file.two.

Task 9: Investigate

The terraform plan should now propose to recreate local_file.two because the configuration has it but the state doesn’t.

To make the plan empty, we need to also remove the resource from the configuration:

Edit main.tf:

resource "local_file" "first" {
  filename = "${path.module}/one.txt"
  content  = "One\n"
}
# Comment out or remove local_file.two

terraform plan

The plan should be empty.

Validation

The lab is successful if:

• The state mv renamed the resource in state.
• The state rm removed the resource from state.
• The plan is empty after each operation.

Expected Outcome

At the end of the lab:

+---------------------------------+
| ~/rb-state-mv-rm-lab/              |
|   .terraform/                    |
|   .terraform.lock.hcl            |
|   one.txt                         |
|   main.tf                        |
+---------------------------------+

The two.txt file is still on disk (the rm didn’t delete it). The state is empty for the rm’d resource.

Cleanup

cd ~/rb-state-mv-rm-lab
rm -rf .terraform *.txt main.tf

What You Learned

You learned the state-mutating commands:

• state mv renames a resource in state. The real-world resource is unchanged.
• state rm removes a resource from state. The real-world resource is unchanged.
• Both commands require careful planning. A wrong operation binds the wrong resource to the wrong state.
• Verify the plan is empty after each operation. The verification is the safety net.
• Document the operation. The audit trail is mandatory.