Terraform: How To Rename (Instead Of Deleting) A Resource

Are you trying to rename or move a Terraform resource and Terraform is now trying to re-create your resource rather than referencing the existing one?

It’s a common issue, and the answer is quite straight-forward. Today we’ll cover how you can move a Terraform resource instead of deleting it.

By the end of this article you’ll understand how to rename, instead of deleting a resource and the reasons for how / why it works. 

The Short Answer

If you’re in a hurry and just need the quick answer for how to rename a resource instead of deleting it, here’s the steps:

  1. Define your new resource block.
  2. Use the Terraform move command.

Execute the Terraform move command by passing your old resource name first, followed by your new resource name.

Some important things to note…

  • Do not manually alter your terraform state, only use the CLI commands or you could end up breaking your state and Terraform setup.
  • Enable versioning on your remote state, or take a copy of local state before you make changes to make reverting easier if you make a mistake.
  • Writing the new resource definition in Terraform is mandatory before you can move the state associated with it.

If you were after the short answer, that’s it! You’re good to go.

However, if you’re curious to learn about what the move command does and why you need it in the first place let’s dig into the details…

Understanding Refactoring In Terraform

Refactoring Terraform is less like refactoring code, and more like refactoring a database schema. When you refactor a database schema you create a proposed new structure of the database and then you also write a migration script to explicitly say which data is going to move where.

To refactor Terraform we need the same process.

The reason for refactoring like this is because Terraform’s state acts like a database. There is a good explanation of why Terraform needs state on the Terraform website. But let’s recap it here quickly…

The primary reason Terraform uses state is to map your Terraform defined resources to real resources. When you move a resource, for instance a server into a module, you’re changing the stored name to the resource and you break the relationship between the scripted Terraform and the real world resource.

Let’s take moving a resource into a module, for instance.

Your stored resource name will now change from resource.resource_name to become module.module_name.resource.resource_name.

Whilst the resource name itself hasn’t changed, the full reference to the resource has changed. So you’ll need to tell Terraform about where that resource has moved, using the terraform mv command.

If you’re new to Infrastructure As Code, I’d recommend you check out the article: Infrastructure As Code: An Ultimate Guide.

Refactor All The Terraform!

And that’s all there is to it. Refactoring Terraform like this can be a bit of a pain and it can be fiddly. But it is possible to refactor Terraform without deleting your existing resources—good news!

I hope that helped to clear things up and helps you refactor your existing Terraform. Now you should be able to continue with your refactoring, moving resources into or out of modules, or simply renaming resources with ease.

Speak soon Cloud Native friends!

Lou Bichard