How To Bootstrap Your State Backend For Your Next Terraform or OpenTofu Project

Hey folks,

Like most things in IaC, a lot of people bootstrap their Terraform or OpenTofu (TF) state backend differently. This is a common chicken and egg problem that a lot of folks get tripped up on.

It's not hard to deal with though, so let's talk through how simple it is.

Here is what we do at Masterpoint and what I'd suggest you do:

1. Create a "tfstate-backend" root module in your repo. This root module should create the object storage bucket that corresponds to your cloud (AWS S3 bucket, Azure Blob, GCP Storage) and any supporting locking resources (Dynamo DB or similar). Do not include any backend configuration yet, just the storage infra. If you're on AWS and you don't want to reinvent the wheel, use the cloudposse/terraform-aws-tfstate-backend child module.

2. tf init && tf apply this root module from your local machine. This will create a terraform.tfstate file in your local working directory. This file manages the state of your new tfstate backend. We want to get that file off of your local machine and into the cloud tfstate backend as soon as we can. Think of this as state backend "inception".

3. Now add a backend.tf file to your tfstate-backend root module. If you're using OpenTofu, you can use dynamic backends and use the same file across all of your root modules. If you're on Terraform, hardcode it and remember to adjust each time you copy it to a new root module. The contents of this file point to the state backend storage location that you just created.

4. Run a tf init in your tfstate-backend root module. Now that you have a backend configured, TF will pick up that it should move the local tfstate file to the backend and ask you to migrate it. Confirm that "yes" you do want to copy the existing state. Below is what this looks like.

Enter yes and TF will now migrate that local state file to your new backend. State file inception complete — You're now done!

You created your state backend with IaC AND you're storing the state file that manages those resources in that same backend.

Now, you could use a tool like Terragrunt instead of the above steps. But it adds a good deal of complexity. We find not all of our projects are using a framework like that; the number is more like 50%. We manage and help clients with plenty of vanilla TF too. So the above agnostic solution is our go-to.

May your bootstrapping be painless,

Matt @ Masterpoint

PS If you want to chat about vanilla TF vs a framework, grab some time on my calendar here. You can also watch my IaCConf talk about the foundational principles of an effective IaC-driven platform.