HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Terraform Home

Search and import resources

HCP Terraform and Terraform Enterprise let you search your existing infrastructure for resources and import them into your workspace. This feature helps you discover unmanaged resources across cloud providers, making it easier to bring existing infrastructure under Terraform management.

Background

When you inherit infrastructure or manage environments with unknown resources, identifying and importing unmanaged resources can be a time-consuming manual process. The search and import feature provides a visual interface to build queries, select resources, and generate configuration so that HCP Terraform can discover resources across your cloud providers.

Workflow

HCP Terraform executes search queries against your cloud providers to discover resources that are not currently managed by Terraform. You can either define these queries in the HCP Terraform UI, or in your workspace's Terraform configuration.

When you query resources, the search interface displays results with management status indicators, helping you identify which resources to import. You can write or automatically generate Terraform configuration to import and manage the selected resources, and then apply your changes to bring them under management.

Requirements

To run queries and import resources, you need:

  • An HCP Terraform workspace with Terraform 1.14 or newer configured
  • Cloud provider credentials for the providers you wish to query configured for your workspace
  • Read and write permissions for the workspace

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

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.

Define queries

To query resources with HCP Terraform, you can either use the build query UI, or write queries directly into your Terraform configuration.

Build a query in the UI

To query resources for your workspace using the buiild query UI:

  1. Navigate to your workspace in HCP Terraform.
  2. Select Search & Import from the left navigation.
  3. Click the + New query dropdown in the upper right.
  4. Select the Build query via UI button.
  5. On the New query page, select the providers you wish to import resources for. Remember that your workspace must have credentials configured for the providers you select.
  6. Click the Select provider button to continue.
  7. To begin building your query, select the resource types you want to query for. You can include multiple resource types from different providers in a single query.
  8. To filter your query to only match certain resources of type you selected, click the + icon to the right of your resource type.
  9. You can either select pre-defined filters based upon the resource type, or filter any attribute that Terraform tracks for the resource type.
  10. After you have defined all of the filters for your query, click the Run query button to run your query. The Start new query modal appears with the Generate starter configuration option enabled by default. This option directs HCP Terraform to generate starter configuration for you by loading additional data about the resources it queries. Queries with this option enabled take longer to complete.
  11. Click Confirm. Terraform searches for resources according your query.

Define a query in Terraform configuration

To query resources for your workspace using Terraform configuration:

  1. Add list blocks to your workspace's Terraform configuration to createthe search queries you want to run against your existing infrastructure. Refer to Import resources in bulk for instructions on how to define queries.
  2. If your workspace uses the VCS-driven workflow, commit and push your changes to the branch configured in your workspace settings.
  3. If your workspace uses the CLI-driven workflow, apply your changes from your terminal.
  4. Navigate to your workspace in HCP Terraform.
  5. Select Search & Import from the left navigation.
  6. Click the + New query dropdown in the upper right.
  7. Select the Fetch latest configuration button.
  8. Click New Query. The Start new query modal appears with the Generate starter configuration option enabled by default. This option directs HCP Terraform to generate starter configuration for you by loading additional data about the resources it queries. Queries with this option enabled take longer to complete.
  9. Click Confirm. Terraform searches for resources according your query.

Review results

HCP Terraform displays the query results, including the IaC status, if known.

The IaC Status column indicates when a discovered resource matches a resource already managed by HCP Terraform:

  • Managed: The resource has the same identity as a resource managed by a workspace with a similar provider version.
  • Unknown: The resource has the same identity as a resource managed by an older Terraform or provider version. Verify the resource before importing.
  • Unmanaged: The resource is not currently managed by Terraform and can be imported.

HCP Terraform identifies resources managed by other workspaces when those workspaces use Terraform v1.12 or newer. When a provider changes its resource identity definition between versions, HCP Terraform may list a resource as Unknown instead of Unmanaged.

Filter and search results

Use the search bar and filters to narrow results:

  • Enter text in the search bar to filter by resource name or identifier.
  • Use the Resource type filter to show only specific resource types.
  • Use the IaC status filter to show only managed, unmanaged, or unknown resources.
  • Click on a resource in the Resource type column to view detailed attributes provided by the provider.

Generate configuration

Select one or more resource instances in the search results area and click Generate Starter 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 import and resource blocks to your Terraform configuration.

If you did not have HCP Terraform generate your starter configuration, you can copy the import blocks to your configuration and use the -generate-config-out flag for terraform plan to generate your configuration. Refer to Generating configuration for more information.

If your workspace uses the VCS-driven workflow, commit and push your changes to the branch configured in your workspace settings. Then navigate to your workspace in HCP Terraform and click New run.

If your workspace uses the CLI-driven workflow, plan and apply your changes from your terminal.

You may need to modify the generated configuration to succesffully import your resources. Resolve any errors in the Terraform plan, and then apply your changes.

Next steps

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

Reference

Refer to the following documentation to learn more about how to import resources with Terraform:

Edit this page on GitHub