terraform-search-import

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Terraform Search and Bulk Import

Terraform 搜索与批量导入

Discover existing cloud resources using declarative queries and generate configuration for bulk import into Terraform state.

References:

通过声明式查询发现现有云资源，并生成配置以批量导入到Terraform状态中。

参考链接：

When to Use

适用场景

Bringing unmanaged resources under Terraform control
Auditing existing cloud infrastructure
Migrating from manual provisioning to IaC
Discovering resources across multiple regions/accounts

将未受管控的资源纳入Terraform管控
审计现有云基础设施
从手动配置迁移至IaC
跨多个区域/账号发现资源

IMPORTANT: Check Provider Support First

重要提示：请先检查提供商支持情况

BEFORE starting, you MUST verify the target resource type is supported:

bash

undefined

开始操作前，必须验证目标资源类型是否受支持：

bash

undefined

Check what list resources are available

查看可用的list资源

./scripts/list_resources.sh aws # Specific provider ./scripts/list_resources.sh # All configured providers

undefined

./scripts/list_resources.sh aws # 指定提供商 ./scripts/list_resources.sh # 所有已配置的提供商

undefined

Decision Tree

决策流程

Identify target resource type (e.g., aws_s3_bucket, aws_instance)
Check if supported: Run
```
./scripts/list_resources.sh <provider>
```
Choose workflow:
- ** If supported**: Check for terraform version available.
- ** If terraform version is above 1.14.0** Use Terraform Search workflow (below)
- ** If not supported or terraform version is below 1.14.0 **: Use Manual Discovery workflow (see references/MANUAL-IMPORT.md)
Note: The list of supported resources is rapidly expanding. Always verify current support before using manual import.

确定目标资源类型（例如：aws_s3_bucket、aws_instance）
检查支持情况：运行
```
./scripts/list_resources.sh <provider>
```
选择工作流：
- 若受支持：检查可用的Terraform版本。
- 若Terraform版本高于1.14.0：使用下方的Terraform Search工作流
- 若不受支持或Terraform版本低于1.14.0：使用手动发现工作流（参见 references/MANUAL-IMPORT.md）
注意：受支持的资源列表正在快速扩充。使用手动导入前，请务必确认当前的支持情况。

Prerequisites

前置条件

Before writing queries, verify the provider supports list resources for your target resource type.

编写查询之前，请确认提供商支持目标资源类型的list资源。

Discover Available List Resources

发现可用的List资源

Run the helper script to extract supported list resources from your provider:

bash

undefined

运行辅助脚本从提供商中提取受支持的list资源：

bash

undefined

From a directory with provider configuration (runs terraform init if needed)

在包含提供商配置的目录中运行（如有需要会执行terraform init）

./scripts/list_resources.sh aws # Specific provider ./scripts/list_resources.sh # All configured providers


Or manually query the provider schema:

```bash
terraform providers schema -json | jq '.provider_schemas | to_entries | map({key: (.key | split("/")[-1]), value: (.value.list_resource_schemas // {} | keys)})'

Terraform Search requires an initialized working directory. Ensure you have a configuration with the required provider before running queries:

hcl

undefined

./scripts/list_resources.sh aws # 指定提供商 ./scripts/list_resources.sh # 所有已配置的提供商


或手动查询提供商架构：

```bash
terraform providers schema -json | jq '.provider_schemas | to_entries | map({key: (.key | split("/")[-1]), value: (.value.list_resource_schemas // {} | keys)})'

Terraform Search需要已初始化的工作目录。运行查询前，请确保您的配置中包含所需的提供商：

hcl

undefined

terraform.tf

terraform { required_providers { aws = { source = "hashicorp/aws" version = "~> 6.0" } } }


Run `terraform init` to download the provider, then proceed with queries.

terraform { required_providers { aws = { source = "hashicorp/aws" version = "~> 6.0" } } }


运行 `terraform init` 下载提供商，然后继续执行查询。

Terraform Search Workflow (Supported Resources Only)

Terraform Search工作流（仅适用于受支持的资源）

Create
```
.tfquery.hcl
```
files with
```
list
```
blocks defining search queries
Run
```
terraform query
```
to discover matching resources
Generate configuration with
```
-generate-config-out=<file>
```
Review and refine generated
```
resource
```
and
```
import
```
blocks
Run
```
terraform plan
```
and
```
terraform apply
```
to import

创建包含
```
list
```
块的
```
.tfquery.hcl
```
文件，定义搜索查询
运行
```
terraform query
```
发现匹配的资源
使用
```
-generate-config-out=<file>
```
生成配置
审阅并优化生成的
```
resource
```
和
```
import
```
块
运行
```
terraform plan
```
和
```
terraform apply
```
完成导入

Query File Structure

查询文件结构

Query files use

.tfquery.hcl

extension and support:

```
provider
```
blocks for authentication
```
list
```
blocks for resource discovery
```
variable
```
and
```
locals
```
blocks for parameterization

hcl

undefined

查询文件使用

.tfquery.hcl

扩展名，支持：

用于身份验证的
```
provider
```
块
用于资源发现的
```
list
```
块
用于参数化的
```
variable
```
和
```
locals
```
块

hcl

undefined

discovery.tfquery.hcl

provider "aws" { region = "us-west-2" }

list "aws_instance" "all" { provider = aws }

undefined

provider "aws" { region = "us-west-2" }

list "aws_instance" "all" { provider = aws }

undefined

List Block Syntax

List块语法

hcl

list "<list_type>" "<symbolic_name>" {
  provider = <provider_reference>  # Required
  
  # Optional: filter configuration (provider-specific)
  config {
    filter {
      name   = "<filter_name>"
      values = ["<value1>", "<value2>"]
    }
    region = "<region>"  # AWS-specific
  }
}

Note: The

config

block schema is provider-specific. Discover available options:

bash

terraform providers schema -json | jq '.provider_schemas."registry.terraform.io/hashicorp/<provider>".list_resource_schemas."<resource_type>"'

}

Optional: limit results

limit = 100 }

undefined

hcl

list "<list_type>" "<symbolic_name>" {
  provider = <provider_reference>  # 必填
  
  # 可选：过滤配置（提供商特定）
  config {
    filter {
      name   = "<filter_name>"
      values = ["<value1>", "<value2>"]
    }
    region = "<region>"  # AWS特定
  }
}

注意：

config

块的架构由提供商决定。可通过以下方式发现可用选项：

bash

terraform providers schema -json | jq '.provider_schemas."registry.terraform.io/hashicorp/<provider>".list_resource_schemas."<resource_type>"'

可选：限制结果数量

limit = 100 }

undefined

Supported List Resources

受支持的List资源

Provider support for list resources varies by version. Always check what's available for your specific provider version using the discovery script.

提供商对list资源的支持因版本而异。请始终使用发现脚本检查您所使用的特定提供商版本支持的资源。

Query Examples

查询示例

Basic Discovery

基础发现

hcl

undefined

hcl

undefined

Find all EC2 instances in configured region

查找已配置区域中的所有EC2实例

list "aws_instance" "all" { provider = aws }

undefined

list "aws_instance" "all" { provider = aws }

undefined

Filtered Discovery

过滤发现

hcl

undefined

hcl

undefined

Find instances by tag

按标签查找实例

list "aws_instance" "production" { provider = aws

config { filter { name = "tag:Environment" values = ["production"] } } }

list "aws_instance" "production" { provider = aws

config { filter { name = "tag:Environment" values = ["production"] } } }

Find instances by type

按实例类型查找

list "aws_instance" "large" { provider = aws

config { filter { name = "instance-type" values = ["t3.large", "t3.xlarge"] } } }

undefined

list "aws_instance" "large" { provider = aws

config { filter { name = "instance-type" values = ["t3.large", "t3.xlarge"] } } }

undefined

Multi-Region Discovery

多区域发现

hcl

provider "aws" {
  region = "us-west-2"
}

locals {
  regions = ["us-west-2", "us-east-1", "eu-west-1"]
}

list "aws_instance" "all_regions" {
  for_each = toset(local.regions)
  provider = aws
  
  config {
    region = each.value
  }
}

hcl

provider "aws" {
  region = "us-west-2"
}

locals {
  regions = ["us-west-2", "us-east-1", "eu-west-1"]
}

list "aws_instance" "all_regions" {
  for_each = toset(local.regions)
  provider = aws
  
  config {
    region = each.value
  }
}

Parameterized Queries

参数化查询

hcl

variable "target_environment" {
  type    = string
  default = "staging"
}

list "aws_instance" "by_env" {
  provider = aws
  
  config {
    filter {
      name   = "tag:Environment"
      values = [var.target_environment]
    }
  }
}

hcl

variable "target_environment" {
  type    = string
  default = "staging"
}

list "aws_instance" "by_env" {
  provider = aws
  
  config {
    filter {
      name   = "tag:Environment"
      values = [var.target_environment]
    }
  }
}

Running Queries

运行查询

bash

undefined

bash

undefined

Execute queries and display results

执行查询并显示结果

terraform query

Generate configuration file

生成配置文件

terraform query -generate-config-out=imported.tf

Pass variables

传递变量

terraform query -var='target_environment=production'

undefined

terraform query -var='target_environment=production'

undefined

Query Output Format

查询输出格式

list.aws_instance.all   account_id=123456789012,id=i-0abc123,region=us-west-2   web-server

Columns:

<query_address>   <identity_attributes>   <name_tag>

list.aws_instance.all   account_id=123456789012,id=i-0abc123,region=us-west-2   web-server

列说明：

<query_address>   <identity_attributes>   <name_tag>

Generated Configuration

生成的配置

The

-generate-config-out

flag creates:

hcl

undefined

-generate-config-out

标志会生成以下内容：

hcl

undefined

generated by Terraform

resource "aws_instance" "all_0" { ami = "ami-0c55b159cbfafe1f0" instance_type = "t2.micro"

... all attributes

}

import { to = aws_instance.all_0 provider = aws identity = { account_id = "123456789012" id = "i-0abc123" region = "us-west-2" } }

undefined

resource "aws_instance" "all_0" { ami = "ami-0c55b159cbfafe1f0" instance_type = "t2.micro"

... 所有属性

}

import { to = aws_instance.all_0 provider = aws identity = { account_id = "123456789012" id = "i-0abc123" region = "us-west-2" } }

undefined

Post-Generation Cleanup

生成后清理

Generated configuration includes all attributes. Clean up by:

Remove computed/read-only attributes
Replace hardcoded values with variables
Add proper resource naming
Organize into appropriate files

hcl

undefined

生成的配置包含所有属性。可通过以下方式清理：

移除计算/只读属性
用变量替换硬编码值
添加合适的资源命名
整理到对应的文件中

hcl

undefined

Before: generated

之前：生成的配置

resource "aws_instance" "all_0" { ami = "ami-0c55b159cbfafe1f0" instance_type = "t2.micro" arn = "arn:aws:ec2:..." # Remove - computed id = "i-0abc123" # Remove - computed

... many more attributes

}

resource "aws_instance" "all_0" { ami = "ami-0c55b159cbfafe1f0" instance_type = "t2.micro" arn = "arn:aws:ec2:..." # 移除 - 计算属性 id = "i-0abc123" # 移除 - 计算属性

... 更多属性

}

After: cleaned

之后：清理后的配置

resource "aws_instance" "web_server" { ami = var.ami_id instance_type = var.instance_type subnet_id = var.subnet_id

tags = { Name = "web-server" Environment = var.environment } }

undefined

resource "aws_instance" "web_server" { ami = var.ami_id instance_type = var.instance_type subnet_id = var.subnet_id

tags = { Name = "web-server" Environment = var.environment } }

undefined

Import by Identity

通过身份信息导入

Generated imports use identity-based import (Terraform 1.12+):

hcl

import {
  to       = aws_instance.web
  provider = aws
  identity = {
    account_id = "123456789012"
    id         = "i-0abc123"
    region     = "us-west-2"
  }
}

生成的导入配置使用基于身份的导入（Terraform 1.12+）：

hcl

import {
  to       = aws_instance.web
  provider = aws
  identity = {
    account_id = "123456789012"
    id         = "i-0abc123"
    region     = "us-west-2"
  }
}

Best Practices

最佳实践

Query Design

查询设计

Start broad, then add filters to narrow results
Use
```
limit
```
to prevent overwhelming output
Test queries before generating configuration

先从宽泛的查询开始，再添加过滤条件缩小结果范围
使用
```
limit
```
避免输出结果过多
生成配置前先测试查询

Configuration Management

配置管理

Review all generated code before applying
Remove unnecessary default values
Use consistent naming conventions
Add proper variable abstraction

应用前审阅所有生成的代码
移除不必要的默认值
使用一致的命名规范
添加合适的变量抽象

Troubleshooting

故障排除

Issue	Solution
"No list resources found"	Check provider version supports list resources
Query returns empty	Verify region and filter values
Generated config has errors	Remove computed attributes, fix deprecated arguments
Import fails	Ensure resource not already in state

问题	解决方案
"未找到list资源"	检查提供商版本是否支持list资源
查询返回空结果	验证区域和过滤值是否正确
生成的配置存在错误	移除计算属性，修复已弃用的参数
导入失败	确保资源未已存在于状态中

Complete Example

完整示例

hcl

undefined

hcl

undefined

main.tf - Initialize provider

main.tf - 初始化提供商

terraform { required_version = ">= 1.14" required_providers { aws = { source = "hashicorp/aws" version = "~> 6.0" # Always use latest version } } }

terraform { required_version = ">= 1.14" required_providers { aws = { source = "hashicorp/aws" version = "~> 6.0" # 始终使用最新版本 } } }

discovery.tfquery.hcl - Define queries

discovery.tfquery.hcl - 定义查询

provider "aws" { region = "us-west-2" }

list "aws_instance" "team_instances" { provider = aws

config { filter { name = "tag:Owner" values = ["platform"] } filter { name = "instance-state-name" values = ["running"] } }

limit = 50 }


```bash

provider "aws" { region = "us-west-2" }

list "aws_instance" "team_instances" { provider = aws

config { filter { name = "tag:Owner" values = ["platform"] } filter { name = "instance-state-name" values = ["running"] } }

limit = 50 }


```bash

Execute workflow

执行工作流

terraform init terraform query terraform query -generate-config-out=generated.tf

Review and clean generated.tf

审阅并清理generated.tf

terraform plan terraform apply

undefined

terraform plan terraform apply

undefined