Terraform IaC 実践ガイド：概要 — GCP/AWS マルチクラウド構成と AI 駆動運用

🗺️ このシリーズが扱うもの

本記事はシリーズ 「Terraform IaC 実践ガイド」第 1 回（概要） です。題材は、複数クライアントの本番環境を 1 つの Terraform リポジトリで管理する、GCP + AWS のマルチクラウド基盤。机上のサンプルではなく、実運用している基盤の設計判断を一般化して解説します。

このシリーズで一貫して主張するのは 1 点です。

Terraform は「書く」より「運用する」フェーズの設計が、事故を分ける。

行き当たりばったりの terraform apply を避け、設計 → 準備 → モジュール化 → CI/CD → 運用の各段階を、再利用可能で安全な形に組み上げます。さらに本基盤は、その開発自体を AI エージェント（Claude Code）とのステアリング駆動開発で回しています（後述）。

🏛️ 基盤アーキテクチャの全体像

この基盤が満たす要件は次の通りです。

マルチクラウド: GCP をメイン（Cloud Run / Cloud SQL / Pub/Sub）、AWS を補完（Cognito 認証・SES・Lightsail）
マルチクライアント: 複数のクライアント案件 + 横断 EC サービス群を、同一の部品で構築
単一リポジトリ: すべてのスタックを 1 リポジトリで管理し、CI/CD で動的にデプロイ
キーレス: 長寿命の認証キーをどこにも置かない（WIF）

各クライアントは独立した GCP プロジェクトに分離し、サービスアカウント・WIF・State プレフィックス・DB・LB をすべて分けます。「同一プロジェクトに本番と検証を同居させない」のが大原則です（理由は第 2 回）。

🚫 行き当たりばったりの apply を避ける

Terraform 作業で最も避けるべきは、調査不足のまま terraform apply を実行することです。よくある失敗：

権限不足で apply が途中失敗 → 中途半端なリソースが残る
API 未有効で 403 SERVICE_DISABLED
State の保存先を決めずローカル実行 → チーム共有不能
手動で作ったリソースと Terraform が衝突（State drift）

これを防ぐ作業手順はシンプルです。

1. 必要な権限・依存・API を調査
   ↓
2. 完全な Terraform コードを作成
   ↓
3. terraform plan で差分確認
   ↓
4. レビュー後に CI 経由で apply

手順 1 を飛ばして 4 に進まない。 準備の具体は第 2 回準備編で扱います。

🔐 認証はキーレス（WIF）が前提

CI/CD からの認証にサービスアカウントキー（JSON キー）を使いません。漏洩リスクとローテーション運用コストが見合わないためです。

方式	セキュリティ	推奨
サービスアカウントキー	漏洩リスク・要ローテーション	❌
Workload Identity Federation（WIF）	キーレス・ローテ不要	✅
`gcloud auth`（ローカル個人）	手動ログイン	開発のみ

GitLab CI の OIDC トークンを GCP の Workload Identity Pool が短命 access token に交換し、さらに GCP → AWS STS へ連鎖させることで、GCP も AWS も鍵ゼロで認証します。詳細は第 4 回 CI/CD パイプライン編と WIF でキーレス認証。

🧩 モジュールは 3 層に分ける

再利用の単位を、抽象度で 3 層に分離します。

terraform/
├── environments/               # 環境別エントリーポイント（stg / prod × スタック）
├── infra/prod/infra-bootstrap/ # bootstrap（State バケット・WIF Pool 等／ローカル実行）
└── modules/
    ├── infra/                  # ① 基盤プリミティブ（1 リソース群 = 1 モジュール）
    │   ├── gcp/                #   cloud-run, cloud-sql, multi-service-load-balancer, gitlab-wif, ...
    │   └── aws/                #   cognito, ses, lightsail, gitlab-oidc, ...
    ├── clients/                # ② クライアント単位の構成（①を束ねる）
    │   ├── client-a/
    │   └── client-b/
    └── services/               # ③ 横断サービス（{業務ドメイン}/{サービス} の 2 階層）
        └── app-domain/
            └── shared-svc/

クラウド別にモジュールを分離することで GCP と AWS の依存が混ざらず、影響範囲が明確になります。cloud-run のような部品は、クライアント A でも B でも同一コードのまま、変数だけ変えて再利用します。この設計原則は第 3 回モジュール設計編で深掘りします。

💾 State は GCS に集約する

マルチクラウドでも、State の保存先は GCS（Cloud Storage）1 箇所に統合します。

クラウド	リソース	State バックエンド
GCP スタック	Cloud Run / SQL 等	GCS
AWS スタック	Cognito / Lightsail 等	GCS（S3 ではなく）

クラウドごとにバックエンドを分けると、管理対象が増えてオペミスの温床になります。GCS に集約し、terraform/state/{category}/{client}/{env} のようなプレフィックス規約でスタックごとに分離。バージョニングとロックは必須です（第 2 回で構築手順）。State 運用の事故対応は第 5 回運用編。

🤖 この基盤はステアリング駆動で開発している

本シリーズのもう 1 つの軸が、インフラ開発そのものを AI エージェント（Claude Code）とのステアリング駆動開発で進めていることです。tf コードの生成・レビュー・ローカルでの plan 確認・git push・MR 作成までを Claude Code が一貫して運用し、人間はレビューと本番承認のゲートを担います（全運用ループは第 5 回運用編で詳述）。

仕組み	配置	役割
CLAUDE.md	リポジトリ直下	必須ルール・禁止事項（例：prod 直 apply 禁止、state 操作前の実態確認必須）
Skill / Agent	`.claude/`	Terraform 規約・レビュー観点・モジュール設計原則を AI に発火
ステアリング	`.steering/`	M / L サイズのタスク単位で要件・設計・決定を SSoT 化

インフラ変更はサイズ（S / M / L）で扱いを変え、M 以上は「いきなり apply」せずステアリングを起こしてから着手します。State drift 解消のような不可逆操作こそ、手順を AI に逸脱させないためにステアリングが効きます（第 5 回で詳述）。

新規スタックは AI が規約どおりに生成する

ここが効きます。新しいクライアント・スタックを追加するとき、専用の Terraform エージェントが「まず既存の類似構成（client-a / client-b 等）を読む」ことを鉄則とし、規約どおりに main.tf / variables.tf / outputs.tf / backend.hcl 一式を生成します。命名規約・3 層モジュール構成・backend 設定・組織ポリシー上の前提（Tag 権限・bootstrap 登録）を、AI が CLAUDE.md / Skill のルールに沿って満たします。

人間の役割は MR でのレビューと承認。ゼロから手書きするのではなく、AI が規約準拠の叩き台を生成 → 人間が判断という分業です。これを第 4 回の動的 child pipeline（.gitlab-ci.yml を触らない）と組み合わせると、新しいクライアントの追加が「ディレクトリを 1 つ足す」作業に近づきます——tf 一式は AI が規約生成し、CI 設定は不変。これがモジュール管理 × AI ステアリングの到達点です。

なぜ「設計原則を AI に守らせるルール化」が必要かは、AI 開発シリーズが扱います。インフラと AI 駆動開発は地続きです。

ステアリング駆動開発とは：概要

Claude Code 7層ハーネスエンジニアリング

ブレインストーミングとサイジング

🎯 まとめ

題材は GCP + AWS のマルチクラウド・マルチクライアント基盤を単一リポジトリで管理する実運用構成
キーレス（WIF）・3 層モジュール・State の GCS 集約が設計の柱
Terraform は 運用フェーズの設計が事故を分ける
開発自体を AI ステアリング駆動で回し、運用ルールを CLAUDE.md / Skill / ステアリングに明文化
新規スタックは AI が既存規約を手本に tf 一式を生成 → 人間がレビュー・承認。動的 child pipeline と合わせ「新規クライアント追加 ≒ ディレクトリ追加」に近づく

次は第 2 回準備編。コードを書く前に整えるべきアカウント・認証・権限・State・bootstrapを、実プロジェクトの落とし穴つきで解説します。

📚 シリーズ記事

#	タイトル	内容
1	概要（本記事）	マルチクラウド構成の全体像と AI 駆動運用
2	準備編	アカウント設計・WIF 認証・bootstrap・State 管理
3	モジュール設計編	再利用可能なモジュールの設計原則
4	CI/CD パイプライン編	動的 child pipeline・WIF キーレス認証・GCP↔AWS
5	運用編	State drift 解消・障害対応・AI 運用ループ

関連記事

WIF でキーレス認証 — 本基盤の認証レイヤの中心
BtoB SaaS セキュリティ設計総覧 — インフラの全体位置づけ
ステアリング駆動開発とは：概要 — 本基盤を AI と開発する手法