Should You Commit the Terraform .tfstate File to Git?

I’m guessing you’ve started working with Terraform and you’re staring at that weird looking state file Terraform just outputted wondering if it’s safe to commit the file to Git (or some other source control)?

A key to understanding Terraform is understanding how to manage your state. Today we’re going to discuss the in’s and out’s of the state file, and answer the pressing question: Should you commit the Terraform .tfstate file to Git?

By the end of this article you’ll understand what a TF state file is, why Terraform needs it, how you can manage it, and ultimately whether you should commit it to git (or not!)

The short answer to: “Should I commit Terraform state to git?” is: no.

Why? Because Terraform state can contain sensitive information which should not be stored in source control. Additionally if Terraform executes on different state files (i.e on two separate machines) it might break your Terraform setup. The solution? Setup a Terraform backend.

Okay — that’s the (very!) short answer incase you’re in a rush. But I assume you might be curious about why this is the recommendation configuration and what is so bad about committing Terraform state to Git?

Sol et’s dive deeper into the details of what Terraform state is and why you should really be storing it in a backend and not committing state to git.

What Is Terraform State?

Terraform State File

So, naturally the first question for us to explore is: What is Terraform state?

Simply put, Terraform state is used to map your real world infrastructure to the resources you’ve defined in your Terraform configuration.

The State file keeps track of which resource configuration maps to which real world resource. The state also stores metadata about those resources such as the dependency order for creating the resources.

Ultimately you can think of Terraform state as just a big JSON array of your resources (because that’s pretty much what it is).

Okay, so that makes sense, but it still doesn’t answer our question about why we shouldn’t commit this file to Git? What’s the big deal?

Why You Shouldn’t Commit State To Git

There are two main reasons to avoid committing state to Git.

Let’s take a look at them…

1. State Has Sensitive Information

The generated state file from Terraform can end up with encryption keys, and infrastructure passwords within it that are not safely encrypted. Storing passwords etc in plain text in a repository is bad practice, anyone who gets access to your repository can gain that sensitive information.

2. Incorrect Or Stale State

When Terraform is executed, it executes against the state file. When state files are checked in to Git you run the risk of running Terraform against an old state file. For instance, if you forget to pull the latest changes the state file on your machine could be different to another team members.

Okay, so that answers why we shouldn’t commit state to Git. But it might leave you wondering: “Okay, so if committing the state file isn’t the best option, what should I do?”. And the answer to that question is: Terraform backends. Let’s take a look at what they are and how they help us…

The Alternative To Local State: Backends

Terraform Backend Configuration

A Terraform backend is a configuration that you can set which tells Terraform where to store your state and also manages state locking (more on this in a moment!). With a backend setup, state is pushed to a remote location and can be accessed by a whole team simultaneously.

However, running Terraform simultaneously could lead to bad outcomes with many machines manipulating the state file at the same time. And that’s why most backend configurations also support “locking”. With locking you can ensure only one person can run executions against the state file at once.

Backends are available in different technologies such as Azure and AWS. How they work on each implementation differs but the functionality remains the same. You can configure a backend with a small code block which is added to any of your terraform .tf files. However typically it’s stored in a file called backend.tf or simply in your main.tf

I Already Stored State in Git — Help!?

Copy Local Terraform State To Remote State

So if you’re reading this article thinking: “Oh no, but I’ve already committed my state to git, what should I do?” then don’t fear, swapping configuration over to a backend is quite a simple process. All you need to do is the following…

Setup a Terraform Backend

Add a backend configuration — Choose from the different configurations in your cloud provider.
Run terraform init — This will prompt Terraform to validate your configuration with your backend.
Push the state to your backend — Terraform asks you whether you want to push your local state to your newly configured backend.

For a more comprehensive Terraform backend setup walkthrough, checkout the article: The Ultimate Terraform Workflow: Setup Terraform (And Remote State) With Github Actions

Terraform: The Right Way!

Hopefully today’s article helped you to understand what Terraform state is, and why you shouldn’t commit it to Git. When you gain a better understanding of what Terraform state really is, and why it’s useful working with Terraform starts to demystify and you realise it’s quite a simple technology.

But regardless — you’re now one step closer to getting a comprehensive understanding of Terraform by understanding what Terraform state is, why it’s important and how backends solve the problems introduced when you commit your tfstate file to git.

Speak soon Cloud Native friend!

Author
Recent Posts

Lou Bichard

Hey I'm Lou! I'm a Cloud Software Engineer From London. I created Open Up The Cloud to help people get their start and grow their careers in cloud. I edit the monthly Open Up The Cloud Newsletter which I think you'd really like. You can find me on Twitter or LinkedIn , I'm always happy to chat. When I'm not writing you can usually find me picking up heavy things and putting them down, or riding two wheels (sometimes with an engine, sometimes not).