In this short article, we will take a look at the terraform refresh command.
We will cover:
Warning: This command is deprecated because its default behavior is unsafe if you have misconfigured credentials for any of your providers.
By running terraform refresh after making manual changes to your infrastructure resources, you ensure that your Terraform state file is up-to-date and reflects the current state of your infrastructure resources. Terraform refresh will not alter any of your real infrastructure but will alter the Terraform state file.
Because the command is included in plan and apply, it is typically not needed to be run separately. In fact, Hashicorp recommends you do not use refresh, unless for backward compatibility reasons, for use with Terraform versions prior to v0.15.4.
When creating a terraform plan or running terraform apply, a refresh of the state of existing objects is automatically performed by Terraform (which is the default behavior).
The terraform refresh command is designed to reconcile any differences from the drift between your infrastructure and the information contained in the state file. It will only take into account objects already in the state file. Any objects outside of the state will not be considered and will need to be imported into the state to become managed by Terraform.
For Terraform versions v0.15.4 and above, the --refresh-only option was introduced to the plan and apply commands.
The terraform refresh command is essentially an alias to the terraform apply -refresh-only -auto-approve in v0.15.4 and above.
Excluding the auto-approve option will prompt you for confirmation before the refresh is performed.
You can also check out our Terraform CLI Cheat Sheet.
Note: New versions of Terraform are 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 expands on Terraform’s existing concepts and offerings. It is a viable alternative to HashiCorp’s Terraform, being forked from Terraform version 1.5.6.
To further explain how terraform refresh works, first create a resource using Terraform, such as a VNET with some subnets.
Next, modify the resource manually through the portal. For example, you could change the address space of one of your subnets.
Run terraform refresh command to reconcile the state of your VNET resources with their current state in the remote backend. This will update your local Terraform state file with the current state of the resource in the remote backend.
Next time you run terraform plan Terraform will detect the changes you made manually (outside of Terraform) and generate an execution plan that reflects the current state of your infrastructure resources.
By running terraform refresh after making manual changes to your infrastructure resources, you ensure that your Terraform state file is up-to-date and reflects the current state of your infrastructure resources. This helps to prevent any conflicts or inconsistencies that might occur when Terraform is used to manage the same resources as other tools or manual changes.
It is not usually necessary to run terraform refresh independently.
We encourage you also 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. It supports Git workflows, policy as code, programmatic configuration, context sharing, drift detection, and many more great features right out of the box. You can check it for free, by creating a trial account.
Terraform Management Made Easy
Spacelift effectively manages Terraform state, more complex workflows, supports policy as code, programmatic configuration, context sharing, drift detection, resource visualization and includes many more features.
