How to Import Resources into a Remote State Managed by Terraform Cloud

Introduction

This article details how to use the remote backend to import resources into a state within a workspace in Terraform Cloud or Terraform Enterprise.

Use Case

terraform import allows for importing resources into Terraform’s state file. This “adopts” the resources so that Terraform may manage the resource moving forward. It is important to note that not all resources can be imported. To verify that the resource in question may be imported, please refer to the provider’s documentation for the resource. Supported resources will have the terraform import syntax listed at the bottom of the page.

Importing specific resources is useful in the following scenarios:

• When Terraform performed a partial apply, leaving the state file in a condition where it does not reflect reality.

• When the resource was manually created outside of Terraform or the workspace and the state file needs to be updated.

Procedure

The remote backend is used to store the Terraform state in Terraform Cloud or Terraform Enterprise rather than locally, and may be used to run import operations.

To start the process of importing a resource ensure that the remote backend configuration is set up in the Terraform configuration.

terraform {
  backend "remote" {
    hostname = "TFEHOSTNAME.com" // for Terraform Cloud, this may be omitted or set to `app.terraform.io`
    organization = "company"

    workspaces {
      name = "my-app-prod"
    }
  }
}

Once the remote backend is in the Terraform configuration, set up the resource configuration in the root module. For example, if an EC2 instance already exists in AWS, you might add a resource to the configuration as follows:

resource "aws_instance" "ec2" {
  # (resource arguments)
}

Run terraform init to initialize the backend.

Initializing the backend...

Initializing provider plugins...
- Finding latest version of hashicorp/aws...
- Installing hashicorp/aws v3.28.0...
- Installed hashicorp/aws v3.28.0 (signed by HashiCorp)

Terraform has made some changes to the provider dependency selections recorded
in the .terraform.lock.hcl file. Review those changes and commit them to your
version control system if they represent changes you intended to make.

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.

Once initialized, run terraform import $RESOURCE_NAME $ADDRESS-ID to import the resource to be managed by the state file. For our example EC2 instance from above, this would appear as follows:

Note: It’s often useful, particularly for resources with for_each, to single quote the resource name to prevent shell expansion from causing issues. For example, attempting to import a resource using aws_instance["test"] will error due to the shell automatically omitting the quotes, while 'aws_instance["test"]' will work correctly.

$ terraform import aws_instance.ec2 i-043ecfb52d3a6e467
Acquiring state lock. This may take a few moments...

aws_instance.ec21: Importing from ID "i-043ecfb52d3a6e467"...

aws_instance.ec21: Import prepared!
  Prepared aws_instance for import


aws_instance.ec21: Refreshing state... [id=i-043ecfb52d3a6e467]

Import successful!

The resources that were imported are shown above. These resources are now in
your Terraform state and will henceforth be managed by Terraform.

Import examples for supported resources can be found on the Terraform Registry.

After the resource has been imported run terraform state list to verify that the resource is now managed by the state file.

$ terraform state list
...
aws_instance.ec21
...

Additional Information

When using Terraform import on the command line with a remote backend the import command runs locally, unlike commands such as apply, which run inside the Terraform Cloud or Enterprise workspace. Because of this, the import command will not have access to information from the remote backend, such as workspace variables. In order to use terraform import with a remote state backend, you may need to set local variables equivalent to the remote workspace variables.

• Terraform Import command reference