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

Introduction

This article details how to use the terraform import command with the HCP Terraform cloud integration to import existing resources into a state file managed by HCP Terraform or Terraform Enterprise.

The terraform import command finds an existing resource in your infrastructure and adopts it into your Terraform state file. This allows Terraform to manage the resource moving forward. Not all resources support import. To verify that a resource can be imported, refer to the provider's documentation for that resource. Supported resources will have terraform import syntax listed at the bottom of their documentation page.

Use Case

Importing resources is useful in the following scenarios:

• When a terraform apply operation fails partially, leaving the state file in a condition where it does not reflect reality.
• When a resource was created manually or outside of the current Terraform workspace and you need to bring it under management.

Prerequisites

The import command runs locally and authenticates to your providers before writing to the remote state file. Unlike operations such as plan or apply, it does not run directly within the HCP Terraform or Terraform Enterprise workspace environment.

Because of this, the import command cannot access workspace variables, which may include provider credentials. To run an import successfully, you must ensure your local environment has the necessary credentials and variables by:

• Configuring provider credentials in your local environment (e.g., via environment variables).
• If needed, defining any required Terraform variables in a local .tfvars file or as environment variables (TF_VAR_...).

Procedure

Follow these steps to import a resource into remote state.

1. Configure the HCP Terraform Cloud Integration

Ensure that the cloud block is defined in your Terraform configuration to connect to your remote workspace.

terraform {
  cloud {
    hostname     = "my-tfe-hostname" ## Optional for HCP Terraform
    organization = "my-org"

    workspaces {
      name = "my-workspace"
    }
  }
}

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

2. Declare the Resource in Configuration

Add a resource block to your configuration that corresponds to the existing infrastructure resource. For example, if an EC2 instance already exists in AWS, add the following resource block, leaving the arguments empty for now.

resource "aws_instance" "ec2" {
  ## Arguments will be populated after import
}

3. Initialize Terraform

Run terraform init to initialize the providers and configure the connection to the remote workspace. You may also need to run terraform login if your local environment is not authenticated.

$ terraform init

4. Import the Resource

Run the terraform import command with the resource address and the resource's provider-specific ID.

$ terraform import 'aws_instance.ec2' 'i-043ecfb52d3a6e467'

Shell Expansion Warning: It is a best practice to wrap the resource address in single quotes ('...'). This prevents your shell from misinterpreting special characters, such as the brackets and quotes used in for_each resource addresses (e.g., 'aws_instance.example["test"]').

5. Verify the Import

Confirm that the resource is now tracked in the remote state file by running terraform state list.

$ terraform state list
aws_instance.ec2

6. Update Configuration to Match State

After a successful import, run terraform plan. Terraform will show that the resource in your state has many attributes that are not defined in your configuration. You must update your HCL configuration to include the required arguments for the imported resource until the plan shows no changes are needed.

Additional Information

• For more details on this command, refer to the official Terraform CLI import command documentation.