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

目次
はじめに
私が関わっている AWS データ層のテストアカウントは、Terraform で構築しています。元になっているのは、本番を読み取り専用で採取した設定から書いたモジュールです。経緯は前回の記事で書きました。その記事では、同じモジュールを本番に使うときも「tfvars ファイルを 1 つ足すだけ」で済むと書いています。
一方で、本番は相変わらずコンソールから手作業で作り、手作業で変更していました。私は本番も同じモジュールで定義し、apply は自分で手動で開始する形にしたいと考えました。ところが、本番に対して最初に実行した読み取り専用の terraform plan には、7 つのリソースの削除が含まれていました。コンソールが付けた名前と、モジュールの名前が違っていたためです。
今では本番は既存のリソースを import し、コンソールが付けた名前をそのまま残しています。apply は私が手動で開始するワークフローからだけ実行し、そのワークフローは削除を含む plan を拒否します。リポジトリが両方のアカウントを定義するようになり、main にマージしても本番は変わりません。
1 つのモジュール、2 つのルート、2 つの適用経路
両方のアカウントは同じデータ層モジュールを使い、それぞれ専用のルートディレクトリと state を持ちます。state は、Terraform が管理しているリソースを記録するファイルです。ルートごとに 1 つずつあるので、2 つのアカウントのリソースが混ざることはありません。ルートとは terraform plan を実行するディレクトリのことで、次の 3 つを置きます。
- バックエンド:state の保存先を指定します。たとえば S3 バケットです。
- プロバイダ:Terraform が操作する AWS アカウントを設定します。ルートごとに 1 つのアカウントだけを指します。
moduleブロック:データ層モジュールを呼び出し、そのアカウント用の値を渡します。
modules/ bootstrap/ state バケットと GitHub Actions のロール。両アカウントで共有 data-layer/ S3、Glue、OpenSearch Serverless、Bedrock ナレッジベース、Lambda、AgentCorebootstrap/ test/ prod/envs/ test/ main.tf prod/ main.tf, imports.tf本番のルートがテストのルートと違うのは次の 2 か所です。
imports.tf:モジュールのリソースを、本番に実在するリソースに対応づけます。main.tf:それらのリソースにコンソールが付けた名前を、モジュールに渡します。
プルリクエストごとに、両方のアカウントの plan が実行されます。テストアカウントにはプルリクエストが main にマージされたときに適用し、本番には私がワークフローを手動で開始したときにだけ適用します。plan にリソースの削除が含まれていれば、本番の実行は何も適用する前に失敗します。
そのため、本番でコンソールから行った変更は、次のプルリクエストの本番の plan にコードとの差分として現れます。次に本番へ適用すると、その変更はコードどおりに戻ります。ただし、戻すためにリソースの削除が必要な場合は、削除チェックが実行を止めます。
読み取り専用の plan で本番のリソースの取り込みをリハーサルする
import ブロックとローカルバックエンドを組み合わせると、本番に何も書き込まずに、本番を取り込んだら何が起きるかを terraform plan で確かめられます。import ブロックには、既存のリソースと、それを管理するモジュール内のアドレスを書きます。plan は稼働中のリソースを読んで設定と比べ、実際に import する前に差分を表示します。
私は List、Get、Describe の呼び出しで ID を集め、リソースごとに import ブロックを 1 つ書きました。同じ形が続くものは for_each でまとめています。
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 バケットも必要ありません。
terraform { backend "local" { path = "/tmp/prod-rehearsal.tfstate" }}本番の認証情報で実行すると、plan はすべてのリソースを読み取り、アカウントには何も変更を加えません。
入力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.本番の state バケットができてからオーバーライドファイルを削除すると、同じコマンドが S3 バックエンドに対して動きました。
plan で 7 つのリソースが置き換えになった理由
置き換えになる 7 つのリソースのうち、6 つは名前が違うためでした。私がコンソールでこれらのリソースを作ったときにコンソールが名前を自動で付けていて、モジュールは独自の規則で別の名前を組み立てます。残りの 1 つはインラインポリシーで、所属するロールが置き換えになるので一緒に置き換えられます。
Terraform はナレッジベースのデータソースや IAM ロールの名前をその場で変更できません。名前が違えば、新しいリソースを作ってから古いリソースを削除するしかありません。
# 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 では置き換えになりました。
そこで各データソースの名前は、ナレッジベースの名前から組み立てるのをやめて、専用の固定の名前にしました。
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 つ追加しました。変数が空のときは、モジュール独自の命名規則で名前を付けます。テストは何も渡さないのでこれまでの名前のまま、本番はコンソールの名前を渡します。
variable "existing_names" { type = object({ data_sources = optional(map(string), {}) kb_roles = optional(map(string), {}) reviewer_role = optional(string) gateway_role = optional(string) }) default = {}}resource "aws_iam_role" "kb" { name = lookup(var.existing_names.kb_roles, each.key, "${local.prefix}-kb-${each.key}") # …}残りの 2 つの問題、aws-apn-id タグの削除とサービスリンクロールの作成は、どちらも 1 行で直せました。ナレッジベースに ignore_changes = [tags["aws-apn-id"]] を付けるとそのタグには触れなくなり、サービスリンクロールに import ブロックを書くと、作成が取り込みに変わります。
入力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 種類です。
- 取り込んだロールに付ける 3 つのインラインポリシー
- 同じロールへの 2 つのポリシーのアタッチ
- OpenSearch のデータアクセスポリシー 1 つ
- インデックスの存在を確かめる
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 にしたので、テストの経路は変わりません。
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
prod environment は main からしかデプロイできません。前回の記事で 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を設定したリソースで使われます。
ワークフローでのチェックは次のとおりです。
- 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 tfplanplan をやり直さずに tfplan を適用するので、変更されるのはチェックを通った plan に載っているリソースだけです。その間に state が変わっていれば、Terraform は古くなった plan の適用を拒否します。
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 つのセキュリティポリシーで失敗しました。
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 の更新は完了していて、コレクションに依存するリソースはまだ適用が始まっていませんでした。
私は説明文を管理対象から外しました。両方のポリシーと、同じくコンソールが説明文を書いていたコレクションが対象です。
resource "aws_opensearchserverless_security_policy" "encryption" { name = local.collection_name type = "encryption" policy = jsonencode({ /* ルールと鍵の設定。省略 */ })
# コンソールが説明文を書き込んでいる。空にする更新は UpdateSecurityPolicy API に拒否される。 lifecycle { ignore_changes = [description] }}プルリクエストの本番の plan に残りの変更が表示され、2 回目の実行でそれを適用しました。
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 を含む)
- Terraform:オーバーライドファイルと、その中の backend ブロックが優先される仕組み
- Terraform:lifecycle メタ引数と ignore_changes
- Terraform の JSON 出力形式(置き換えを表す actions の値を含む)
- Terraform:モジュールのリファクタリングに使う moved ブロック
- GitHub Docs:デプロイと environment(deployment branch policy を含む)
- OpenSearch Serverless API:UpdateSecurityPolicy



