As a current user of the Terraform CLI, you are responsible for maintaining a state file as a source of truth for your cloud infrastructure. You can keep your state file secure and share it with collaborators, by migrating it to Terraform Cloud without interrupting or recreating your existing infrastructure.
Warning: When uploading a state file to Terraform Cloud using the steps in this tutorial, always use the same version of the Terraform CLI you used to create the resources. Using a newer version of Terraform may update the state file and cause state file corruption.
»Prerequisites
This tutorial assumes that you have the following:
- The Terraform CLI installed locally
- A Terraform Cloud account
Note: Because the cloud
block is not supported by older versions of Terraform, you must use 1.1.0 or higher in order to follow this tutorial. Previous versions can use the remote
backend block to configure the CLI workflow and migrate state.
»Create state
Start by cloning this GitHub repository.
Next, change into the directory.
Review the main.tf
file in the working directory to get an overview of the resources you are about to create. This configuration uses the random_pet
resource to generate and output a random pet name with a given number of words. The length of the name is determined by the value of the name_length
variable, which defaults 3.
In a real-world configuration you may have additional variables such as cloud platform credentials defined in a .tfvars
file. We'll cover how to set these values in the Terraform Cloud workspace later on in this tutorial, after you've migrated the state file.
Initialize the directory.
After Terraform initializes, apply the configuration and approve the run by typing "yes" at the prompt.
Terraform will output a three word randomly generated pet name.
»Set up Terraform Cloud
Now that you have a local state file, you need to create a cloud
code block in your configuration.
The Terraform CLI workflow saves your state as a terraform.tfstate
file in the directory where you run terraform apply
. To migrate your state to Terraform Cloud, update the cloud
block and change the <ORG_NAME>
to your Terraform Cloud organization name.
Replace the organization and workspaces attribute values with the name of your Terraform Cloud organization and desired workspace name. While the organization defined in the cloud
stanza must already exist, the workspace does not have to; Terraform Cloud will create it if necessary. If you opt to use a workspace that already exists, the workspace must not have any existing states.
Note: If you are familiar with running Terraform using the CLI, you may have used Terraform workspaces. Terraform Cloud workspaces behave differently than Terraform CLI workspaces. Terraform CLI workspaces allow multiple state files to exist within a single directory, enabling you to use one configuration for multiple environments. Terraform Cloud workspaces contain everything needed to manage a given set of infrastructure, and function like separate working directories.
»Authenticate with Terraform Cloud
Now that you have defined your Terraform Cloud configuration, 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.
Note: If you are using a version of Terraform prior to 0.12.21, the terraform login
command is not available. Instead, set up a CLI configuration file to authenticate.
Respond to the confirmation prompt with a yes
.
For more detailed instructions on logging in, see the login tutorial.
»Migrate the state file
Once you have authenticated to Terraform Cloud, you're ready to migrate your local state file to Terraform Cloud. To begin the migration, reinitialize. This causes Terraform to recognize your cloud
block configuration.
During reinitialization, Terraform presents a prompt saying that it will copy the state file to your Terraform Cloud workspace. Enter yes
and Terraform will migrate the state from your local machine to Terraform Cloud.
»Configure the Terraform Cloud workspace
After migrating your state to Terraform Cloud, log in to the Terraform Cloud web UI, find your workspace name as defined in your cloud
block, and click on it. Navigate to the States tab of the workspace, and see your first action within the workspace.
Remember that your configuration has a variable that you need to add to the new
workspace. Click the "Variables" tab in the workspace and then "Add variable".
Enter the name of the variable, name_length
, as the key. Then enter a new
value, 5
, and save the variable.
For real-world configurations, add cloud platform credentials and any other configuration variables to the workspace as well.
»Initiate a run in the new workspace
After verifying that the state was migrated to the Terraform Cloud workspace, remove the local state file.
Apply a new run.
Terraform will stream logs from Terraform Cloud and provide a link to the run in the Terraform Cloud UI. You set a new value for the name_length
variable, so the resource will be replaced with one matching the new parameters.
»Next steps
Destroy the resources you created for this tutorial by first clicking the "Settings" option in the Terraform Cloud workspace, selecting "Destruction and Deletion", ensuring the "Allow destroy plans" checkbox is checked, and then clicking "Queue destroy plan".
After the resources have been destroyed, return to the "Destruction and Deletion" page and click "Delete from Terraform Cloud" to delete the workspace.
In this tutorial, you migrated a state file from your local machine to a Terraform Cloud workspace. To learn how to migrate the state files of multiple local workspaces, or restrict workspace access to a particular team, see the following documentation.
If you have a large number of state files that you would like to migrate to Terraform Cloud, consider using the Terraform Cloud API to do so. For information on uploading state versions using the API, refer to the State Version API documentation.