Using Terraform Cloud Remote State Management

We recently announced Terraform 0.12 and Terraform Cloud Remote State Management. Both these releases provide Terraform users a better experience writing and collaborating on Infrastructure as Code. This blog post will look at some motivations for using Terraform Cloud and describe how it works.

»What is Terraform State?

To explain the value of Terraform Cloud, it’s important to understand the concept of state in Terraform. Terraform uses state to map your Terraform code to the real-world resources that it provisions. For example, you could use the following code to create an AWS EC2 instance:

resource "aws_instance" "web" {
	ami = "ami-e6d9d68c"
	instance_type = "t2.micro"
}

When you run terraform apply on this configuration file, Terraform will make an API call to AWS to create an EC2 instance and AWS will return the unique ID of that instance (ex. i-0ad17607e5ee026d0). Terraform needs to record that ID somewhere so that later, it can make API calls to change or delete that instance.

To store this information, Terraform uses a state file. For the above code, the state file will look something like:

{
...
"resources": {
	"aws_instance.web": {
		"type": "aws_instance",
		"primary": {
		"id": "i-0ad17607e5ee026d0",
...
}

Here you can see that the resource aws_instance.web from the Terraform code is mapped to the instance ID i-0ad17607e5ee026d0.

»Remote State

By default, Terraform writes its state file to your local filesystem. This works well for personal projects, but once you start working with a team, things start to get more challenging. In a team, you need to make sure everyone has an up to date version of the state file and ensure that two people aren’t making concurrent changes.

Remote state solves those challenges. Remote state is simply storing that state file remotely, rather than on your local filesystem. With a single state file stored remotely, teams can ensure they always have the most up to date state file. With remote state, Terraform can also lock the state file while changes are being made. This ensures all changes are captured, even if concurrent changes are being attempted.

Configuring remote state in Terraform has always been an involved process. For example, you can store state in an S3 bucket, but you need to create the bucket, properly configure it, set up permissions, create a DynamoDB table for locking, and then ensure everyone has proper credentials to write to it.

As a result, setting up remote state can be a stumbling block as teams adopt Terraform.

»Easy Remote State Set Up with Terraform Cloud

Unlike other remote state solutions that require complicated setup, Terraform Cloud offers an easy way to get started with remote state:

• Step 0 — Sign up for a Terraform Cloud account here

• Step 1 —  An email will be sent to you, follow the link to activate your free Terraform Cloud account.

• Step 2 — When you log in, you’ll land on a page where you can create your organization or join an existing one if invited by a colleague.

[](

• Step 3 — Next, go into User Settings and generate a token.

• Step 4 — Take this token and create a local ~/.terraformrc file:

credentials "app.terraform.io" {
	token = "mhVn15hHLylFvQ.atlasv1.jAH..."
}

• Step 5 — Configure Terraform Cloud as your backend

In your Terraform project, add a terraform block to configure your backend:

terraform {
	backend "remote" {
		organization = "my-org" # org name from step 2.
		workspaces {
			name = "my-app" # name for your app's state.
		}
	}
}

• Step 6— Run terraform init and you’re done.

Your state is now being stored in Terraform Cloud. You can see the state in the UI:

»Fully Featured State Viewer

Terraform Cloud offers a fully featured state viewer to gain insight into the state of your infrastructure:

This maintains versions of your Terraform state allowing you to download an old version if needed. Likewise, it provides audit logs to know who changed what and when.

You can view the full state file at each point in time:

You can also see the diff of what changed:

»Manual Locking

Terraform Cloud also includes the ability to manually lock your state. This is useful if you’re making large changes to your infrastructure and you want to prevent coworkers from modifying that infrastructure while you’re in the middle of your work.

You can lock and unlock states directly in the UI:

While the state is locked, Terraform operations will receive an error:

»Conclusion

We’re pleased to offer Remote State Management with Terraform Cloud free to our users. Sign up for an account here: https://app.terraform.io/signup