リモートバックエンドのコード化

リモートバックエンドの準備ができたので、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で反映できる状態になりました。