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

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

白地に、紫の平行四辺形4つでTの形を作るTerraformのマークと、ほぼ黒のTerraformロゴタイプ
目次

はじめに

私が関わっている AWS データ層のテストアカウントは、Terraform で構築しています。元になっているのは、本番を読み取り専用で採取した設定から書いたモジュールです。経緯は前回の記事で書きました。その記事では、同じモジュールを本番に使うときも「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 ブロック:データ層モジュールを呼び出し、そのアカウント用の値を渡します。
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 にコードとの差分として現れます。次に本番へ適用すると、その変更はコードどおりに戻ります。ただし、戻すためにリソースの削除が必要な場合は、削除チェックが実行を止めます。

PR は両アカウントを plan し、マージはテストに適用し、本番は削除チェックを通った手動実行からだけ適用する3 本のレーン。任意のブランチからのプルリクエストは、テストと本番の両アカウントに terraform plan を実行して結果をコメントし、何も適用しない。main へのマージは main からのみデプロイする test environment で走り、テストアカウントに自動で適用する。本番は target を prod にして手動で起動した実行からだけ適用する。main からのみデプロイする prod environment で plan を tfplan に保存し、削除されるリソースが 1 つでもあれば削除チェックが実行を失敗させ、そうでなければ保存した plan を本番アカウントに適用する。プルリクエスト任意のブランチテストと本番の terraform planPR にコメントするだけで適用しないmain へのマージ自動environment: testmain からのみデプロイterraform applyテストアカウント手動で実行target: prodenvironment: prodmain からのみデプロイplan -out=tfplan削除チェックapply tfplan本番アカウント削除があれば失敗
プルリクエストごとに両方のアカウントを plan します。マージするとテストに適用されます。本番には、main から手動で開始した実行で、保存した plan が削除チェックを通ったときにだけ適用します。

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

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

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

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 バケットも必要ありません。

terraform/envs/prod/zz_local_override.tf
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.
import ブロック、ローカル state のオーバーライドファイル、本番の認証情報で、本番を読むだけの plan を実行する3 つの入力が terraform plan に渡る。既存リソースごとに import ブロックを書いた imports.tf、state をローカルディスクに置く zz_local_override.tf、読み取りにだけ使う本番の認証情報。plan は List・Get・Describe の呼び出しで本番アカウントを読み、何も書き込まない。出力は実際に apply したときの内容で、44 件の import、17 件の追加、23 件の変更、7 件の削除。imports.tf既存リソースごとに import ブロックzz_local_override.tfstate はローカルディスク本番の認証情報読み取りにだけ使うterraform plan-lock=false本番アカウントList / Get / Describe何も書き込まない実際に apply したときの内容Plan: 44 to import, 17 to add,23 to change, 7 to destroy.
import ブロックが既存のリソースを指定し、オーバーライドファイルが state をローカルに留め、plan は本番を読むだけです。結果として、実際に apply したら何が起きるかの一覧が得られます。

本番の 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 では置き換えになりました。

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

modules/data-layer/bedrock_kb.tf
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 つ追加しました。変数が空のときは、モジュール独自の命名規則で名前を付けます。テストは何も渡さないのでこれまでの名前のまま、本番はコンソールの名前を渡します。

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 = {}
}
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}")
# …
}
existing_names でコンソールの名前を保つと、ロールは置き換えられずに import されるコンソールが AmazonBedrockExecutionRoleForKnowledgeBase_xxxxx と名付けた本番の IAM ロール。左側では、モジュールの命名規則が実在する名前と異なる app-kb-catalog を作るので、plan は置き換えになり、新しいロールを作って古いロールを削除する。右側では、existing_names がコンソールの名前をそのまま渡すので、import でロールを取り込み、plan はその場での更新だけになる。コンソールが作った本番の IAM ロールAmazonBedrockExecutionRoleForKnowledgeBase_xxxxx実在するロールの名前と比較モジュールの命名規則app-kb-catalog名前が違う:置き換えになる新しいロールを作り、古いロールを削除existing_namesAmazonBedrockExecutionRoleForKnowledgeBase_xxxxx名前が同じ:import されるそのまま取り込み、その場で更新
モジュール独自の名前では置き換えになります。existing_names でコンソールの名前を渡すと、import でリソースをそのまま取り込めます。

残りの 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 種類です。

  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 にしたので、テストの経路は変わりません。

.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

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

main からワークフローを手動で実行し、target に 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 を設定したリソースで使われます。

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

.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 の適用を拒否します。

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 の更新は完了していて、コレクションに依存するリソースはまだ適用が始まっていませんでした。

本番への最初の apply はセキュリティポリシーで止まり、それより前は適用済み。2 回目で残りを終えた4 つの段階にわたる 2 回の apply のタイムライン。段階は import、ロール・セキュリティグループのルール・S3・Glue・Lambda、OpenSearch のセキュリティポリシー、コレクション・ナレッジベース・インデックスの順。1 回目は 45 件を import し、2 つ目の段階を更新したあと、セキュリティポリシーで説明文に関する ValidationException で失敗し、最後の段階には着手しなかった。説明文に ignore_changes を加えた 2 回目では、最初の 2 段階はすでに state にあって変更がなく、セキュリティポリシーは更新せず、最後の段階を追加 5・変更 3・削除 0 で終えた。importロール・SG ルール・Glue・Lambdaセキュリティポリシーコレクション・KB・インデックス1 回目45 件 import更新済みValidationException説明文未着手2 回目state にある変更なし説明文を無視更新しない追加 5・変更 3削除 0ignore_changes = [description]
1 回目の実行は 2 つのセキュリティポリシーで止まり、それより前はすべて適用済みでした。コンソールの説明文を無視するようにしたあと、2 回目の実行で残りを終えました。

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

modules/data-layer/opensearch.tf
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 が更新しないようにしました。

参考リンク

この記事をシェア