Terraform Search and Bulk Import
Discover existing cloud resources using declarative queries and generate configuration for bulk import into Terraform state.
References:
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
IMPORTANT: Check Provider Support First
BEFORE starting, you MUST verify the target resource type is supported:
./scripts/list_resources.sh aws
./scripts/list_resources.sh
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.
Prerequisites
Before writing queries, verify the provider supports list resources for your target resource type.
Discover Available List Resources
Run the helper script to extract supported list resources from your provider:
./scripts/list_resources.sh aws
./scripts/list_resources.sh
Or manually query the provider schema:
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:
terraform {
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 6.0"
}
}
}
Run terraform init to download the provider, then proceed with queries.
Terraform Search Workflow (Supported Resources Only)
- 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
Query File Structure
Query files use .tfquery.hcl extension and support:
provider blocks for authenticationlist blocks for resource discoveryvariable and locals blocks for parameterization
provider "aws" {
region = "us-west-2"
}
list "aws_instance" "all" {
provider = aws
}
List Block Syntax
list "<list_type>" "<symbolic_name>" {
provider = <provider_reference>
config {
filter {
name = "<filter_name>"
values = ["<value1>", "<value2>"]
}
region = "<region>"
}
limit = 100
}
Supported List Resources
Provider support for list resources varies by version. Always check what's available for your specific provider version using the discovery script.
Query Examples
Basic Discovery
list "aws_instance" "all" {
provider = aws
}
Filtered Discovery
list "aws_instance" "production" {
provider = aws
config {
filter {
name = "tag:Environment"
values = ["production"]
}
}
}
list "aws_instance" "large" {
provider = aws
config {
filter {
name = "instance-type"
values = ["t3.large", "t3.xlarge"]
}
}
}
Multi-Region Discovery
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
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
terraform query
terraform query -generate-config-out=imported.tf
terraform query -var='target_environment=production'
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>
Generated Configuration
The -generate-config-out flag creates:
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"
}
}
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
resource "aws_instance" "all_0" {
ami = "ami-0c55b159cbfafe1f0"
instance_type = "t2.micro"
arn = "arn:aws:ec2:..."
id = "i-0abc123"
}
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
}
}
Import by Identity
Generated imports use identity-based import (Terraform 1.12+):
import {
to = aws_instance.web
provider = aws
identity = {
account_id = "123456789012"
id = "i-0abc123"
region
