Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -85,8 +85,6 @@ The optional configurations for customizing the agent include building a custom

### Enable search queries

@include 'beta.mdx'

You can query your existing infrastructure to find resources that are not yet managed by Terraform. This makes it easier to identify and import unmanaged resources into your Terraform workspace. Refer to [Import existing resources to state](terraform/cloud-docs/workspaces/import) for more information.

To use the search functionality, you must include the `query` operation in the [`TFE_AGENT_ACCEPT` variable](#accept) when starting your agent.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -298,12 +298,7 @@
{
"title": "Import existing resources",
"path": "workspaces/import",
"alias": "search, terraform search, resource discoverability",
"badge": {
"text": "BETA",
"type": "outlined",
"color": "neutral"
}
"alias": "search, terraform search, resource discoverability"
},
{
"title": "Policy enforcement",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,13 @@ tfc_only: true

# Import existing resources to state

Terraform can search your existing infrastructure for resources to let you import any unmanaged resources to an HCP Terraform workspace in bulk. For instructions on importing single resources or small batches of resources in your configuration, refer to [Import a single resource](/terraform/language/v1.14.x/import/single-resource).

@include 'beta.mdx'
Terraform can search your existing infrastructure for resources to let you import any unmanaged resources to an HCP Terraform workspace in bulk. For instructions on importing single resources or small batches of resources in your configuration, refer to [Import a single resource](/terraform/language/import/single-resource).

## Overview

You can search for unmanaged resources in [UI and VCS-driven](/terraform/cloud-docs/run/ui) and [CLI-driven](/terraform/cloud-docs/run/cli) workspaces. HCP Terraform presents results so that you can use the UI to import the resources and begin managing them as code. 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](/terraform/language/v1.14.x/import/bulk) for more information.
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](/terraform/language/import/bulk) for more information.
1. **Run the queries**: You can run queries in the HCP Terraform UI or run the Terraform CLI on your local workstation.
1. **Review search results**: HCP Terraform shows the management status for resources it finds.
1. **Generate code**: HCP Terraform generates `import` and `resource` blocks for the resources it discovers.
Expand All @@ -26,13 +24,13 @@ If you use HCP Terraform agents for your runs, you must enable the `query` opera

## 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](/terraform/cloud-docs/workspaces/settings#general) for more information about changing workspace settings.
You must enable Terraform 1.14.0 or newer for your workspace to access the **Search & Import** page. Refer to the [general workspace settings documentation](/terraform/cloud-docs/workspaces/settings#general) 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](/terraform/language/v1.14.x/import/bulk) for instructions on how to 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](/terraform/language/import/bulk) for instructions on how to define queries.

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

Expand All @@ -52,11 +50,11 @@ As the query progresses, HCP Terraform loads the results to the page.

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](/terraform/language/v1.14.x/import#resource-identity) as a resource applied by a similar provider version.
- **Unknown** indicates that the resource has the same [identity](/terraform/language/v1.14.x/import#resource-identity) as a resource applied by an older version of Terraform or older provider version.
- **Managed** indicates that the resource has the same [identity](/terraform/language/import#resource-identity) as a resource applied by a similar provider version.
- **Unknown** indicates that the resource has the same [identity](/terraform/language/import#resource-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](/terraform/language/v1.14.x/import#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.
Over time, providers may change their [resource identity](/terraform/language/import#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:

Expand All @@ -75,7 +73,7 @@ Copy the code to your Terraform configuration and apply the configuration. Befor
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.
- Run the `terraform apply` command on your 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
Expand Down
6 changes: 0 additions & 6 deletions content/terraform/v1.13.x/docs/cli/commands/import.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,6 @@ The `terraform import` command imports existing resources into Terraform. Refer

> **Hands-on:** Try the [Import Terraform Configuration](/terraform/tutorials/state/state-import?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial.

<Note>

Terraform `v1.14.x (beta)` lets you search existing infrastructure for resources, generate configuration, and import them in bulk. Refer to the [Import existing resources in bulk](/terraform/language/v1.14.x/import/bulk) beta documentation for more information.

</Note>

## Usage

Usage: `terraform import [options] ADDRESS ID`
Expand Down
6 changes: 0 additions & 6 deletions content/terraform/v1.13.x/docs/cli/import/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,6 @@ This topic provides an overview of the Terraform commands that let you import ex

> **Hands-on:** Try the [Import Terraform Configuration](/terraform/tutorials/state/state-import?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial.

<Note>

Terraform `v1.14.x (beta)` lets you search existing infrastructure for resources, generate configuration, and import them in bulk. Refer to the [Import existing resources in bulk](/terraform/language/v1.14.x/import/bulk) beta documentation for more information.

</Note>

## Workflows

You can import an existing resource to state from the Terraform CLI. You can also perform import operations using HCP Terraform. To import multiple resources, use the `import` block.
Expand Down
6 changes: 0 additions & 6 deletions content/terraform/v1.13.x/docs/cli/import/usage.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,6 @@ This topic describes how to use the `terraform import` command to import existin

> **Hands-on:** Try the [Import Terraform Configuration](/terraform/tutorials/state/state-import?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial.

<Note>

Terraform `v1.14.x (beta)` implements a new workflow for searching existing infrastructure for resources, generating configuration, and importing them in bulk. Refer to the [Import existing resources in bulk](/terraform/language/v1.14.x/import/bulk) beta documentation for more information.

</Note>

## Overview

Use the `terraform import` command to import existing infrastructure to Terraform state. The `terraform import` command can only import one resource at a time. It cannot simultaneously import an entire collection of resources, such as an AWS VPC.
Expand Down
6 changes: 0 additions & 6 deletions content/terraform/v1.13.x/docs/language/block/import.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,6 @@ description: >-

The `import` block instructs Terraform to import existing infrastructure resources into Terraform. Refer to [Import existing resources](/terraform/language/import) for more information.

<Note>

Terraform `v1.14.x (beta)` lets you configure queries to search your existing infrastructure for resources and generate configuration to import them. Refer to the [list block reference](/terraform/language/v1.14.x/block/tfquery/list) beta documentation for more information.

</Note>

## Configuration model

An `import` block supports the following configuration:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,19 +6,13 @@ description: >-

# Generating configuration

Terraform can generate code for the resources you define in [`import` blocks](/terraform/language/import) that do not already exist in your configuration. Terraform produces HCL to act as a template that contains Terraform's best guess at the appropriate value for each resource argument.
This topic describes how to generate code for single resources or small batches of resources defined in [`import` blocks](/terraform/language/import). For instructions querying your existing infrastructure for resources and generating `import` configuration based on search results, refer to the [Import existing resources in bulk](/terraform/language/import/bulk).

~> **Experimental:** Configuration generation is available in Terraform v1.5 as an experimental feature. Later minor versions may contain changes to the formatting of generated configuration and behavior of the `terraform plan` command using the `-generate-config-out` flag.

<Note>

Terraform `v1.14.x (beta)` lets you configure queries to search your existing infrastructure for resources and generate configuration to import them. Refer to the [Import existing resources in bulk](/terraform/language/v1.14.x/import/bulk) beta documentation for more information.

</Note>

Starting with Terraform's generated HCL, we recommend iterating to find your ideal configuration by removing some attributes, adjusting the value of others, and rearranging `resource` blocks into files and modules as appropriate.

To generate configuration, run `terraform plan` with the `-generate-config-out` flag and supply a new file path. Do not supply a path to an existing file, or Terraform throws an error.
To generate configuration, run `terraform plan` with the `-generate-config-out` flag and supply a new file path. Do not supply a path to an existing file, or Terraform throws an error. Terraform produces HCL to act as a template that contains Terraform's best guess at the appropriate value for each resource argument.

```shell
$ terraform plan -generate-config-out="generated_resources.tf"
Expand Down
6 changes: 0 additions & 6 deletions content/terraform/v1.13.x/docs/language/import/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,6 @@ You can import existing infrastructure resources into your Terraform state so th

> **Hands-on:** Try the [State Import](/terraform/tutorials/state/state-import?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial.

<Note>

Terraform `v1.14.x (beta)` implements a new workflow for searching existing infrastructure for resources, generating configuration, and importing them in bulk. Refer to the [Import existing resources in bulk](/terraform/language/v1.14.x/import/bulk) beta documentation for more information.

</Note>

## Overview

When you import existing infrastructure into state, you must also define the Terraform configuration corresponding to that resource to manage the rest of its lifecycle. You can manually write all of the configuration or use the Terraform CLI to generate configuration for resources your are importing. When you import resources, Terraform pulls all of the resource's attributes into the state file, but you do not need to define all of them in the `resource` block.
Expand Down
9 changes: 3 additions & 6 deletions content/terraform/v1.14.x/data/language-nav-data.json
Original file line number Diff line number Diff line change
Expand Up @@ -213,7 +213,8 @@
{ "title": "Overview", "path": "import"},
{
"title": "Import resources in bulk",
"path": "import/bulk"
"path": "import/bulk",
"alias": "search, terraform search, query, list"
},
{ "title": "Import a single resource", "path": "import/single-resource" },
{
Expand Down Expand Up @@ -384,11 +385,7 @@
{
"title": "list",
"path": "block/tfquery/list",
"badge": {
"text": "BETA",
"type": "outlined",
"color": "neutral"
}
"alias": "search, terraform search"
},
{
"title": "locals",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,6 @@ description: |-

The `list` block defines a query that reads existing infrastructure and returns resources that you can import to your Terraform workspace. You can only add `list` blocks to configuration files with `.tfquery.hcl` extensions. This topic provides reference information about configuring `list` blocks in `.tfquery.hcl` files. Refer to [Import existing resources in bulk](/terraform/language/import/bulk) for information about querying and importing resources.

@include 'beta.mdx'

## Configuration model

A `list` block supports the following configuration:
Expand Down
19 changes: 2 additions & 17 deletions content/terraform/v1.14.x/docs/language/import/bulk.mdx
Original file line number Diff line number Diff line change
@@ -1,14 +1,12 @@
---
page_title: Import existing resources in bulk
description: Learn how to query existing infrastructure for unmanaged resources so you can import them into Terraform in bulk
description: Learn how to use Terraform search functionality to query existing infrastructure for unmanaged resources so that you can import them into Terraform state in bulk
---

# Import existing resources in bulk

You can configure queries that instruct Terraform to search your existing infrastructure for unmanaged resources. Terraform can also generate configuration for importing the resources it finds so that you can import them to your Terraform workspace in bulk. For information about importing single resources or small batches of resources, refer to [Import single resources](/terraform/language/import/single-resource) for instructions.

@include 'beta.mdx'

## Introduction

For organizations with large sets of infrastructure resources, manually identifying and importing them is tedious and labor intensive, even when using third-party tools or custom scripts. To alleviate this burden, you can write HCL-based queries and run them with the Terraform CLI to retrieve unmanaged resources so that you can import them in bulk.
Expand All @@ -26,18 +24,7 @@ Terraform v1.12 or newer is required to search for resources according to their

### Supported providers

Verify that the resource type you want to search for is supported. For the initial beta release, you can use `list` blocks to query for the following resource types. This list may change. Refer to your provider documentation for the most up-to-date information.

#### AWS provider

- [`aws_batch_job_queue`](https://github.com/hashicorp/terraform-provider-aws/blob/main/website/docs/list-resources/batch_job_queue.html.markdown)
- [`aws_cloudwatch_log_group`](https://github.com/hashicorp/terraform-provider-aws/blob/main/website/docs/list-resources/cloudwatch_log_group.html.markdown)
- [`aws_iam_role`](https://github.com/hashicorp/terraform-provider-aws/blob/main/website/docs/list-resources/iam_role.html.markdown)
- [`aws_instance`](https://github.com/hashicorp/terraform-provider-aws/blob/main/website/docs/list-resources/instance.html.markdown)

#### AWS CC provider

All resources in this provider support `list` blocks. Because this provider is fully generated and doesn't accept provider-specific configurations, omit the `config` block when defining queries for AWS CC resources.
Verify that the resource type you want to search for is supported. Refer to your provider documentation for the most up-to-date information.

## Define a query

Expand Down Expand Up @@ -120,8 +107,6 @@ If HCP Terraform is connected to your version control system (VCS), you can also

After copying the configuration to your HCP Terraform workspace, you can either run the query locally using the Terraform CLI or run the query in the HCP Terraform UI. Refer to [Import existing resources to state](/terraform/cloud-docs/workspaces/import) in the HCP Terraform documentation for instructions on how to run queries and import resources from the UI.

Refer to [Import existing resources to state in bulk](/terraform/cloud-docs/workspaces/import) in the HCP Terraform documentation for details.

### Terraform CLI

Run the [`terraform query` command](/terraform/cli/commands/query) to retrieve the resource types specified in your `list` blocks. The command prints the results to your console. By default, each result includes the following information:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ description: >-

# Generating configuration

This topic describes how to generate code for single resources or small batches of resources defined in [`import` blocks](/terraform/language/block/import). For instructions querying your existing infrastructure for resources and generating `import` configuration based on search results, refer to the [Import existing resources in bulk](/terraform/language/import/bulk).

~> **Experimental:** Configuration generation is available in Terraform v1.5 as an experimental feature. Later minor versions may contain changes to the formatting of generated configuration and behavior of the `terraform plan` command using the `-generate-config-out` flag.

Terraform can generate code for the resources you define in [`import` blocks](/terraform/language/import) that do not already exist in your configuration. Terraform produces HCL to act as a template that contains Terraform's best guess at the appropriate value for each resource argument.
Expand Down
Loading
Loading