If you just started to use Terraform for infrastructure deployments, chances are high that you're still using the local state files for the configuration. This is not bad for development reasons, but if you're starting to work with VCS repositories, CI/CD pipelines and in a team you should consider switching to remote state files. In this post I'll show you how to use the Terraform Cloud service to store your state file remotely.

Register for an account

First of all, you have to register an account on the Terraform website:

No worries, the account is free if you use it in a small team.

Create an api key

After successful registration, you have to add an api key so that your VCS repository and/or your cli installation can communicate with the Terraform Cloud api. You can find the service on the top under Settings --> API Tokens.

Due to security reasons, we cannot configure the api key in a Terraform configuration file. Instead, we use the .terraformrc file inside our $HOME directories:

credentials "app.terraform.io" {
  token = "xxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Create the backend configuration

With the api token in place we can now configure the backend for our Terraform infrastructure. Therefore, we create a new backend.tf file with the following content:

terraform {
  backend "remote" {
    hostname = "app.terraform.io"
    organization = "your chosen organization name"

    workspaces {
      name = "my-workspace"
    }
  }
}

If you work with Terraform workspaces you can also prefix your workspace like:

workspaces {
      prefix = "my-workspace-"
}

So, if you have a "prod" and a "staging" workspace the prefix solves the unique naming problem for you and creates a "my-workspace-prod" and a "my-workspace-staging" workspace in your Terraform Cloud.

Initialize your new backend workspace

Now we're ready to create the remote state file. Thus, we have to reinitialize the Terraform infrastructure again. No worries, nothing will change in your infrastructure!

terraform init                            

Initializing the backend...
Acquiring state lock. This may take a few moments...
Do you want to copy existing state to the new backend?
  Pre-existing state was found while migrating the previous "local" backend to the
  newly configured "remote" backend. No existing state was found in the newly
  configured "remote" backend. Do you want to copy this state to the new "remote"
  backend? Enter "yes" to copy and "no" to start with an empty state.

  Enter a value: yes


Successfully configured the backend "remote"! Terraform will automatically
use this backend unless the backend configuration changes.

Initializing provider plugins...

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

Because we only like to use the remote state file feature, please make sure to change the execution mode from remote to local. You can change the settings under your Workspace --> Settings --> General

And you're done. After you changed the setting you can run your Terraform commands like before. Your state file is now safely placed in Terraform Cloud.