Terraform Search と一括インポート

宣言的なクエリを使用して既存のクラウドリソースを検出し、Terraform状態への一括インポート用の設定を生成します。

参考資料:

• Terraform Search - list block
• Bulk Import

使用時機

• アンマネージドなリソースをTerraform制御下に置く場合
• 既存のクラウドインフラストラクチャを監査する場合
• 手動プロビジョニングからIaCへ移行する場合
• 複数のリージョン/アカウント間でリソースを検出する場合

重要: プロバイダーサポートを先に確認してください

開始する前に、ターゲットリソースタイプがサポートされているか確認する必要があります:

# 利用可能なリスト リソースを確認
./scripts/list_resources.sh aws      # 特定のプロバイダー
./scripts/list_resources.sh          # すべての設定済みプロバイダー

判定フロー

1. ターゲットリソースタイプを特定 (例: aws_s3_bucket, aws_instance)

2. サポート状況を確認: ./scripts/list_resources.sh <provider> を実行

3. ワークフローを選択:

   • サポートされている場合: 利用可能なTerraformバージョンを確認してください。
   • Terraformバージョンが1.14.0以上の場合 Terraform Searchワークフロー (以下を参照) を使用
   • サポートされていない場合、またはTerraformバージョンが1.14.0未満の場合: 手動検出ワークフロー (references/MANUAL-IMPORT.mdを参照) を使用

   注記: サポートされるリソースのリストは急速に拡大しています。手動インポートを使用する前に、現在のサポート状況を常に確認してください。

前提条件

クエリを作成する前に、プロバイダーがターゲットリソースタイプのリストリソースをサポートしていることを確認してください。

利用可能なリストリソースの検出

ヘルパースクリプトを実行して、プロバイダーからサポートされているリストリソースを抽出します:

# プロバイダー設定を含むディレクトリから実行 (必要に応じてterraform initを実行)
./scripts/list_resources.sh aws      # 特定のプロバイダー
./scripts/list_resources.sh          # すべての設定済みプロバイダー

または、プロバイダースキーマを手動でクエリ:

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

Terraform Searchには初期化済みのワーキングディレクトリが必要です。クエリを実行する前に、必要なプロバイダーを備えた設定があることを確認してください:

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

terraform init を実行してプロバイダーをダウンロードしてから、クエリに進んでください。

Terraform Searchワークフロー (サポートされているリソースのみ)

1. list ブロックで検索クエリを定義する .tfquery.hcl ファイルを作成
2. terraform query を実行してマッチングリソースを検出
3. -generate-config-out=<file> で設定を生成
4. 生成された resource および import ブロックを確認して精査
5. terraform plan と terraform apply を実行してインポート

クエリファイル構造

クエリファイルは .tfquery.hcl 拡張子を使用し、以下をサポートします:

• 認証用の provider ブロック
• リソース検出用の list ブロック
• パラメータ化用の variable と locals ブロック

# discovery.tfquery.hcl
provider "aws" {
  region = "us-west-2"
}

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

List ブロック構文

list "<list_type>" "<symbolic_name>" {
  provider = <provider_reference>  # 必須

  # オプション: フィルター設定 (プロバイダー固有)
  # `config` ブロックスキーマはプロバイダー固有です。利用可能なオプションは `terraform providers schema -json | jq '.provider_schemas."registry.terraform.io/hashicorp/<provider>".list_resource_schemas."<resource_type>"'` を使用して検出できます

  config {
    filter {
      name   = "<filter_name>"
      values = ["<value1>", "<value2>"]
    }
    region = "<region>"  # AWS固有
  }
  # オプション: 結果を制限
  limit = 100
}

サポートされているリストリソース

リストリソースのプロバイダーサポートはバージョンごとに異なります。検出スクリプトを使用して、特定のプロバイダーバージョンで利用可能なものを常に確認してください。

クエリの例

基本的な検出

# 設定済みリージョンのすべてのEC2インスタンスを検出
list "aws_instance" "all" {
  provider = aws
}

フィルター付き検出

# タグでインスタンスを検出
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"]
    }
  }
}

マルチリージョン検出

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
  }
}

パラメータ化されたクエリ

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

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

クエリの実行

# クエリを実行して結果を表示
terraform query

# 設定ファイルを生成
terraform query -generate-config-out=imported.tf

# 変数を渡す
terraform query -var='target_environment=production'

クエリ出力形式

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

カラム: <query_address> <identity_attributes> <name_tag>

生成された設定

-generate-config-out フラグは以下を作成します:

# __generated__ by Terraform
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"
  }
}

生成後のクリーンアップ

生成された設定にはすべての属性が含まれます。以下の方法でクリーンアップしてください:

1. 計算済み/読み取り専用属性を削除
2. ハードコードされた値を変数で置き換え
3. 適切なリソース命名を追加
4. 適切なファイルに整理

# 変更前: 生成済み
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
  }
}

アイデンティティでのインポート

生成されたインポートはアイデンティティベースのインポート (Terraform 1.12以上) を使用します:

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

ベストプラクティス

クエリ設計

• 広範囲から始めて、フィルターを追加して結果を絞る
• limit を使用してスカイオーバーフローを防止
• 設定を生成する前にクエリをテスト

設定管理

• 適用する前にすべての生成されたコードを確認
• 不要なデフォルト値を削除
• 一貫した命名規則を使用
• 適切な変数抽象化を追加

トラブルシューティング

問題	解決方法
"No list resources found"	プロバイダーバージョンがリストリソースをサポートしていることを確認
クエリが空を返す	リージョンとフィルター値を確認
生成された設定にエラーがある	計算済み属性を削除し、廃止された引数を修正
インポートが失敗する	リソースが既に状態にないことを確認

完全な例

# main.tf - プロバイダーを初期化
terraform {
  required_version = ">= 1.14"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.0"  # 常に最新バージョンを使用
    }
  }
}

# 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
}

# ワークフローを実行
terraform init
terraform query
terraform query -generate-config-out=generated.tf
# generated.tf を確認してクリーンアップ
terraform plan
terraform apply