State File in Terraform: What Do You Need to Know?

If you recently started using Terraform as your Infrastructure as Code tool, you might wonder how TF knows which resources need to be created, deleted, or modified when you run your code.

The answer is not a magic — the agent behind this management is the state file.

How does the state file work?

Every time we deploy our infrastructure with terraform apply, a file named terraform.tfstate is created. This file includes all of the information about the resources that are managed by TF and that are currently deployed in your cloud provider.

You can navigate on the file to see a key with the name of resources. It is an array that lists all elements created with the configuration file (after doing terraform apply).

If you create an EC2 instance in AWS, for example, your tfstate file will look like this:

What is the role of the state file when Terraform selects the actions to perform? To better understand how this works, it is important to discuss the current and desired state.

Current state

The terraform.tfstate file is responsible for storing the current state of the infrastructure, including all of the information about resources currently deployed in your cloud provider (after the terraform apply command has been run).

Desired state

All code in the main.tf file, or in any configuration file with the “.tf” extension, corresponds to the desired state. This is where you specify the resources that you expect to be created in the cloud, and where the magic occurs.

Terraform is going to compare both states (the current state and the desired one). If there is a difference between them, Terraform will make the necessary changes so that the current state is equal to the desired state. TF shows the result of the comparison when we execute the terraform plan command in the terminal.

The example of using the terraform plan command

Let’s say that you have a “t2.micro” EC2 instance already created using Terraform, and your state file looks something like:

That is your current state.

Now, you want to change the instance type from “t2.micro” to “t2.nano,” so your desired state (Terraform configuration file) would need to be changed to something like:

Then, you would run terraform plan and the output would be:

As you can see, the output of terraform plan comes from the TF comparison between your state file and the desired state.

How to refresh the state

But what if we modify a resource directly in the cloud provider interface without using terraform apply (AWS Console for instance)? Let's say that we changed the EC2 instance type from “t2.micro” to “t2.large,” how will our local terraform.tfstate be modified to match those remote changes?

Terraform has a solution for that. We just need to run the terraform refresh command, and the configuration that is currently running in the cloud provider will be updated in the local terraform.tfstate file.

Keep in mind, however, that if your TF configuration file does not include the change that you pulled using terraform refresh, your EC2 instance will again be set to “t2.micro” in the next terraform apply.

Conclusion

The state file is a core concept of Terraform workflow. Understanding how it works behind the scenes, and how it is used during the deployment flow, will help you troubleshoot complex scenarios and understand unexpected results.

If you are planning to be certified as Terraform Associate, make sure you’ve successfully covered this concept.