Terraform

Terraform で非同期プローバーインフラを宣言的に管理する構成、ワークスペース運用、Amplify 管理領域との連携点を扱う章です。

Terraform は、証明生成パイプラインに関わる AWS リソース（ECS、Step Functions、SQS、S3、ECR、CodeBuild、VPC、Lambda、IAM、CloudWatch、CloudTrail、SSM Parameter）を宣言的に管理します。Amplify Gen 2 管理領域との連携点は本章末の Amplify との連携ポイント を参照してください。

ディレクトリ構成

Terraform の構成ファイルは terraform/ ディレクトリに配置され、機能別に分割されています。

環境分離

ワークスペース戦略

develop と main の 2 環境を、Terraform ワークスペースと git 管理外の *.local.tfvars ファイルの組み合わせで管理します。

flowchart LR
  subgraph "Terraform State"
    S3["S3 バケット<br/>terraform-state"]
    S3 --> DEV["develop<br/>workspace"]
    S3 --> MAIN["main<br/>workspace"]
  end

  subgraph "local tfvars"
    DEVF["develop.local.tfvars"]
    MAINF["main.local.tfvars"]
  end

  DEVF --> DEV
  MAINF --> MAIN

environment 変数はバリデーションにより develop または main のみが許可されます。環境ごとの差分は locals で定義された設定マップにより解決されます。

ワークスペースの確認

環境の取り違えを防ぐため、操作前にワークスペースの確認が推奨されます。

ステート管理

S3 バックエンド

Terraform ステートは S3 バケットに保存され、use_lockfile = true による S3 lockfile でステートの同時変更を防止します。tracked の backend.tf は partial backend として backend "s3" {} だけを持ち、bucket や region は backend.local.hcl から terraform init に渡します。

named workspace ごとに state path と lockfile path は分かれますが、同じ backend bucket と root module を共有し、bootstrap・共有リソース・環境別 prover runtime が同居しています。長期運用では state と lifecycle の粒度に課題が残ります。経緯と改善候補は 設計ふりかえり § 7 を参照してください。

認証方式

Terraform の実行は STS AssumeRole を前提とし、現行の標準フローでは terraform-admin assumed role で実行します。aws_account_id は AWS provider の allowed_account_ids に渡され、principal_guard.tf は実行 principal が assumed-role/terraform-admin/* に一致しない場合に fail-fast します。

flowchart LR
  EXEC["実行環境<br/>(ローカル/CI)"] --> STS["AWS STS<br/>AssumeRole"]
  STS --> ROLE["Terraform 実行ロール<br/>IAM ロール"]
  ROLE --> TF["Terraform 実行"]

plan / apply は scripts/terraform/terraform-guarded.sh 経由で実行します。この wrapper は AWS caller、account ID、Terraform workspace、*.local.tfvars の environment を確認してから Terraform を起動します。

主要な入力変数

Terraform の実行に必要な変数と、そのバリデーションルールの概要です。

必須変数

*_arn / *_location の各変数は、sanitized placeholder を弾くバリデーションが入っているため、実値の注入が前提です。現行の CodeBuild source は GITHUB タイプ（location 指定）で構成されています。

オプション変数

tracked の develop.tfvars / main.tfvars は値の形を示す placeholder です。実運用では .env.local または shell 環境から pnpm terraform:backend / pnpm terraform:tfvars:develop / pnpm terraform:tfvars:main で backend.local.hcl と *.local.tfvars を生成します。

出力値

Terraform の出力値は、Amplify 環境変数や運用ツールから参照されます。

IAM 設計

最小権限の原則に基づき、各コンポーネントに専用の IAM ロールが割り当てられています。

flowchart TD
  subgraph "信頼されるサービス (Service Principal)"
    ECSSVC["ecs-tasks.amazonaws.com"]
    STATESVC["states.${aws_region}.amazonaws.com"]
    CBSVC["codebuild.amazonaws.com"]
    LAMSVC["lambda.amazonaws.com"]
  end

  subgraph "IAM ロール"
    ETE["ecs_task_execution"]
    ET["ecs_task"]
    SFN["step_functions"]
    CB["codebuild"]
    CBT["codebuild_risc0_toolchain"]
    CIS["check_image_signature"]
    CTL["cloudtrail_logs<br/>(main only)"]
  end

  ECSSVC --> ETE
  ECSSVC --> ET
  STATESVC --> SFN
  CBSVC --> CB
  CBSVC --> CBT
  LAMSVC --> CIS
  CTSVC["cloudtrail.amazonaws.com"] --> CTL

スコープの制限

• ECS タスクロールの S3 権限は var.s3_proof_prefix 配下に制限（既定: sessions/*）
• Step Functions ロールの ECS 権限は特定クラスター ARN に制限
• Step Functions ロールの iam:PassRole は ECS 関連ロールのみに制限
• Step Functions ロールの EventBridge 権限は ecs:runTask.sync の managed rule 操作用
• CodeBuild ロールの metadata 書き込みは prover image metadata バケット配下と現行 metadata SSM Parameter に制限

Amplify との連携ポイント

Terraform と Amplify は別系統で管理され、以下のポイントで手動同期を含む連携が残っています。

flowchart TB
  subgraph TF["Terraform"]
    SFN_ARN["Step Functions ARN"]
    SQS_ARN["SQS キュー ARN"]
    SQS_URL["SQS キュー URL"]
    S3_NAME["S3 バケット名"]
    CB_INPUT["入力変数<br/>finalize_callback_lambda_arn"]
  end

  subgraph AMP["Amplify"]
    ENV["環境変数"]
    CB_ARN["finalize-callback-runner<br/>Lambda ARN"]
  end

  SFN_ARN --> ENV
  SQS_ARN --> ENV
  SQS_URL --> ENV
  S3_NAME --> ENV
  CB_ARN -. "IaC input" .-> CB_INPUT

この双方向の参照により、Amplify が管理する Lambda を Terraform が管理する Step Functions から呼び出します。Terraform 出力 → Amplify 環境変数は手動同期のため、出力を変更した場合は Amplify 側の app-level / branch override の実効値も合わせて確認してください。

バージョン制約