🐷

"実務でつまずいたところ全部まとめました：Terraform×AWSデータ基盤ハンドブック（前編）"

に公開
AWS
Terraform
データ基盤
tech

1. はじめに

外資コンサルのデータチームにジョインしました。直近のプロジェクトで弱いところを補うテーマで実装してみることになり、最初のタスクが 「RSS → S3 → Glue/Athena基盤をTerraformで立ち上げること」でした。

やってみたら、予想以上にハマりどころだらけ（笑）。
そこで、同じような基盤をつくる人向けに、実務でつまずいたポイントを全部まとめて記事化しました。

今回の記事は 前編（設計・Terraform適用編） です。
後編では 監視・運用・権限管理のベストプラクティス を掘り下げていく予定です。

2. アーキテクチャ概要（今回の採用技術）

今回つくった基盤の全体像はこんなイメージです 👇

[RSS] --fetch--> [Lambda]
|
v (CSV, SSE-KMS)
s3://raw/rss/dt=YYYY-MM-DD/source=<name>/part-*.csv
|
v
[Glue Catalog: rss table]
|
v
[Athena WorkGroup]
- s3://athena-results (SSE-KMS)
- 結果保存先と暗号化を強制

ストレージ（S3）

  • バケットは raw と athena-results の2種類を用意
  • Public Access Block 有効化
  • Versioning 有効化
  • デフォルト暗号化は SSE-KMS

暗号鍵（KMS）

  • alias 運用で管理
  • Key Policy に 運用ロール と Lambda実行ロール を明示的に許可

メタデータ（Glue Catalog）

  • Database + Table を定義
  • rss テーブルは Partition Projection を採用
    • パーティションキー: dt（日付）, source（取得元）

クエリエンジン（Athena）

  • WorkGroup を固定
  • クエリ結果は 専用S3 + SSE-KMS で保存

取得処理（Lambda）

  • 言語は Python
  • 処理フロー: RSS → 正規化 → CSV → S3
  • 保存先: raw/rss/dt=YYYY-MM-DD/source=<name>/part-*.csv
  • 環境変数 KMS_KEY_ARN で暗号鍵を指定

スケジュール（EventBridge）

  • ルール: rate(15 minutes)
  • Lambda Invoke の許可は 関数側のリソースベースポリシーで付与

監視（CloudWatch Logs）

  • Lambda の実行ログを CloudWatch Logs に送信
  • Athena結果S3の暗号化状態も合わせてチェック

3. Terraform設計パターン

3.1 ディレクトリ構成

Terraform のリポジトリ構成はこんな感じにしました。

new-project-terraform-aws/
├─ env/
│ ├─ dev/
│ │ ├─ backend.tf
│ │ ├─ main.tf
│ │ ├─ variables.tf
│ │ └─ terraform.tfvars.example
│ └─ bootstrap/ # state 用 S3 や DynamoDB ロック用
└─ modules/
├─ security-kms/
├─ storage-s3/
├─ analytics-athena-glue/
├─ iam-lambda/
├─ lambda-function/
└─ scheduler-eventbridge/

  • env/dev : 開発環境用
  • env/bootstrap : state 管理用（S3 バケットや DynamoDB ロックテーブル）
  • modules : 論理コンポーネントごとに分割して再利用できるようにした。

3.2 Backend（state 管理）

state は S3 + DynamoDB Lock を採用しました。

terraform {
backend "s3" {
bucket = "<state-bucket>"
key = "env/<env>/terraform.tfstate"
region = "ap-northeast-1"
dynamodb_table = "<lock-table>"
encrypt = true
}
}

  • 初回注意点：S3 バケットと DynamoDB テーブルが存在しないと terraform init が失敗します
  • そのため bootstrap 環境を用意し、まずはそこから state 管理用のリソースを作るのがおすすめです
  • 既存の S3 がある場合は terraform import で取り込みます。

3.3 変数・出力・タグの扱い

  • 共通変数: project, env, region
  • 論理名: kms_alias, raw_bucket_name, athena_results_bucket_name, glue_database_name
  • すべてのモジュールに Project, Env タグを付与して課金や運用を追跡しやすくします。

3.4 KMSモジュール（security-kms）

  • Key Policy に root と Lambda実行ロール を明示的に許可
  • Grant を多用せず、ポリシーで完結できる範囲はポリシーで対応
  • 出力値: key_id, key_arn, alias_arn

3.5 S3モジュール（storage-s3）

  • raw と athena-results の2つのバケットを作成
  • SSE-KMS を強制
  • Public Access Block 有効化
  • Versioning 有効化

3.6 Glue / Athenaモジュール（analytics-athena-glue）

  • Glue Database と rss テーブルを作成
  • Athena WorkGroup を専用に作成し、結果出力先と暗号化を固定化

rssテーブル定義のイメージ：

  • パーティションキー: dt (string), source (string)
  • パラメータ（Partition Projection）
    • projection.enabled = true
    • projection.dt.type = date
    • projection.source.type = injected
    • storage.location.template = s3://<raw>/raw/rss/dt=$${dt}/source=$${source}/
  • カラム: title, link, published_at, source_name

3.7 IAM（Lambda実行ロール）

  • Logs: logs:CreateLogGroup, logs:CreateLogStream, logs:PutLogEvents
  • S3:
    • ListBucket は prefix 条件つき（raw/rss/*）
    • PutObject/GetObject はオブジェクトキーに限定
  • KMS: 対象キーのみに限定して Encrypt/Decrypt/GenerateDataKey*/DescribeKey

💡 よくある失敗

  • ListBucket に prefix 条件を付け忘れて過剰権限になる
  • Resource をバケット直下に指定してしまい、オブジェクトキーが限定されない

3.8 Lambdaデプロイ（lambda-function）

  • 組織によっては lambda:CreateFunction が SCP や Permissions boundary で禁止されている
  • 初回はコンソールで手動作成し、以降は UpdateFunctionCode 運用
  • Terraformでは use_existing_lambda フラグを用意して既存関数を参照できるようにした

3.9 EventBridge（scheduler-eventbridge）

  • aws_cloudwatch_event_rule + aws_cloudwatch_event_target を利用
  • Lambda Invoke の許可は 関数のリソースベースポリシーで制御
  • Terraformでは add_lambda_permission フラグで付与の有無を切り替え可能

4. デプロイ手順（dev想定）

Terraform で dev 環境を立ち上げるまでの手順を、前提 → 認証 → 適用 → 検証 の順でまとめます。

4.1 前提（ディレクトリ & tfvars）

  • この記事の前提ディレクトリ構成：
    new-project-terraform-aws/
    ├─ env/
    │ ├─ dev/
    │ │ ├─ backend.tf
    │ │ ├─ main.tf
    │ │ ├─ variables.tf
    │ │ └─ terraform.tfvars # ★ 実値を入れる
    │ └─ bootstrap/
    └─ modules/
    ├─ ...

  • env/dev/terraform.tfvars に一意な名前等を設定します（例）：

project = "new-project"
env = "dev"
region = "ap-northeast-1"

raw_bucket_name = "new-project-dev-raw-123456789013"
athena_results_bucket_name = "new-project-dev-athena-results-123456789013"
glue_database_name = "new_project_dev"
kms_alias = "alias/new-project-dev"

use_existing_lambda = true
lambda_function_arn = "arn:aws:lambda:ap-northeast-1:123456789013:function:new-project-dev-rss-ingestion"
add_lambda_permission = false

4.2 認証（AWS SSO / プロファイル）

  • 例：terraform-bootstrap という SSO プロファイルを使う前提です。

ログイン

AWS_PROFILE=terraform-bootstrap aws sso login

認証確認

AWS_PROFILE=terraform-bootstrap aws sts get-caller-identity --region ap-northeast-1

4.3 初期化と適用（dev 環境）

  • env/dev 配下で init → apply の順に実行します。

cd new-project-terraform-aws/env/dev

初期化（backend.tf の S3/DynamoDB が存在する前提）

terraform init -input=false

差分確認（任意）

terraform plan

適用

terraform apply -auto-approve

📝 メモ：

  • もし terraform init で backend 用の S3/DynamoDB が無くて失敗する場合は、
    先に env/bootstrap で state リソースを作成するか、既存リソースを import して整合を取ってください。

4.4 既存 Lambda 参照パターン（CreateFunction 禁止対応）

  • 組織の SCP/Permissions boundary で lambda:CreateFunction が禁止されているケース向けの回避策です。
  • 初回は コンソールで関数を手動作成 → Terraform は 既存関数を参照。

変数フラグで既存参照に切り替え（tfvars 側で設定している場合は不要）

terraform apply
-var="use_existing_lambda=true"
-var="lambda_function_arn=arn:aws:lambda:ap-northeast-1:123456789013:function:new-project-dev-rss-ingestion"
-var="add_lambda_permission=false"
-auto-approve

  • EventBridge → Lambda の Invoke 許可は 関数側のリソースベースポリシー で制御します（必要に応じて手動付与）。

4.5 動作確認（Lambda → S3 → Athena）

  1. Lambda を手動実行（コンソールでテスト {}）
  2. CloudWatch Logs に処理ログが出ることを確認
  3. S3 生成物（当日パーティション配下）を確認
  4. Athena（WorkGroup 固定）で SELECT が通ることを確認

直近1時間のログを tail（関数名は環境に合わせて変更）

AWS_PROFILE=terraform-bootstrap aws logs tail /aws/lambda/new-project-dev-rss-ingestion --since 1h

-- Athena（WorkGroup は専用WGに切り替え）
-- 当日分をサッと確認
SELECT *
FROM new_project_dev.rss
WHERE dt = 'YYYY-MM-DD'
LIMIT 10;

-- 日別件数の確認
SELECT dt, count(*) AS cnt
FROM new_project_dev.rss
GROUP BY dt
ORDER BY dt DESC;

4.6 よくあるエラーと素早い対処

  • AccessDenied: athena:StartQueryExecution

    • WorkGroup で結果保存先や KMS を固定しているか確認
    • 対象バケット/KMS の権限がロールに付与されているか確認

  • CreateFunction: 403

    • 組織の SCP/Permissions boundary が原因
    • 初回は手動作成 → 以降は既存参照で回避

  • AddPermission: 404/403

    • Lambda が未作成 / GetPolicy 不足
    • 先に関数を作成し、関数側のリソースベースポリシーで events.amazonaws.com を許可

  • S3 Put/Get: AccessDenied

    • IAM の Resource がバケット直下になっていないか（オブジェクトキー配下に限定）
    • ListBucket に prefix 条件を付けているか

4.7 検証チェックリスト（使い回しOK）

  • AWS SSO ログイン済み（aws sts get-caller-identity OK）
  • backend の S3/DynamoDB が存在、または import 完了
  • terraform init / plan / apply が成功
  • Lambda 手動実行で CloudWatch Logs が更新
  • S3（raw/rss/dt=YYYY-MM-DD/source=<name>/）に CSV が生成
  • Athena（専用 WorkGroup）で SELECT が成功
  • EventBridge ルール（15分間隔）が動作

5. セキュリティ・ベストプラクティス

5.1 IAM ポリシーは「最小権限」

  • ListBucket は必ず prefix 条件を付ける
    • ✅ 良い例: arn:aws:s3:::<raw-bucket>/raw/rss/*
    • ❌ 悪い例: arn:aws:s3:::<raw-bucket>（バケット直下だと過剰権限）
  • PutObject/GetObject はオブジェクトキー配下だけに限定
  • KMS は対象キーのみに制限（Encrypt/Decrypt/GenerateDataKey/DescribeKey）

5.2 暗号化は SSE-KMS をデフォルトで強制

  • S3 バケットは デフォルト SSE-KMS を設定
  • Athena WorkGroup の出力先も SSE-KMS で強制
  • 「デフォルト暗号化なし」だとレビューで落とされることが多い

5.3 リソースベースポリシーでの制御

  • EventBridge → Lambda の Invoke は 関数側のリソースベースポリシー で許可
  • IAM ロールに余計な権限を付けずに済むのでセキュア
  • Terraform 側では add_lambda_permission をフラグ化し、環境ごとに制御

5.4 組織ポリシー（SCP/Boundary）との付き合い方

  • 多くの組織では lambda:CreateFunction が禁止されている
  • 回避策:
    • 初回はコンソールで Lambda を作成
    • Terraform 側は use_existing_lambda=true で既存参照
  • 長期的には「運用専用ロール」を定義して CreateFunction を部分的に許可するのが理想

5.5 ログと監査

  • Lambda 実行ログは必ず CloudWatch Logs に出力
  • Athena クエリログも WorkGroup 経由で監査可能
  • S3 のアクセスログや CloudTrail 連携で「誰がいつ何をしたか」を可視化できるとさらに安心

6. トラブルシュート（実録）

ここでは、実際にハマったポイントとその解決策をまとめます。

6.1 Lambda CreateFunction が 403 になる

症状

  • terraform apply 時に lambda:CreateFunction が 403 で失敗

原因

  • 組織の SCP や Permissions boundary で CreateFunction が禁止されている

解決策

  • 初回だけ コンソールで関数を手動作成
  • Terraform は use_existing_lambda=true で既存関数を参照するように変更

6.2 Lambda AddPermission が 404 / 403 になる

症状

  • EventBridge → Lambda の Invoke 許可を Terraform で付与しようとすると失敗

原因

  • 関数がまだ存在しない
  • または GetPolicy 権限不足

解決策

  • コンソールから関数にリソースベースポリシーを手動追加
  • その後、権限が整えば IaC 化に戻す

6.3 RSS 取得が失敗する

症状

  • Lambda 実行時にタイムアウト / 接続エラー

原因

  • VPC 接続ありで NAT が無いケース
  • タイムアウト値が短すぎるケース

解決策

  • 基本は VPC 接続なし で動かす
  • やむを得ず VPC 内で実行するなら NAT Gateway を用意する
  • Lambda のタイムアウトを 60〜90秒 に調整する

6.4 Athena の結果保存でエラー

症状

  • クエリ実行時に AccessDenied や Output location not found が発生

原因

  • WorkGroup 側で出力先 S3 や SSE-KMS 設定がされていない
  • 実行ロールに権限が不足している

解決策

  • WorkGroup を 専用に作成し、S3 出力先と KMS を固定化する
  • S3/KMS 権限をロールに付与する

6.5 S3 バケットの import 周り

症状

  • terraform apply が S3 でハング / 403 / 409 エラーになる

原因

  • 既に同名バケットが存在していた
  • 読み取り系権限不足（GetBucketVersioning など）

解決策

  • terraform import を活用して既存バケットを state に取り込む
  • IAM 権限に s3:GetBucketVersioning, s3:GetEncryptionConfiguration などを追加

7. 他プロジェクトへの展開ポイント

今回つくった基盤は、そのまま別の案件でも再利用しやすいように設計しました。
横展開する際に気をつけたポイントをまとめます。

7.1 変数と命名規約を外出し

  • project, env, region を共通変数として定義
  • バケット名 / Glue DB 名 / KMS alias などは terraform.tfvars 側で差し替えられるようにした
  • 環境ごとに env/dev, env/stage, env/prod を切って使い回し

7.2 モジュールの入出力IFを固定化

  • modules/security-kms, modules/storage-s3, modules/analytics-athena-glue などの IF を固定化
  • 共通化すると、別プロジェクトでも「env/ 配下をコピーして tfvars を書き換えるだけ」で利用可能

7.3 Lambda 運用の標準化

  • 多くの組織では CreateFunction が禁止されているので「既存関数参照フラグ」を標準パターン化
  • IaC 側では EventBridge のスケジュールや IAM だけを管理
  • 関数の初期作成は人間がやって、以降のコード更新は CI/CD or UpdateFunctionCode で回す

7.4 EventBridge → Lambda 権限の統一

  • EventBridge → Lambda の Invoke は 関数側のリソースベースポリシーに統一
  • プロジェクトごとにバラバラにしないことで、セキュリティレビューがスムーズに通る

7.5 S3 のデフォルト設定をテンプレ化

  • SSE-KMS / Versioning / Public Access Block を強制するのをデフォルトにした
  • 「特別な理由が無い限り、この設定で」というルールを組織内で共有すると安心

8. まとめと次回予告

今回は Terraform × AWS データ基盤の設計と適用編（前編） をまとめました 🎉

  • ディレクトリ構成は env/ と modules/ を分けて再利用性を確保
  • state は S3 + DynamoDB Lock で安定運用
  • IAM は prefix 条件つきで最小権限を徹底
  • S3 / Athena は SSE-KMS を強制
  • Lambda は「既存関数参照」を標準化して CreateFunction 禁止にも対応
  • EventBridge → Lambda の権限は関数側リソースベースポリシーに集約

要するに、実務でハマったところを整理してハンドブック化した、という感じです。

次回（後編）では、もっと運用寄りのテーマにフォーカスします👇

  • 監視・通知のベストプラクティス（失敗回数 / レイテンシ / メトリクス監視）
  • Runbook（手順書）のサンプル
  • SCP / Permissions boundary と権限管理のリアルなTips

後編も、実務で役立つ内容をガッツリ書いていく予定です。

Discussion