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

Queries created in the UI

You must select the Remote (custom) or Agent (custom) execution mode, or Project Default if the project uses remote or agent execution. Refer to Execution mode for more information.

You do not need to connect a VCS repository, upload Terraform configuration, or write provider or list blocks. HCP Terraform generates a separate configuration for the query. You still need provider credentials and required settings available during query execution. Refer to Configure providers for queries created in the UI.

Resource identity

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

Policy evaluations

To evaluate policies against query results in HCP Terraform, you also need:

A workspace that uses Terraform v1.17.0 or later.
A workspace configured for remote or agent execution.
An organization with Terraform policy and search policy evaluation enabled, including access to policy enforcement and versioned policy sets.
Applicable Terraform policy (tfpolicy) policy sets. These can include workspace assignments, inherited project assignments, and organization-wide assignments. Refer to Set up Terraform policy.
Generated configuration enabled for the query. In the UI, leave Generate starter configuration selected in the Start new query modal.

To create or change policy sets, you also need your organization's manage policies permission.

HCP Terraform agents

HCP Terraform agents enable the query operation by default. Refer to Install and run agents for more information.

Policy evaluation also requires a compatible Terraform policy runtime for the agent's operating system and architecture. If your policies use custom plugins, build them for the agent's architecture. Refer to Terraform policy plugins.

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

You can use the build query UI to create and run a query in a workspace without any prior Terraform configuration.

HCP Terraform installs the provider version shown on the catalog entry you select into a separate query configuration. It does not reuse provider blocks, aliases, version constraints, or the dependency lock file from your workspace's existing code. You do not need to edit or upgrade the providers in that code to run a query created in the UI.

Configure providers for queries created in the UI

Before you select a provider, configure its authentication and required settings, such as region, subscription, or project. Use the environment variables supported by that provider. Refer to the provider's Terraform Registry documentation, such as AWS authentication and configuration, for the required keys and authentication prerequisites.

Open your workspace's Variables page.
Click + Add variable in the Workspace Variables section.
Select the Environment variable category and enter the provider-supported key and value. Mark credentials and other secrets Sensitive.
Click Add variable. Repeat for each required key.

Refer to Add a variable for the full procedure, Permissions for the access required to manage variables, and Sensitive values for how HCP Terraform handles secrets.

To reuse provider settings across workspaces, add environment variables to a variable set that applies to the query's workspace. You can apply an existing variable set from the workspace's Variables page. Check variable precedence when multiple sources define the same key.

Terraform input variables selected in resource filters supply query values, but they do not configure the provider. For example, a Terraform variable named region does not replace the AWS provider's AWS_REGION environment variable. HCP Terraform does not copy provider settings or authentication from your workspace's provider blocks. This includes the alias argument and the AWS provider's assume_role block.

Run a query

After you configure the provider, use the query builder to select resource types and filters. HCP Terraform generates the query's configuration, so you do not need to upload configuration or author provider or list blocks.

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

Navigate to your workspace in HCP Terraform.
Select Search & Import from the left navigation.
Click the + New query dropdown in the upper right.
Select the Build query via UI button.
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.
Click Next to continue.
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.
To filter your query to only match certain resources of type you selected, click the + icon to the right of your resource type.
You can either select pre-defined filters based upon the resource type, or filter any attribute that Terraform tracks for the resource type.
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 loads additional resource data and generates configuration for the query results. You do not need to write a list block or supply a CLI flag. The additional resource reads can increase query duration.
Leave Generate starter configuration selected to provide configuration for policy evaluation. Resource identities alone do not provide enough information to evaluate policies.
The separate Evaluate against workspace policies checkbox starts checked when configuration generation is enabled. Leave it checked to evaluate applicable Terraform policy sets, or clear it to opt out of automatic workspace policy evaluation for this query. Clearing Generate starter configuration also clears and disables policy evaluation. Reopening the modal restores the policy checkbox's default, subject to your configuration-generation preference.
Click Confirm. Terraform searches for resources according your query.

Define a query in Terraform configuration

To query resources for your workspace using Terraform configuration:

Add list blocks to your workspace's Terraform configuration to create the search queries you want to run against your existing infrastructure. Refer to Import resources in bulk for instructions on how to define queries.
If your workspace uses the VCS-driven workflow, commit and push your changes to the branch configured in your workspace settings.
If your workspace uses the CLI-driven workflow, apply your changes from your terminal.
Navigate to your workspace in HCP Terraform.
Select Search & Import from the left navigation.
Click the + New query dropdown in the upper right.
Select the Fetch latest configuration button.
Click New Query. The Start new query modal appears with the same Generate starter configuration option described in Build a query in the UI. Leave it selected to request additional resource data and generated configuration. The additional resource reads can increase query duration.
Leave Evaluate against workspace policies checked to evaluate applicable Terraform Policy sets. Clear it to opt out for this query. Clearing Generate starter configuration also clears and disables policy evaluation. Setting include_resource = true in your query configuration does not replace the UI's generated-configuration requirement.
Click Confirm. Terraform searches for resources according your query.

Review results

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

Discovery is not limited to resources in the workspace's existing code. Results depend on the following factors:

The selected provider version's supported list resource types
The cloud identity's permissions and account
Region or project scope
The selected resource types, filters, and query result limits

One query does not necessarily return every resource accessible to the identity.

If a query created in the UI fails because credentials or required provider settings are missing, update the provider settings and run the query again.

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.

Review policy results

When the query includes policy results, the Policy evaluation column shows the number of policy evaluations with Pass, Fail, or Unknown outcomes for each resource. Click a result to open the resource details and inspect the policy names, enforcement levels, and diagnostics.

Passed: The resource's generated configuration satisfies the policy.
Failed: The resource's generated configuration does not satisfy the policy. Review its diagnostics to understand the failure.
Unknown: Terraform cannot determine the outcome. Missing resource data or incomplete relationship data can prevent evaluation. The UI also groups evaluation errors under Unknown; inspect the diagnostics to distinguish an error from an indeterminate result.
N/A: Policies exist, but none target the resource type specified by the list block. The details show No policy targeted at resource. This is not a passing result.

Query-time policy results are informational. They do not block resource selection or import, even for mandatory policies, and do not replace policy enforcement during a Terraform plan or apply. Policies evaluate configuration generated from discovered resource data, not a complete view of your infrastructure. Review generated-input limitations and relationships that the query does not capture before drawing conclusions about compliance.

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.

Policy input and an importable configuration file serve different purposes:

In the UI, Generate starter configuration in the Start new query modal requests full resource data and generated configuration during the query. HCP Terraform uses this configuration as policy input. After you review the results, select resources and copy their generated blocks to your configuration.
In a remote CLI query, include_resource = true in a list block requests full resource data. Terraform can generate policy input from that data without writing a .tf file.
The CLI option terraform query -generate-config-out=/path/to/config.tf requests resource data and writes generated resource and import blocks to a file on your workstation that must not already exist.

To evaluate policies from the CLI, configure a cloud block connected to a workspace with remote or agent execution. The CLI's -policies option selects explicit policy-set directories but does not enable include_resource. Without resource configuration, policy evaluation returns Unknown. Refer to Evaluate policies with the Terraform CLI for examples.

Queries started through the HCP Terraform UI or API require generated configuration for policy evaluation. Setting include_resource alone does not satisfy that requirement. Refer to the Queries API for API options.

Import resources

Copy the import and resource blocks to your Terraform configuration.

If HCP Terraform did not 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.

When you plan an import into the same workspace, HCP Terraform evaluates the workspace's policies again against the import plan. This includes imports planned with terraform plan -generate-config-out. Plan-time evaluation does not change the earlier query's policy results.

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 successfully 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: