# Terraform の import ブロックでコンソール構築の AWS 本番を取り込む — コンソールの名前を残し、削除は CI で止める

> コンソールで作られた AWS のデータ層を、import ブロックで Terraform の管理下に移しました。名前はコンソールのものを残し、本番には削除を止めるチェックを通してから手動で適用します。

- Source: https://oharu121.com/ja/blog/terraform-import-blocks-console-built-aws-prod-delete-guard/
- Published: 2026-11-08T11:51:21+09:00
- Tags: Terraform, AWS, GitHub Actions

---
## はじめに

私が関わっている AWS データ層のテストアカウントは、Terraform で構築しています。元になっているのは、本番を読み取り専用で採取した設定から書いたモジュールです。経緯は[前回の記事](/ja/blog/terraform-rebuild-console-aws-account-prod-spec-parity-oidc/)で書きました。その記事では、同じモジュールを本番に使うときも「tfvars ファイルを 1 つ足すだけ」で済むと書いています。

一方で、本番は相変わらずコンソールから手作業で作り、手作業で変更していました。私は本番も同じモジュールで定義し、apply は自分で手動で開始する形にしたいと考えました。ところが、本番に対して最初に実行した読み取り専用の `terraform plan` には、**7 つのリソースの削除が含まれていました**。コンソールが付けた名前と、モジュールの名前が違っていたためです。

今では本番は既存のリソースを import し、**コンソールが付けた名前をそのまま残しています**。apply は私が手動で開始するワークフローからだけ実行し、そのワークフローは**削除を含む plan を拒否します**。リポジトリが両方のアカウントを定義するようになり、`main` にマージしても本番は変わりません。

## 1 つのモジュール、2 つのルート、2 つの適用経路

両方のアカウントは同じデータ層モジュールを使い、それぞれ専用のルートディレクトリと state を持ちます。state は、Terraform が管理しているリソースを記録するファイルです。ルートごとに 1 つずつあるので、2 つのアカウントのリソースが混ざることはありません。ルートとは `terraform plan` を実行するディレクトリのことで、次の 3 つを置きます。

1. **バックエンド**：state の保存先を指定します。たとえば S3 バケットです。
2. **プロバイダ**：Terraform が操作する AWS アカウントを設定します。ルートごとに 1 つのアカウントだけを指します。
3. **`module` ブロック**：データ層モジュールを呼び出し、そのアカウント用の値を渡します。

```text title="terraform/"
modules/
  bootstrap/     state バケットと GitHub Actions のロール。両アカウントで共有
  data-layer/    S3、Glue、OpenSearch Serverless、Bedrock ナレッジベース、Lambda、AgentCore
bootstrap/
  test/
  prod/
envs/
  test/          main.tf
  prod/          main.tf, imports.tf
```

本番のルートがテストのルートと違うのは次の 2 か所です。

1. `imports.tf`：モジュールのリソースを、本番に実在するリソースに対応づけます。
2. `main.tf`：それらのリソースにコンソールが付けた名前を、モジュールに渡します。

プルリクエストごとに、両方のアカウントの plan が実行されます。**テストアカウントにはプルリクエストが `main` にマージされたときに適用し、本番には私がワークフローを手動で開始したときにだけ適用します**。plan にリソースの削除が含まれていれば、本番の実行は何も適用する前に失敗します。

そのため、本番でコンソールから行った変更は、次のプルリクエストの本番の plan にコードとの差分として現れます。次に本番へ適用すると、その変更はコードどおりに戻ります。ただし、戻すためにリソースの削除が必要な場合は、削除チェックが実行を止めます。

*Figure — ApplyPaths: プルリクエストごとに両方のアカウントを plan します。マージするとテストに適用されます。本番には、main から手動で開始した実行で、保存した plan が削除チェックを通ったときにだけ適用します。*

## 読み取り専用の plan で本番のリソースの取り込みをリハーサルする

**`import` ブロックとローカルバックエンドを組み合わせると、本番に何も書き込まずに、本番を取り込んだら何が起きるかを `terraform plan` で確かめられます**。`import` ブロックには、既存のリソースと、それを管理するモジュール内のアドレスを書きます。`plan` は稼働中のリソースを読んで設定と比べ、実際に import する前に差分を表示します。

私は `List`、`Get`、`Describe` の呼び出しで ID を集め、リソースごとに `import` ブロックを 1 つ書きました。同じ形が続くものは `for_each` でまとめています。

```hcl title="terraform/envs/prod/imports.tf"
import {
  to = module.data_layer.aws_bedrockagent_knowledge_base.this["handbook"]
  id = "KBID000001"
}

import {
  to = module.data_layer.aws_bedrockagent_data_source.this["handbook"]
  id = "DSID000001,KBID000001"
}

import {
  for_each = local.buckets
  to       = module.data_layer.aws_s3_bucket.this[each.key]
  id       = each.value
}
```

本番の `main.tf` は state を S3 バケットに保存する設定ですが、そのバケットはまだなかったので、`terraform plan` はそもそも実行できませんでした。また、リハーサルで本番の state に書き込むべきでもありません。

名前が `_override.tf` で終わるファイルを追加すると、Terraform はその内容でほかのファイルの同じ設定を上書きします。そして**オーバーライドファイルの backend ブロックは元の backend ブロックより優先される**ので、一時的なオーバーライドファイルを 1 つ置くだけで、state の保存先をローカルディスクに変えられます。`main.tf` には手を入れずに済み、S3 バケットも必要ありません。

```hcl title="terraform/envs/prod/zz_local_override.tf"
terraform {
  backend "local" {
    path = "/tmp/prod-rehearsal.tfstate"
  }
}
```

本番の認証情報で実行すると、`plan` はすべてのリソースを読み取り、アカウントには何も変更を加えません。

```bash
aws-vault exec prod -- terraform -chdir=terraform/envs/prod plan -lock=false
# Plan: 44 to import, 17 to add, 23 to change, 7 to destroy.
```

*Figure — ReadOnlyPlan: import ブロックが既存のリソースを指定し、オーバーライドファイルが state をローカルに留め、plan は本番を読むだけです。結果として、実際に apply したら何が起きるかの一覧が得られます。*

本番の state バケットができてからオーバーライドファイルを削除すると、同じコマンドが S3 バックエンドに対して動きました。

## plan で 7 つのリソースが置き換えになった理由

置き換えになる 7 つのリソースのうち、**6 つは名前が違うためでした**。私がコンソールでこれらのリソースを作ったときにコンソールが名前を自動で付けていて、モジュールは独自の規則で別の名前を組み立てます。残りの 1 つはインラインポリシーで、所属するロールが置き換えになるので一緒に置き換えられます。

Terraform はナレッジベースのデータソースや IAM ロールの名前をその場で変更できません。名前が違えば、新しいリソースを作ってから古いリソースを削除するしかありません。

```text
# module.data_layer.aws_bedrockagent_data_source.this["catalog"] must be replaced
    ~ name = "knowledge-base-quick-start-xxxxx-data-source" -> "app-catalog-s3" # forces replacement

# module.data_layer.aws_iam_role.kb["catalog"] must be replaced
    ~ name = "AmazonBedrockExecutionRoleForKnowledgeBase_xxxxx" -> "app-kb-catalog" # forces replacement
```

| リソース | 置き換え | 置き換えで失うもの |
| --- | --- | --- |
| ナレッジベースのデータソース | 2 | データソース ID が変わり、すべてのドキュメントを取り込み直す |
| ナレッジベース、Lambda、ゲートウェイの IAM ロール | 4 | 新しいロールは参照先が切り替わる前に作られるので、切り替えが反映されるまで呼び出しが `AccessDenied` で失敗しうる |
| Lambda ロールのインラインポリシー | 1 | ロールと一緒に作り直される |

ナレッジベースの 1 つには、モジュールが宣言していない `aws-apn-id` タグが付いていたので、plan にはこのタグの削除が含まれていました。また AgentCore のサービスリンクロールは作成として計画されていましたが、本番にはすでにあったので、apply はその作成で失敗していたはずです。

### ナレッジベースの名前から作っていたデータソース名

モジュールは、各データソースの名前をナレッジベースの名前から組み立てていました。私がコンソールでナレッジベースの名前を変え、モジュールの名前も新しい名前に合わせると、plan はナレッジベースをその場での更新として扱いました。**しかしデータソースの名前はナレッジベースの名前から作られているので、一緒に変わります**。データソースは名前をその場で変えられないので、plan では置き換えになりました。

そこで各データソースの名前は、ナレッジベースの名前から組み立てるのをやめて、専用の固定の名前にしました。

```hcl title="modules/data-layer/bedrock_kb.tf" del={2} ins={3}
resource "aws_bedrockagent_data_source" "this" {
  name = "${replace(each.value.name, "_", "-")}-s3"
  name = each.value.data_source_name
  # …
}
```

この変更で、テストの plan は `1 to add, 1 to change, 1 to destroy` から `0 to add, 1 to change, 0 to destroy` に変わりました。

## `existing_names` でコンソールの名前を残す

**私は、コンソールが付けた名前を受け取る省略可能な変数を 1 つ追加しました。変数が空のときは、モジュール独自の命名規則で名前を付けます**。テストは何も渡さないのでこれまでの名前のまま、本番はコンソールの名前を渡します。

```hcl title="modules/data-layer/variables.tf"
variable "existing_names" {
  type = object({
    data_sources  = optional(map(string), {})
    kb_roles      = optional(map(string), {})
    reviewer_role = optional(string)
    gateway_role  = optional(string)
  })
  default = {}
}
```

```hcl title="modules/data-layer/bedrock_kb.tf"
resource "aws_iam_role" "kb" {
  name = lookup(var.existing_names.kb_roles, each.key, "${local.prefix}-kb-${each.key}")
  # …
}
```

*Figure — NameAdoption: モジュール独自の名前では置き換えになります。existing_names でコンソールの名前を渡すと、import でリソースをそのまま取り込めます。*

残りの 2 つの問題、`aws-apn-id` タグの削除とサービスリンクロールの作成は、どちらも 1 行で直せました。ナレッジベースに `ignore_changes = [tags["aws-apn-id"]]` を付けるとそのタグには触れなくなり、サービスリンクロールに `import` ブロックを書くと、作成が取り込みに変わります。

```bash
aws-vault exec prod -- terraform -chdir=terraform/envs/prod plan -lock=false
# Plan: 45 to import, 9 to add, 28 to change, 0 to destroy.
```

**9 件の追加は、既存のものを何も変えません**。内訳は次の 4 種類です。

1. 取り込んだロールに付ける 3 つのインラインポリシー
2. 同じロールへの 2 つのポリシーのアタッチ
3. OpenSearch のデータアクセスポリシー 1 つ
4. インデックスの存在を確かめる `terraform_data` と、その後ろの `time_sleep`

テストの plan は引き続き `No changes. Your infrastructure matches the configuration.` を出力しました。

### リソースの古い名前を残した理由

決めた時点で気にしていたのは、名前を移すあいだに権限が途切れる時間ができることでした。モジュールの名前に移行すると、Terraform は新しいロールを作り、ナレッジベース、Lambda、ゲートウェイの参照先をそのロールに切り替え、古いロールを削除します。その間の呼び出しはどれも失敗する可能性があります。

ただし、名前を残すことには代償もありました。**取り込んだロールにはどれも、コンソールが付けた管理ポリシーとモジュールのインラインポリシーの両方が付いていて**、同じ権限が二重にある状態です。私はこの点をスナップショット差分スクリプトの想定内の差分の一覧（`EXPECTED_DIFFS`）に加え、理由も書き添えました。

## 本番には手動で、削除チェックを通して適用する

**本番への適用は、`target: prod` を指定した `workflow_dispatch` の実行からだけ行い、ジョブはチェックした plan そのものを適用します**。`workflow_dispatch` は、GitHub Actions で手動で開始する実行のトリガーです。入力は `test` と `prod` の選択式で既定値を `test` にしたので、テストの経路は変わりません。

```yaml title=".github/workflows/terraform.yml"
on:
  workflow_dispatch:
    inputs:
      target:
        description: apply する環境
        type: choice
        options: [test, prod]
        default: test

jobs:
  apply-prod:
    if: github.event_name == 'workflow_dispatch' && inputs.target == 'prod'
    environment: prod
    env:
      TF_DIR: terraform/envs/prod
```

*Image: ブランチに main、target 入力に prod を選んだ GitHub の Run workflow ダイアログ*

*main からワークフローを手動で実行し、target に prod を選びます。*

`prod` environment は `main` からしかデプロイできません。[前回の記事](/ja/blog/terraform-rebuild-console-aws-account-prod-spec-parity-oidc/)で `test` に設定したのと同じ deployment branch policy です。必須のレビュアーは設定していないので、実行に誰かの承認は要りません。AWS の apply ロールは、この environment から発行された OIDC トークン（subject が `prod` environment を指すもの）だけを信頼します。

チェックは保存した plan を JSON として読み、**アクションに `delete` を含むリソースが 1 つでもあれば失敗します**。Terraform の JSON 形式では、置き換えは `["delete", "create"]` または `["create", "delete"]` と書かれます。ドキュメントによると、この形になっているのは、呼び出し側が `delete` を探すだけで、削除が起きる次の 3 つのケースをすべて拾えるようにするためです。

- `["delete"]`：リソースを削除するだけです。
- `["delete", "create"]`：古いリソースを先に削除してから新しいリソースを作る置き換えで、Terraform の既定の動作です。
- `["create", "delete"]`：新しいリソースを先に作ってから古いリソースを削除する置き換えで、`create_before_destroy` を設定したリソースで使われます。

ワークフローでのチェックは次のとおりです。

```yaml title=".github/workflows/terraform.yml"
- name: terraform plan
  run: terraform -chdir="$TF_DIR" plan -input=false -no-color -lock-timeout=10m -out=tfplan

- name: Refuse deletes and replacements
  run: |
    terraform -chdir="$TF_DIR" show -json tfplan > plan.json
    jq -r '.resource_changes[] | select(.change.actions | index("delete")) | "\(.change.actions | join("/")) \(.address)"' plan.json > destructive.txt
    if [ -s destructive.txt ]; then
      echo "::error::refusing to apply a plan that deletes or replaces resources"
      cat destructive.txt
      exit 1
    fi

- name: terraform apply
  run: terraform -chdir="$TF_DIR" apply -input=false -no-color -lock-timeout=10m tfplan
```

plan をやり直さずに `tfplan` を適用するので、変更されるのはチェックを通った plan に載っているリソースだけです。その間に state が変わっていれば、Terraform は古くなった plan の適用を拒否します。

> **これおすすめ**
>
> **手書きの plan で jq の式を試す**
>
> `update`、`["delete","create"]`、`["delete"]` を含む plan で試すと、`delete/create a.rep` と `delete a.del` が出力され、update については何も出力されませんでした。

state バケットと 2 つの GitHub Actions 用ロールを作るブートストラップのルートは、共有モジュール `modules/bootstrap` にまとめました。テストのリソースを `modules/bootstrap` へ移すのに `moved` ブロックを 13 個書きました。`moved` ブロックは、リソースのアドレスが変わっただけで別物になったわけではないことを Terraform に伝えます。テストのブートストラップの plan は `0 to add, 0 to change, 0 to destroy` になり、本番のブートストラップでは 13 個のリソースを新しく作成しました。

## 本番への最初の apply は 2 つの OpenSearch ポリシーで止まった

**最初の実行では 45 個のリソースをすべて import し、更新の大半を適用したあと、OpenSearch Serverless の 2 つのセキュリティポリシーで失敗しました**。

```text
Error: updating OpenSearch Serverless Security Policy

  with module.data_layer.aws_opensearchserverless_security_policy.encryption,
  on ../../modules/data-layer/opensearch.tf line 10, in resource "aws_opensearchserverless_security_policy" "encryption":
  10: resource "aws_opensearchserverless_security_policy" "encryption" {

ID: <collection-name>
Cause: operation error OpenSearchServerless: UpdateSecurityPolicy, ,
ValidationException: No changes detected in policy or policy description"
```

コンソールは両方のポリシーに説明文（`description` フィールド）を書き込んでいて、モジュールは説明文を宣言していません。Terraform は、ポリシー本体はそのままで説明文だけを空にする更新を送り、OpenSearch Serverless の `UpdateSecurityPolicy` API はこれを何も変えないリクエストとして拒否しました。更新は削除ではないので、削除チェックは通っていました。

**削除されたものはなく、成功した分は適用されたまま残りました**。Terraform はリソース単位で適用します。ロール、セキュリティグループのルール、Glue テーブル、Lambda の更新は完了していて、コレクションに依存するリソースはまだ適用が始まっていませんでした。

*Figure — PartialApply: 1 回目の実行は 2 つのセキュリティポリシーで止まり、それより前はすべて適用済みでした。コンソールの説明文を無視するようにしたあと、2 回目の実行で残りを終えました。*

私は説明文を管理対象から外しました。両方のポリシーと、同じくコンソールが説明文を書いていたコレクションが対象です。

```hcl title="modules/data-layer/opensearch.tf" ins={7-9}
resource "aws_opensearchserverless_security_policy" "encryption" {
  name   = local.collection_name
  type   = "encryption"
  policy = jsonencode({ /* ルールと鍵の設定。省略 */ })

  # コンソールが説明文を書き込んでいる。空にする更新は UpdateSecurityPolicy API に拒否される。
  lifecycle {
    ignore_changes = [description]
  }
}
```

プルリクエストの本番の plan に残りの変更が表示され、2 回目の実行でそれを適用しました。

```text
Apply complete! Resources: 5 added, 3 changed, 0 destroyed.
```

2 回目の適用のあとに実行した plan は `No changes. Your infrastructure matches the configuration.` を出力しました。

## まとめ

本番とテストは同じデータ層モジュールを使うようになり、本番には私が手動で開始した実行からだけ適用します。本番に何かが触れる前に、読み取り専用の plan（import ブロック、ローカル state のオーバーライド、読み取り専用の認証情報）で、取り込みによって起きるはずだった 7 つの置き換えを確認できました。

コンソールで作ったアカウントでは、コンソールがリソースに独自の名前を付けているので、モジュールはその名前を入力として受け取るようにし、名前を変えないことにしました。ほかのリソースの名前から組み立てていた名前には固定の値を持たせたので、あるリソースの名前を変えても、別のリソースが置き換えられることはありません。

本番にはレビュアーを置かず、削除チェックで守っています。**保存した plan にリソースの削除が 1 つでも含まれていれば、適用されません**。

ただし削除チェックが見るのは削除だけなので、今回のセキュリティポリシーのように適用時に失敗する更新は止められません。そのため、コンソールが値を入れていて API が空にできないフィールド（説明文など）は `ignore_changes` に入れ、Terraform が更新しないようにしました。

## 参考リンク

- [Terraform：import ブロック（for_each を含む）](https://developer.hashicorp.com/terraform/language/import)
- [Terraform：オーバーライドファイルと、その中の backend ブロックが優先される仕組み](https://developer.hashicorp.com/terraform/language/files/override)
- [Terraform：lifecycle メタ引数と ignore_changes](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle)
- [Terraform の JSON 出力形式（置き換えを表す actions の値を含む）](https://developer.hashicorp.com/terraform/internals/json-format)
- [Terraform：モジュールのリファクタリングに使う moved ブロック](https://developer.hashicorp.com/terraform/language/modules/develop/refactoring)
- [GitHub Docs：デプロイと environment（deployment branch policy を含む）](https://docs.github.com/en/actions/reference/workflows-and-actions/deployments-and-environments)
- [OpenSearch Serverless API：UpdateSecurityPolicy](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_UpdateSecurityPolicy.html)
