In this article, we will take a look at the terraform state rm command, explaining what it is and how to use it, showing basic syntax and the available options. We will explain why you might want to remove a resource from the state file and show how to remove single instances as well as multiple resources that have count or for_each set or are contained in the configuration as child modules.
We will cover:
- What is the terraform state rm command?
- Why remove a resource from the Terraform state file?
- How to remove a single resource from the Terraform state file?
- How to remove multiple resources from the Terraform state file?
- How to remove all instances of a resource in a module?
- How to remove the S3 bucket or EC2 instance from the Terraform state file?
- How to save backup when using terraform state rm?
- Use terraform state rm with -path flag
The terraform state rm is a Terraform command that allows you to explicitly remove a resource from the Terraform state, which is useful in scenarios where you want to disassociate a resource from your configuration without destroying the actual resource in your infrastructure. This can be helpful in situations such as when you no longer want Terraform to manage a particular resource, but you still want the resource to exist and be managed manually or by other means.
After running terraform state rm, Terraform will remove the specified resource from its state, which means that Terraform will no longer track, manage, or attempt to update that resource.
Keep in mind that this operation only removes the resource from the state; it does not destroy or delete the actual resource in your infrastructure.
Command options
The basic syntax of the terraform state rm command:
terraform [global options] state rm [options] ADDRESS...Options for the command include the following:
-dry-run— If set, prints out what would’ve been removed but doesn’t actually remove anything.-backup=PATH— Path where Terraform should write the backup state.lock=false— Don’t hold a state lock during the operation. This is dangerous if others might concurrently run commands
against the same workspace.-lock-timeout=0s— Duration to retry a state lock.-state=PATH— Path to the state file to update. Defaults to the current workspace state.-ignore-remote-version— Continue even if remote and local Terraform versions are incompatible. This may result in an unusable workspace and should be used with extreme caution.
Let’s take a look at some use cases:
Change of management
You might want to hand over the management of a resource to a different tool or process. Removing it from Terraform’s state ensures that Terraform will no longer attempt to manage the resource, reducing the risk of conflicts and unintended changes.
Resource decommissioning
If you’re decommissioning a resource from your infrastructure, you can use terraform state rm to cleanly disassociate that resource from your Terraform configuration. It allows you to keep your configuration clean and remove the resource’s history from your state file. It will not remove the actual resource but rather just the entry from the Terraform state file.
Resource re-creation
You might want to re-create a resource with a different configuration or settings. Removing it from the state file allows you to do this without Terraform thinking the resource already exists.
Cleanup and organization
Over time, your state file can become cluttered with resources that are no longer relevant to your infrastructure. Removing unused or obsolete resources can help improve the organization and readability of your Terraform state.
Migration or transition
When transitioning from one infrastructure management tool to Terraform, or vice versa, you may need to remove resources from Terraform’s state to avoid conflicts and ensure a smooth transition.
In the following example, we will show step-by-step how to remove a resource from the state file.
1. Identify the resource
You can view and list the available resource addresses in your state file using terraform state list. The command will list all resources and modules in the state file matching the given addresses (if any). If no addresses are given, all resources and modules are listed.
If you want to remove a particular resource, you can specify it to return the address, e.g. for an Azure web app configured in your main.tf file as a resource called azurerm_app_service.example, you can then reference that as follows:
terraform state list "azurerm_app_service.example"2. Remove the resource using terraform state rm
Once you have identified the resource to be removed from the state file, go ahead and run
terraform state rm "azurerm_app_service.example"3. Run terraform apply
Once the resource has been removed, you can run terraform apply to verify the resource is no longer listed in the plan output and will no longer be managed by Terraform.
If you give the address of a resource that has “count” or “for_each” set, all of the instances of that resource will be removed from the state.
If you want to remove a single instance from the state, you can specify it for count using the index:
# Remove a resource with "count"
terraform state rm "azurerm_app_service.example[1]"Or if it has for_each set:
# Remove a resource with "for_each"
terraform state rm "azurerm_resource_with_for_each.example[\"name1\"]"If you give the address of an entire Terraform module, then all of the instances in that module and any of its child modules will be removed from the state.
# Remove an entire module and its instances, including child modules
terraform state rm "module.web_apps"To remove an S3 bucket from the Terraform state file, check how it is defined in your Terraform configuration. In this example with have a simple bucket defined as aws_s3_bucket.example.
resource "aws_s3_bucket" "example" {
bucket = "example-bucket"
acl = "private"
}We can then issue the terraform state rm "aws_s3_bucket.example" to remove it.
To remove an EC2 instance from your Terraform state file, check the configuration file for the resource block, in this example defined as aws_instance.example.
resource "aws_instance" "example" {
ami = "ami-0123456789abcdef0"
instance_type = "t2.micro"
# other instance configuration
}And issue the command to remove it from state terraform state rm "aws_instance.example".
When you use terraform state rm to remove a resource from the Terraform state file, it’s essential to take backups or precautions to ensure you can recover from potential issues or unintended changes. Terraform state is a critical part of your infrastructure management, and modifying it should be done with care.
- Make a backup copy of the Terraform state file before modifying it. You can simply copy the
.tfstatefile and store it safely. - You can also use the
-backup=PATHflag to create a backup of the state file that includes the removed resource. This can be helpful if you need to recover it. For example:
terraform state rm -backup=path/to/backup.tfstate "azurerm_app_service.example"3. You can also take a Terraform State Snapshot using the terraform state pull command to create a snapshot of your current state before making any changes. This can be useful for reference or recovery if needed.
terraform state pull > terraform_state_backup.jsonWhen using the default local backend, the state file is stored in the working directory, and the path is simply terraform.tfstate.
If you want to override this and point it to a different state file on the command line, you can use the -state=PATH flag.
terraform state rm "azurerm_app_service.example" -state=path/to/your/statefile.tfstateModifying the Terraform state file is usually not necessary, as Terraform manages the resources contained within it and removes them as necessary.
However, You can use terraform state rm in the less common situation where you wish to remove a binding to an existing remote object without first destroying it, which will effectively make Terraform “forget” the object while it continues to exist in the remote system. You should use the command with caution, as errors could make your system unusable, and always take a backup of the state file before modifying it directly!
You can also use a tool such as Spacelift to manage your state for you.
We encourage you to explore how Spacelift makes it easy to work with Terraform. If you need any help managing your Terraform infrastructure, building more complex workflows based on Terraform, and managing AWS credentials per run, instead of using a static pair on your local machine, Spacelift is a fantastic tool for this.
Note: New versions of Terraform will be placed under the BUSL license, but everything created before version 1.5.x stays open-source. OpenTofu is an open-source version of Terraform that will expand on Terraform’s existing concepts and offerings. It is a viable alternative to HashiCorp’s Terraform, being forked from Terraform version 1.5.6. OpenTofu retained all the features and functionalities that had made Terraform popular among developers while also introducing improvements and enhancements. OpenTofu works with your existing Terraform state file, so you won’t have any issues when you are migrating to it.
Manage Terraform Better and Faster
If you are struggling with Terraform automation and management, check out Spacelift. It helps you manage Terraform state, build more complex workflows, and adds several must-have capabilities for end-to-end infrastructure management.
