Move Terraform State Between Accounts

Terraform State is a way to track and manage your Terraform configurations and resources. It stores your Terraform configurations in a centralized location and makes it easy to query and visualize your state.

What is Terraform State?

The state file is a way to keep track of the current state of a Terraform configuration. It stores all of the information necessary to reconstruct the state of the configuration at any point in time. This includes information about which resources have been provisioned, how they’re configured, and how they’re being used.

Why Do you need to move Terraform State files?

Here are some key reasons why you might want to move the state files.

1. Change of ownership: If you transfer ownership of an application or infrastructure stack from one AWS account to another, you may need to move the Terraform state to the new account to maintain control over the infrastructure.
2. Compliance requirements: Some organizations may require that certain resources be deployed in a separate AWS account for compliance reasons. In such cases, moving the Terraform state to the target account can help ensure the infrastructure complies with the necessary regulations.
3. Security considerations: If you need to enforce strict access control policies for your infrastructure, you may want to deploy resources in a separate AWS account with tighter security controls. Moving the Terraform state to the target account can help ensure that only authorized personnel can access the infrastructure.
4. Consolidation of accounts: Sometimes, you may need to consolidate multiple AWS accounts into a single account to streamline management and reduce costs. In such cases, moving the Terraform state to the new account can help simplify the infrastructure management process.

In general, moving Terraform state between AWS accounts can be useful in situations where you need to transfer ownership, enforce compliance requirements, tighten security controls, or consolidate accounts. However, it is important to carefully plan and execute the migration to avoid any disruption to existing infrastructure.

How does Terraform state work?

When you run a Terraform command, the state file is updated to reflect your changes. The state is stored in a file on your local machine. You can use the state file to reconstruct the state of your configuration at any point in time.
Consequently, the remote state data source needs to have parameters added to its config block which specify a suitable IAM role that may be assumed in the account containing the state file; for example:

data "terraform_remote_state" "example" {
  backend = "s3"

  config = {
    bucket         = var.my_state_bucket1
    dynamodb_table = var.tf_state_dynamo
    region         = var.region
    key            = var.tfstate_key
    role_arn       = data.aws_ssm_parameter.cross_account_role.value
    external_id    = data.aws_ssm_parameter.external_id.value
  }
}

Note that where a project that acts as the provider of remote state data has its state file moved to a different account, it is important to identify all other projects that act as consumers, and if their state files are not being moved at the same time, the above modification will need to be made to the terraform_remote_state data sources.

Alternatively, it may be preferable to refactor the code in the impacted projects to use the SSM Parameter Store, which is now the preferred method of sharing Terraform outputs between projects.

Instructions (Manually)

If you want to update your state, you can use the “terraform state pull” command. This will update your state based on the latest changes to your code. You can also use the “terraform state push” command to update your state from a versioned Terraform file.

Note that I use AWS-VAULT to query my AWS infrastructure, you can find out how to set this up here

Step 1 – Pull the Terraform State

Pull the remote state file into your local state (Note, the following example is pulling the state file from the non-prod account)

aws-vault exec myprofile -- terraform state pull > terraform.tfstate

Step 2 – Push to a new S3 bucket

Once the file is pulled down locally, it can be uploaded to the s3 path you desire (Make sure after the file has been pulled that your backend.conf within your tf code has been updated to where you will upload the state file. (Note, the following example is uploading the state file to an s3 path within the AWS account)

aws-vault exec myprofile -- aws s3 cp terraform.tfstate s3://mybucket/terraform.tfstate

Step 3 – Run Terraform init

Lastly, run a terraform init to confirm the new state file can be remotely initialised (Terraform Init Example)

aws-vault exec myprofile-- terraform init -reconfigure -backend-config=/path/to/backend.conf

With Terraform, you can easily manage your state and keep your infrastructure up-to-date. Whether you need to push a new version of your software to all your servers or just update a single one, Terraform simplifies the process.

Want to know more about Terraform? Check out our other articles:

Learn Core Terraform Concepts

Terraform Core Commands

Learn out Terraform Plan -Out