Import existing resources to state

You can define queries in your Terraform configuration to search for resources that are not yet managed by Terraform. HCP Terraform presents query results so that you can use the UI to import the resources and begin managing them as code. This topic describes the workflow for importing resources in bulk. For instructions on importing single resources or small batches of resources in your configuration, refer to Import a single resource.

Overview

You can use search functionality in UI and VCS-driven and CLI-driven workspaces. Complete the following steps to search for resources and import them into your Terraform state:

1. Define queries: Add list blocks to your Terraform configuration. If you are using the VCS-driven workflow, commit this change and push it to the repository associated with your workspace in HCP Terraform. Refer to Import resources in bulk for more information.
2. Run the queries: You can run queries in the HCP Terraform UI or run the Terraform CLI on your local workstation.
3. Review search results: HCP Terraform shows the management status for resources it finds.
4. Generate code: HCP Terraform generates import and resource blocks for the resources it discovers.
5. Apply the configuration: Copy the generated code to your Terraform configuration and run it to finish importing the resources.

HCP Terraform agents

If you use HCP Terraform agents for your runs, you must enable the query operation when starting the agent pool. Refer to Install and run agents for more information.

Requirements

You must enable Terraform 1.14.0-beta or newer for your workspace to access the Search & Import page. Refer to the general workspace settings documentation for more information about changing workspace settings.

HCP Terraform identifies resources managed by other workspaces when the workspace uses Terraform v1.12 and newer.

Define queries

Add list blocks to your workspace's Terraform configuration to create search queries you want to run against your existing infrastructure. Refer to Import resources in bulk for instructions on how to define queries.

If HCP Terraform is connected to your VCS, commit the configuration to version control.

You can also connect your local workstation to HCP Terraform with the CLI-driven workflow and use the Terraform CLI to perform operations in your HCP Terraform workspace. Refer to Connect to HCP Terraform for instructions.

Run queries

Complete the following steps after defining queries and copying them to your HCP Terraform workspace:

1. Log into HCP Terraform and navigtate to your workspace.
2. Click Search & Import in the sidebar menu. The page shows previously completed queries, as well as any queries that are in progress.
3. Click New Query to start a query.

As the query progresses, HCP Terraform loads the results to the page.

Review queries

In the IaC column, HCP Terraform indicates one of the following statuses for resources returned by the query:

• Managed indicates that the resource has the same identity as a resource applied by a similar provider version.
• Unknown indicates that the resource has the same identity as a resource applied by an older version of Terraform or older provider version.
• Unmanaged indicates that there are no managed resources of this type or that Terraform can't attribute this resource to a similar provider and Terraform version.

Over time, providers may change their resource identity definitions, but HCP Terraform attempts to capture all resource identities as providers evolve. When a schema for a resource type changes between versions, HCP Terraform may list a resource as Unknown instead of Unmanaged when a resource was applied by one version of a provider but queried by a different version.

You can perform the following actions in the results area:

• Use the search bar and filters to sort and filter the results.
• Click on a resource in the Resource type column to view details made available by the provider.
• Select resources that you want to import to your workspace. Refer to Generate code for instructions.

Generate code

Select one or more resource instances in the search results area and click Generate configuration. HCP Terraform generates import and resource blocks that you can add to your configuration to import the resource instances into your state.

Import resources

Copy the code to your Terraform configuration and apply the configuration. Before applying the configuration, we recommend running the terraform fmt command to ensure that the code is properly formatted.

Use one of the following methods to apply the configuration:

• Navigate to your workspace in HCP Terraform and click New run.
• Run the terraform apply command on the remote workstation.
• If your workspace is configured to run on VCS changes, check the updated configuration into your VCS to trigger a new run.

Next steps

After importing the resources to state, you can delete the generated import blocks or keep them as a historical record.