リモートバックエンドのコード化
リモートバックエンドの準備ができたので、environments/test/ディレクトリにバックエンド設定のコードを作成し、Terraformを初期化します。その後、マネジメントコンソールで手動作成したS3バケットとDynamoDBテーブルをimportブロックでTerraformの管理下に取り込みます。
1. コードの記載
environments/test/ディレクトリにリモートバックエンドの設定コードを記述していきます。ここでは、リモートバックエンドのbackend設定と、AWSプロバイダの基本設定を記述します。変数やモジュールの呼び出しは、リモートバックエンドのコード化が完了した後で追加していきます。
1.1 backend.tf
environments/test/backend.tfに以下の内容を記述します。bucketの値は実際のS3バケット名に置き換えてください。
terraform {
backend "s3" {
bucket = "noteapp-tfstate-123456789012"
key = "test/terraform.tfstate"
region = "ap-northeast-1"
dynamodb_table = "noteapp-tfstate-lock"
encrypt = true
}
}
| 💡 ポイント |
|---|
keyにtest/terraform.tfstateと指定することで、環境ごとにtfstateファイルを分けて管理できます。将来prod環境を追加する場合は、prod/terraform.tfstateのように別のキーを使用します。 |
コードを解説します。
backend "s3"
terraform {
backend "s3" {
bucket = "noteapp-tfstate-123456789012"
key = "test/terraform.tfstate"
region = "ap-northeast-1"
dynamodb_table = "noteapp-tfstate-lock"
encrypt = true
}
}
tfstateファイルをS3に保存するためのバックエンド設定です。
bucketは、tfstateファイルの保存先となるS3バケット名を指定する設定です。リモートバックエンドで作成したバケット名を指定します。
keyは、S3バケット内でのtfstateファイルのパスを指定する設定です。test/terraform.tfstateとすることで、環境ごとにtfstateを分離できます。
dynamodb_tableは、同時実行防止のためのロックテーブルを指定する設定です。複数人が同時にterraform applyを実行した場合の競合を防ぎます。
encryptは、tfstateファイルをS3上で暗号化するかどうかを制御する設定です。trueにすることで、機密情報を含むtfstateが暗号化されて保存されます。
1.2 main.tf
environments/test/main.tfに以下の内容を記述します。この時点ではAWSプロバイダの基本設定のみを記述します。変数やモジュールの呼び出しは、リモートバックエンドのコード化が完了した後で順番に追加していきます。
terraform {
required_version = ">= 1.0.0"
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 6.0"
}
}
}
provider "aws" {
region = "ap-northeast-1"
}
コードを解説します。
terraform / required_providers
terraform {
required_version = ">= 1.0.0"
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 6.0"
}
}
}
Terraform 1.0以上の安定版を使用し、AWSプロバイダはメジャーバージョン6系(~> 6.0)を指定しています。
プロバイダ設定
provider "aws" {
region = "ap-northeast-1"
}
メインのプロバイダは東京リージョン(ap-northeast-1)を使用します。
2. Terraformの初期化とリモートバックエンドの確認
ターミナルでenvironments/test/ディレクトリに移動し、Terraformを初期化します。この初期化により、backend.tfで設定したS3バケットとDynamoDBテーブルにtfstateが保存されるようになります。
アプリケーションの準備でapp/フォルダに移動しているため、まずプロジェクトルートに戻ります。
cd ..
environments/test/ディレクトリに移動します。
cd environments/test
以下のコマンドで、Terraform がインストールされていることを確認します。
terraform --version
以下のように Terraform のバージョンが表示されれば、インストールは確認できています。
Terraform vX.X.X
on darwin_arm64
バージョンが表示されない場合は、Terraformのインストール を先に実施してください。
インストールが確認できたら、Terraformを初期化します。
terraform init
以下のような出力が表示されれば成功です。Successfully configured the backend "s3"!というメッセージが表示され、先ほどマネジメントコンソールで作成したS3バケットがリモートバックエンドとして正しく設定されたことを確認してください。
Initializing the backend...
Successfully configured the backend "s3"! Terraform will automatically
use this backend unless the backend configuration changes.
Initializing provider plugins...
- Finding hashicorp/aws versions matching "~> 6.0"...
- Installing hashicorp/aws v5.x.x...
- Installed hashicorp/aws v5.x.x (signed by HashiCorp)
Terraform has been successfully initialized!
リモートバックエンド(S3)が正しく設定されていることを確認してください。
| ⚠️ 「Error configuring S3 Backend」エラーが出る場合 |
|---|
backend.tfのbucket名が実際に作成したS3バケット名と一致しているか確認してください。また、AWS CLIの認証情報が正しく設定されていることも確認してください。 |
3. remoteモジュールのインポート
リモートバックエンドが正しく設定されたことを確認できたので、次にマネジメントコンソールで手動作成したS3バケットとDynamoDBテーブルをTerraformの管理下に取り込みます。ここでは、importブロックのコード生成機能(-generate-config-out)を使って、既存リソースからTerraformコードを自動生成します。
| 📝 これから行う作業の全体像 |
|---|
| このセクションでは、以下の流れで既存リソースをTerraformの管理下に取り込みます。少し複雑なので、最初に全体像を把握しておくと迷いません。 1. importブロックをルートモジュールに記述(まだ module.remote. 付きにしない)2. terraform plan -generate-config-out=generated.tf で environments/test/ に generated.tf を自動生成3. 生成された generated.tf の不要な属性を削除4. generated.tf を modules/remote/ に移動5. importブロックの to を module.remote.aws_xxx に書き換え6. terraform plan と terraform apply で取り込みを反映この2段階方式を採っている理由は、 -generate-config-out オプションが ルートモジュールのリソースにのみ対応 しているためです。モジュール内のリソースには直接コードを生成できないため、一度ルートで生成してからモジュールに移動する という流れが必要になります。 |
3.1 importブロックの追加
environments/test/main.tfのプロバイダ設定の下に、remoteモジュールの呼び出しとimportブロックを追記します。importブロックはルートモジュール(environments/test/)に記述する必要があるため、モジュール呼び出しと一緒にmain.tfに記載します。<アカウントID>の部分はご自身のAWSアカウントIDに置き換えてください。
まず、コード自動生成のために、importブロックのtoをルートモジュールのアドレス(module.remote.なし)で記述します。<アカウントID>の部分はご自身のAWSアカウントIDに置き換えてください。
# リモートバックエンドモジュール
module "remote" {
source = "../../modules/remote"
}
# コード自動生成用(生成後にmodule.remote.付きに書き換える)
import {
to = aws_s3_bucket.tfstate
id = "noteapp-tfstate-<アカウントID>"
}
import {
to = aws_s3_bucket_versioning.tfstate
id = "noteapp-tfstate-<アカウントID>"
}
import {
to = aws_dynamodb_table.tfstate_lock
id = "noteapp-tfstate-lock"
}
| 📝 importブロックについて |
|---|
importブロックは、Terraform 1.5で導入された機能で、既存のAWSリソースをTerraformの管理下に宣言的に取り込めます。従来のterraform importコマンドと異なり、コードとして管理できるため、チームメンバーが同じ手順を再現しやすくなります。toにTerraformリソースのアドレスを、idにAWSリソースの識別子を指定します。 |
3.2 Terraformの再初期化
新しいモジュールを追加したため、Terraformを再初期化してモジュールを読み込む必要があります。
terraform init
以下のように、remoteモジュールの初期化が行われれば成功です。
Initializing modules...
- remote in ../../modules/remote
Initializing the backend...
Initializing provider plugins...
Terraform has been successfully initialized!
3.3 コードの自動生成
Terraformの初期化が完了したら、importブロックの-generate-config-outオプションを使って、既存のAWSリソースからTerraformコードを自動生成します。-generate-config-outはルートモジュールのリソースにのみ対応しているため、先ほどimportブロックのtoをmodule.remote.なしで記述しました。
terraform plan -generate-config-out=generated.tf
以下のような実行結果が表示されます。エラーが表示される場合がありますが、generated.tfファイル自体は生成されているため問題ありません。
aws_s3_bucket.tfstate: Preparing import... [id=noteapp-tfstate-123456789012]
aws_s3_bucket_versioning.tfstate: Preparing import... [id=noteapp-tfstate-123456789012]
aws_dynamodb_table.tfstate_lock: Preparing import... [id=noteapp-tfstate-lock]
Plan: 3 to import, 0 to add, 0 to change, 0 to destroy.
| 💡 ポイント |
|---|
-generate-config-outは、importブロックで指定したリソースの現在の状態をAWSから読み取り、対応するresourceブロックを自動生成する機能です。手動でコードを書く必要がなく、AWSの実態と完全に一致したコードが得られます。ただし、この機能は実験的(experimental)であり、生成されたコードに手動修正が必要な場合があります。 |
3.4 生成されたコードの確認と移動
生成されたenvironments/test/generated.tfを開いて内容を確認しましょう。S3バケット、バージョニング設定、DynamoDBテーブルの3つのリソースが定義されているはずです。
-generate-config-out は実験的(experimental)機能のため、そのままではapplyできない値が含まれることがあります。具体的には、DynamoDBテーブル(aws_dynamodb_table)のpoint_in_time_recoveryブロック内に recovery_period_in_days = 0 という行がある場合は、その行を削除してください。
point_in_time_recovery {
recovery_period_in_days = 0 # ← この行を削除
}
削除する理由は、recovery_period_in_days は有効値(1以上)を求める属性であり、自動生成時に 0 が入ってしまうと後の terraform apply で Value must be at least 1 のようなバリデーションエラーが発生するためです。属性自体を省略すると、AWSのデフォルト値が使われます。
また、値がnullになっている属性も同様にそのままだとエラーや不要な差分の原因になるため、削除して構いません。
修正が完了したら、generated.tfをmodules/remote/ディレクトリに移動します。
Windowsの場合:
move generated.tf ..\..\modules\remote\generated.tf
macOSの場合:
mv generated.tf ../../modules/remote/generated.tf
移動後、modules/remote/ディレクトリにgenerated.tfが存在し、environments/test/ディレクトリからgenerated.tfがなくなっていれば成功です。
3.5 importブロックの書き換え
generated.tfをモジュール内に移動したので、environments/test/main.tfのimportブロックのtoをmodule.remote.付きのアドレスに書き換えます。
# マネジメントコンソールで手動作成したリソースをTerraformに取り込む
import {
to = module.remote.aws_s3_bucket.tfstate
id = "noteapp-tfstate-<アカウントID>"
}
import {
to = module.remote.aws_s3_bucket_versioning.tfstate
id = "noteapp-tfstate-<アカウントID>"
}
import {
to = module.remote.aws_dynamodb_table.tfstate_lock
id = "noteapp-tfstate-lock"
}
| 📝 なぜ書き換えが必要なのか |
|---|
-generate-config-outはルートモジュールのリソースにのみ対応しているため、コード生成時はmodule.remote.なしで記述しました。生成されたコードをモジュールに移動した後は、importブロックのtoをモジュール内のアドレス(module.remote.付き)に書き換えることで、正しくインポートされます。 |
3.6 差分の確認
コードが自動生成されましたが、AWSへ反映する前にterraform planで差分を確認し、意図しない変更がないことを確かめます。
terraform plan
以下のような実行結果が表示されます。
module.remote.aws_s3_bucket.tfstate: Preparing import... [id=noteapp-tfstate-123456789012]
module.remote.aws_s3_bucket_versioning.tfstate: Preparing import... [id=noteapp-tfstate-123456789012]
module.remote.aws_dynamodb_table.tfstate_lock: Preparing import... [id=noteapp-tfstate-lock]
Plan: 3 to import, 0 to add, 0 to change, 0 to destroy.
3つのリソースがインポート対象として表示され、新規作成や変更が0件であることを確認してください。自動生成されたコードはAWSの実態と一致しているため、差分は発生しません。
3.7 AWSへの反映
terraform planで差分に問題がないことを確認できたので、terraform applyでAWSに反映します。
terraform apply
確認プロンプトが表示されたら、yesと入力して実行します。以下のように、3件のリソースがインポートされたことを確認します。
Apply complete! Resources: 3 imported, 0 added, 0 changed, 0 destroyed.
これで、マネジメントコンソールで作成したS3バケットとDynamoDBテーブルがTerraformの管理下に置かれました。以降、これらのリソースの変更や削除もTerraformで管理できます。
| 💡 ポイント |
|---|
importが完了したら、environments/test/main.tfのimportブロック3つは削除して構いません。importブロックは取り込み時に一度だけ使用するもので、取り込み完了後は不要です。残しておいても害はありませんが、コードをすっきりさせるために削除するのが一般的です。 |
これで、リモートバックエンドのコード化が完了しました。マネジメントコンソールで手動作成したS3バケットとDynamoDBテーブルがTerraformの管理下に置かれ、モジュールを追加するたびにterraform planで差分を確認し、terraform applyで反映できる状態になりました。