How to Remove a Resource From Terraform State File

In this blog post, we will take a look at the terraform state rm command, explaining what it is, and how to use it.  We will explain why you would want to remove a resource from the state file. 

The terraform state rm command explained

The terraform state rm is a Terraform command that allows you to remove a resource from the Terraform state, which is helpful in situations where you want to disassociate a resource from your configuration without actually destroying the resource in your infrastructure. 

When you remove a resource from the state file it allows the resource to still exist but for you to manage it another way. 

After running the terraform state rm command Terraform will remove the specified resource from its state, and from then on Terraform will no longer track, or manage or attempt to update that resource. 

Remember this operation only removes the resource from the state it doesn’t delete the actual resource from your infrastructure. 

Why remove a resource from the Terraform state file?

There are a few use cases when you’d want to remove a resource from the Terraform state file. 

• Resource decommissioning: You are decommissioning a specific resource within your infrastructure and you want to keep your state file clear and remove the resource’s history.  Removing it won’t delete the resource, but it will keep your state file configuration up to date and allow you to decommission the resource according to your normal processes. 
• Cleanup: Over time your state file might become cluttered with resources that are no longer relevant, using the terraform state rm command can allow you to remove unused or old resources and help improve the reliability of your state file. 
• Change management tool: There might be a change in direction as to what management tool you are using to manage resources and you are no longer going to use Terraform for a type of resource.  Removing that resource from the state file will ensure there are no unintended changes or conflicts. 

terraform state rm syntax

The terraform state rm has a couple of options attached to the command that you can use: 

• -dry-run: If set this will show you what would be removed but doesn’t remove anything. 
• -backup=PATH: This tells the command where to write the backup state to. 
• lock=FALSE: This would instruct Terraform to not hold a state lock during the operation of the command, this can be dangerous if others are running commands at the same time. 
• -lock-timeout=0s:  This sets the time for when the command should retry a state lock. 
• -state=PATH: This tells the command where the state file is, this is useful if you don’t have the state file in the default location. 
• -ignore-remote-version: This instructs the command to continue even if the remote and local Terraform versions are incompatible. 

How to delete a single resource from your Terraform state file

Let’s walk through the process of removing a single resource from your state file. 

The first step is to identify the resource.  To do this we will use the terraform state list command.  This will list all the resources and modules that are in the state file. 

I have a simple Terraform template that creates an Azure resource group and when I run the terraform state list command the output is:

To remove the resource group from the Terraform state file I would use the command: 

Terraform state rm “azurerm_resource_group.rg”

Once the resource has been removed you can run the terraform apply command to verify the resource is no longer listed in the plan output and is no longer managed by Terraform. 

In my case, the existing resource group is no longer listed in the plan output and a new one would be created.

Backup your state file while using the terraform state rm command

Whenever you are about to undertake a destructive operation it’s important to take a backup to undo it if necessary. 

When you are going to use the terraform state rm command it is no different. 

There are a couple of ways you can take a copy of your state file. 

The first way is to simply take a copy of the .tfstate file and store it safely. 

The second is to take a Terraform State Snapshot using the terraform state pull command.  This command will take a snapshot of your current state before you make the changes. 

To use this command you would type:

terraform state pull > state_backup.json

Conclusion

Terraform should manage your state file for you, updating resource status as you manage your infrastructure. 

However, if you wish to remove a resource from being managed by the Terraform and exclude it from the state file then the terraform state rm command is a good one to know and understand.