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

Introduction

This article details how to use the cloud backend to import resources into a state managed by 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.

1. Ensure that the backend is defined in the Terraform configuration.

   terraform {
     cloud {
       hostname = "my-tfe-hostname" # Optional for TFC 
       organization = "my-org"
   
       workspaces {
         name = "my-workspace"
       }
     }
   }
   

   Note: For versions older than Terraform v1.1.0 and Terraform Enterprise v202201-1, you should use the remote block instead:

   terraform {
     backend "remote" {
       hostname = "my-tfe-hostname" # app.terraform.io for TFC 
       organization = "my-org"
   
       workspaces {
         name = "my-workspace"
       }
     }
   }

2. Declare 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)
   }

3. Run terraform init to initialize the backend and the providers. You may need to run terraform login as well if your local environment is not authenticated with Terraform Cloud/Enterprise
4. Run terraform import $RESOURCE_ADDRESS $RESOURCE_ID to import the resource to be managed by the state file. For our example EC2 instance from above: terraform import aws_instance.ec2 i-043ecfb52d3a6e467

   Note: To prevent Shell expansion issues, it is recommended to wrap the resource address in single quotes, particularly for resources created with for_each. 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.

5. Verify that the resource is now managed by the state file by running: terraform state list

Additional Information

The import command runs locally before writing to the remote state file; unlike commands such as plan or apply, which run directly in the Terraform Cloud or Enterprise workspace. Because of this, the import command will not have access to the workspace variables (which may include credentials). Thus, to successfully complete an import, you may need to:

• hardcode workspace Terraform variables in your local HCL configuration,
• and, export workspace environment variables to your local Shell.

Terraform Import command reference