Store Remote State

You have now seen how to build, change, and destroy infrastructure from a local machine. This is great for testing and development, but in production environments it is considered a best practice to store state elsewhere than your local machine. The best way to do this is by running Terraform in a remote environment with shared access to state.

Terraform supports team-based workflows with a feature known as remote backends. Remote backends allow Terraform to use a shared storage space for state data, so any member of your team can use Terraform to manage the same infrastructure.

Depending on the features you wish to use, Terraform has multiple remote backend options. HashiCorp recommends using Terraform Cloud.

Terraform Cloud also offers HashiCorp's commercial solutions and with a free version which acts as a remote backend. Terraform Cloud allows teams to easily version, audit, and collaborate on infrastructure changes. Each proposed change generates a Terraform plan which can be reviewed and collaborated on as a team. When a proposed change is accepted, the Terraform logs are stored, resulting in a linear history of infrastructure states to help with auditing and policy enforcement. Additional benefits to running Terraform remotely include moving access credentials off of developer machines and freeing local machines from long-running Terraform processes.

»Prerequisites

You should have completed the previous guides in this track, or use the following configuration to start this guide.

Create a directory named learn-terraform-azure-instance and paste this code into a file named example.tf.

terraform {
  required_providers {
    azurerm = {
      source = "hashicorp/azurerm"
      version = ">= 2.26"
    }
  }
}

provider "azurerm" {
  features {}
}

resource "azurerm_resource_group" "rg" {
  name     = "myTFResourceGroup"
  location = "westus2"
}

»Set up the remote backend

First, we'll use Terraform Cloud as our backend. Terraform Cloud offers free remote state management. Terraform Cloud is the recommended best practice for remote state storage.

If you don't have an account, please sign up here for this guide. For more information on Terraform Cloud, view our getting started guide.

When you sign up for Terraform Cloud, you'll create an organization. Make a note of the organization's name.

Next, configure the backend in your configuration with the organization name, and a new workspace name of your choice:

terraform {
  required_providers {
    azurerm = {
      source = "hashicorp/azurerm"
      version = ">= 2.26"
    }
  }
}

provider "azurerm" {
  features {}
}

+  backend "remote" {
+    organization = "<ORG_NAME>"
+    workspaces {
+      name = "Example-Workspace"
+    }
+  }
}

resource "azurerm_resource_group" "rg" {
  name     = "myTFResourceGroup"
  location = "westus2"
}

»Authenticate with Terraform Cloud

Now that you have defined your backend, you must authenticate with Terraform Cloud in order to proceed with initialization. In order to authenticate with Terraform Cloud, run the terraform login subcommand, and follow the prompts to log in.

$ terraform login
Terraform will request an API token for app.terraform.io using your browser.

If login is successful, Terraform will store the token in plain text in
the following file for use by subsequent commands:
    /Users/username/.terraform.d/credentials.tfrc.json

Do you want to proceed? (y/n)

For more detailed instructions on logging in, see the login guide.

»Migrate the state file

Once you have authenticated the remote backend, you're ready to migrate your local state file to Terraform Cloud. To begin the migration, reinitialize. This causes Terraform to recognize your changed backend configuration.

$ 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:

During reinitialization, Terraform presents a prompt saying that it will copy the state file to the new backend. Enter "yes" and Terraform will migrate the state from your local machine to Terraform Cloud. Now, if you run terraform apply, Terraform should state that there are no changes:

$ terraform apply
# ...

No changes. Infrastructure is up-to-date.

This means that Terraform did not detect any differences between your
configuration and real physical resources that exist. As a result, Terraform
doesn't need to do anything.

Terraform is now storing your state remotely in Terraform Cloud. Remote state storage makes collaboration easier and keeps state and secret information off your local disk. Remote state is loaded only in memory when it is used.

If you want to move back to local state, you can remove the backend configuration block from your configuration and run terraform init again. Terraform will once again ask if you want to migrate your state back to local.

»Learn more about Terraform Cloud

Terraform Cloud offers commercial solutions which combines a predictable and reliable shared run environment with tools to help you work together on Terraform configurations and modules.

Although Terraform Cloud can act as a standard remote backend to support Terraform runs on local machines, it works even better as a remote run environment. It supports two main workflows for performing Terraform runs:

• A VCS-driven workflow, in which it automatically queues plans whenever changes are committed to your configuration's VCS repo.
• An API-driven workflow, in which a CI pipeline or other automated tool can upload configurations directly.

For a hands-on introduction to Terraform Cloud, follow the Terraform Cloud getting started guides for our free offering as well as Terraform Cloud for Teams and Governance.

»Next Steps

That concludes the getting started guide for Terraform. Hopefully you're now able to not only see what Terraform is useful for, but you're also able to put this knowledge to use to improve building your own infrastructure.

We've covered the basics for all of these features in this guide.

For more information on Terraform, review the following resources:

• Documentation - The documentation is an in-depth reference guide to all the features of Terraform, including technical details about the internals of how Terraform operates.

• Modules Track - Learn how to organize and re-use Terraform configuration with modules.

• Import - The import section of the documentation covers importing existing infrastructure into Terraform.