Refactor Safely: moved, removed, and state mv

1. 1

   Why rename?

   In Stage 4 ShopLite gets a second bucket for user uploads. assets is then ambiguous, so the team agrees on static_assets. You'll also move the bucket code out of main.tf into storage.tf. The file move is free, because Terraform doesn't care about file names; the rename is the part that needs care.
2. 2

   Rename the three resources in a new storage.tf

   Create storage.tf with the renamed blocks and delete main.tf. Note the references inside also change to aws_s3_bucket.static_assets.id.

   resource "aws_s3_bucket" "static_assets" {
     bucket = local.assets_bucket_name
   
     tags = {
       Name = "${local.name_prefix}-assets"
     }
   }
   
   resource "aws_s3_bucket_versioning" "static_assets" {
     bucket = aws_s3_bucket.static_assets.id
   
     versioning_configuration {
       status = "Enabled"
     }
   }
   
   resource "aws_s3_bucket_public_access_block" "static_assets" {
     bucket = aws_s3_bucket.static_assets.id
   
     block_public_acls       = true
     block_public_policy     = true
     ignore_public_acls      = true
     restrict_public_buckets = true
   }

3. 3

   Look at the plan WITHOUT moved blocks first

   Update outputs.tf to reference aws_s3_bucket.static_assets, then plan. This is the plan a careless refactor would produce: three destroys and three creates, for a change that was only meant to rename things. Don't apply it.

   terminalcopy cmd

   $ sed -i 's/aws_s3_bucket.assets/aws_s3_bucket.static_assets/' outputs.tf

   terraform plan | tail -n 1

   ── expected output ──

   Plan: 3 to add, 0 to change, 3 to destroy.

4. 4

   Add moved blocks

   One block per renamed resource. Keep them in a dedicated refactors.tf with a comment, so reviewers see the intent and the blocks are easy to delete later.

   # 2026-09 rename: "assets" → "static_assets" (uploads bucket arrives in Stage 4).
   # Safe to delete once every environment has applied it.
   
   moved {
     from = aws_s3_bucket.assets
     to   = aws_s3_bucket.static_assets
   }
   
   moved {
     from = aws_s3_bucket_versioning.assets
     to   = aws_s3_bucket_versioning.static_assets
   }
   
   moved {
     from = aws_s3_bucket_public_access_block.assets
     to   = aws_s3_bucket_public_access_block.static_assets
   }

5. 5

   Plan again: moves only

   Now the plan lists each move and the summary is all zeros. Apply it; only state changes.

   terminalcopy cmd

   $ terraform apply

   ── expected output ──

   # aws_s3_bucket.assets has moved to aws_s3_bucket.static_assets

   resource "aws_s3_bucket" "static_assets" {

   id = "shoplite-dev-assets-3f9a"

   # (11 unchanged attributes hidden)

   }

    

   # aws_s3_bucket_public_access_block.assets has moved to aws_s3_bucket_public_access_block.static_assets

   ...

   # aws_s3_bucket_versioning.assets has moved to aws_s3_bucket_versioning.static_assets

   ...

    

   Plan: 0 to add, 0 to change, 0 to destroy.

   ...

   Apply complete! Resources: 0 added, 0 changed, 0 destroyed.

6. 6

   Hand a resource over with a removed block

   Create a throwaway SSM parameter that, in our story, the data team will manage in their own repo from now on. Apply it, then replace the resource block with a removed block. The plan says it 'will no longer be managed by Terraform', and nothing is destroyed.

   First add and apply the resource block; then swap it for the removed block and apply again.

   # Step A — apply this once:
   resource "aws_ssm_parameter" "reporting_endpoint" {
     name  = "/shoplite/dev/reporting-endpoint"
     type  = "String"
     value = "https://reports.internal.example.com"
   }
   
   # Step B — delete the block above and add:
   removed {
     from = aws_ssm_parameter.reporting_endpoint
   
     lifecycle {
       destroy = false
     }
   }

   terminalcopy cmd

   $ terraform apply

   ── expected output ──

   # aws_ssm_parameter.reporting_endpoint will no longer be managed by Terraform

   resource "aws_ssm_parameter" "reporting_endpoint" {

   name = "/shoplite/dev/reporting-endpoint"

   ...

   }

    

   Plan: 0 to add, 0 to change, 0 to destroy.

    

   Warning: Some objects will no longer be managed by Terraform

    

   If you apply this plan, Terraform will discard its tracking information for

   the following objects, but it will not delete them:

   - aws_ssm_parameter.reporting_endpoint

   ...

   Apply complete! Resources: 0 added, 0 changed, 0 destroyed.

7. 7

   Confirm the parameter still exists, then tidy up

   AWS still has the parameter; Terraform no longer tracks it. Delete it by hand now, since it was only for the exercise, and remove the removed block too.

   terminalcopy cmd

   $ aws ssm get-parameter --name /shoplite/dev/reporting-endpoint --query Parameter.Value --output text

   aws ssm delete-parameter --name /shoplite/dev/reporting-endpoint

   ── expected output ──

   https://reports.internal.example.com

Make each change, run the command, and read the error before revealing the diagnosis. Recognising these messages on sight is what makes you fast on a real team. Undo the change afterwards.