An Introduction to the Terraform State File

The purpose of the Terraform state file can be confusing, even for the most expert DevOps engineers.


The purpose of the Terraform state file can be confusing, even for the most expert DevOps engineers. You may have noticed that the aptly named “tfstate file” appears when you’re making changes to resources or the configuration. In fact, it’s required by Terraform, and, according to HashiCorp, “cannot function without it.” The purpose of our introductory article is to save you from getting lost in a sea of files, without having any understanding of what is happening, how to secure them, and what you can do with them. In this article, we’ll go over:

  • What is the Terraform state file?
  • Most Common Terraform State File Commands
  • Remote vs. Local

Let’s get started!

Note: If you’re interested in learning more or want to have your questions answered with 1-on-1 guidance, join our InfraCode Slack to gain valuable help from our community of experts.

What is a Terraform State File?
link icon

Your configuration is stored with the ending “.tfstate”. Below, you can see the sample screenshot of a list of files that were created after using the “apply” command. As you can see, it is also backed up to keep your work secure.

Here’s the interesting part: the Terraform state file is updated simultaneously to you creating a new resource. Here’s how it works: Essentially, a remote object for a particular resource is created on your system. The link between the remote object and the actual configuration is recorded. The next time that you update a resource on your configuration, a new remote object is created. The new object is, again, mapped against the resource in the tfstate, and the previous remote object is deleted. Therefore, every time you update a resource, you’re also creating a new remote object (whether you realize or not).

Source: “DevOps 101” by Rafael Belchoir

While it’s clear that the tfstate is important during the “apply” and “plan” commands, did you know that it also appears again when you hit the “destroy” command? Besides resource changes, the tfstate file also tracks resource dependencies. When performing the “destroy” action, it helps determine the order in which the resources are destroyed.

Most Common Terraform State File Commandslink icon

Additionally, the inspection and the modification of Terraform state files is also allowed, by using the command “terraform state”. Within this command are the following subcommands:

Any subcommand that modifies the tfstate always creates/writes backup information. They’re mandatory for every modification command and cannot be disabled.

While the allowed modifications to the tfstate file are quite limited and basic, we recommend that you don’t bother modifying them if you’re still new to Infrastructure as Code. Why do we suggest that you skip these actions?

As we mentioned previously, there is an inherent link maintained between every configuration resource and a remote object in the tfstate. However, if you begin to modify or delete any of the links in the Terraform state file, then, unfortunately, going forward, it will be your responsibility to manually maintain the links, as well as modify/delete objects. Why give yourself extra work as a beginner when you can focus on the basics? Note: If you are a beginner, check out our “Best Terraform Tutorial Guides” for a brief overview.

Remote vs. Locallink icon

Imagine a scenario where you have a team of 4 DevOps professionals, dedicated to building and maintaining your infrastructure. One team member updates the configuration, and everything is going as planned. The “apply” command is performed, which updates the Terraform state file on the user’s local system, leaving the user who made the changes with the updated tfstate file. But, the rest of your team is left with the old work, resulting in configurational differences (and overall confusion).

The remote state solves this small issue that can lead to major complications. You can store, read, and write the tfstate file with cloud storage, which can easily be shared with your complete team. Your work can be stored with cloud providers such as Google Cloud Storage, Amazon S3, and Terraform Cloud.

With remote tfstate, another feature called “locking” is offered. Any operation that could write the tfstate automatically induces this operation. As the name insinuates, your work becomes locked and will not become corrupted. This is a backend process and if it fails, it does not let you continue with your configuration changes.

When you create a configuration, there may be resources with sensitive information such as passwords or user tokens. Locally, this data is stored as plain text. However, remotely, data can be stored in an encrypted format, making it more secure.

Next Stepslink icon

While the tfstate may be a bit confusing, we hope that you can see some of the advantages of working in a remote state. As we mentioned earlier, if you’re a beginner, it’s far easier to skip modifications and focus on other core components of Terraform. If you’re interested in learning more about the Terraform state file, or want to have your questions answered with 1-on-1 guidance, join our InfraCode Slack to gain valuable help from our community of experts.

P.S. A note from the teamlink icon

Hi everyone! Considering the success of our first post with Faun, we’ve decided to provide you with the comprehensive Terraform information you’re looking for. We understand the pain you’ve experienced searching for resources. The reason we understand is because we were there too. We understand that the tools around HashiCorp are great, but smaller organizations needed to be empowered to use their tools. It can be difficult to find the time to seek out these resources--and some of these resources are not catered specifically to smaller organizations. We are trying to create content that not only solves this problem, but clearly lays out foundational concepts in an easy-to-use, practical manner. Since there is demonstrated latent demand for better, clearer explanations of core Terraform concepts, we’ve decided to begin a series of articles diving deep on the fundamentals without all the drag of reading the complex, esoteric descriptions in HashiCorp’s documentation. While we believe there’s a time and place to go in-depth, we also understand that the average beginner is looking for clear, carefully laid out information that is both tangible and immediately usable. We’re here to try and make your lives easier. Once again, thanks for joining us!