小規模チームがゼロからTerraform構成を設計した話 - AI時代の運用を見据えて

こんにちは。PIVOTでソフトウェアエンジニアとして、Webフロントエンド、バックエンド、インフラを横断的に担当している@tawachanです。

この記事では、PIVOTのプロダクトチームでインフラのTerraform化を推進した経験を共有します。IaCできていなかった状態から、AI時代の運用を見据えた構成をゼロから設計した過程と判断基準について、振り返りながら紹介していきます。

PIVOTのチーム状況と背景

チーム体制

PIVOTはビジネス映像メディア「PIVOT」を運営する会社です。開発チームは正社員エンジニア3名、QAエンジニア1名、プロダクトマネージャー1名、業務委託で数名という体制で、PIVOTというプロダクトの開発と社内システムのメンテナンスを主なスコープとしています。

エンジニア3名は、iOS、Android、Web（フロントエンド・バックエンド）をそれぞれ担当しており、私がWebを担当しつつインフラ周りも見ています。

IaCできていなかった過去

もともとIaC化されていない状態でした：

• Google Cloudコンソール上からの手修正が常態化
• インフラ構成がコード化されておらず、属人化
• 変更履歴も追えない状態
• コンソールでぽちぽち操作していると意図しない変更をして事故ることもたまにあり、かなり不健全

よくある話ですが、これではインフラ変更のたびにコンソールを開き、手作業で設定を変更する運用が続きます。

クラウドネイティブ化とIaC構築の決断

内製化が進む中で、アーキテクチャをクラウドネイティブに寄せる作業が進行していました^[1]。このタイミングで、改めてIaC化を推進することを決めました。

ゼロからの構築なので、現在のチーム状況に最適化した構成を新規設計することにしました。そしてこの機会に、AI時代の運用も考慮した設計を取り入れることにしました。

Terraform構成のゼロからの設計

選択1: モノレポ vs リポジトリ分散管理

分散管理での失敗経験

実は、モノレポ化する前にPoC的に各リポジトリでTerraformを管理してみたことがあります。サーバーやWebフロントエンドのリポジトリそれぞれにCloud RunなどのTerraformコードを配置してみたのですが、早々に問題が見えてきました：

• ほぼ同じリソース（Cloud Run）なのに、リポジトリごとにフォルダ構成が微妙に違う
• 命名規則や変数の定義方法も統一されていない
• どうせ自分が全て操作するのに、リポジトリによって書き方が違うのがやりづらい
• すでに管理が煩雑になりそうで、破綻の予感がした

この経験から、「分散的にやりたくない」という気持ちが強くなり、モノレポ化を真剣に検討し始めました。

我々の選択: モノレポで一元管理

理由:

1. チーム体制: チームは1つ、インフラを見るのも固定メンバー
2. 実体験からの学び: 分散管理は小規模チームではすぐに破綻する
3. スケール後の懸念が少ない: LayerXのようにスケールしているチームでもモノレポを採用している^[2]なら、将来的にチームが成長しても大きな問題はないだろう

選択2: リソース種別ベースの構成

PIVOTの状況

PIVOTは1つのプロダクトを1つのチームで開発しており、複数プロダクトを複数チームで開発しているわけではありません。サーバー、フロントエンド、バッチなど、デプロイ単位や開発担当の違いはありますが、これらは「プロダクト」というより「コンポーネント」の分類に近いものです。

チームトポロジーの観点では、複数のプロダクトチームがそれぞれのインフラを管理する構成が理想的なケースもあります。しかし、我々は1チームで全体を見ているため、そのような組織的な境界はありません。

我々の選択: リソース種別ベースで横並び管理

この状況を踏まえ、以下の構成を採用しました：

modules/google-cloud/       # リソース種別ごとのモジュール
  ├── cloud-run-api/
  ├── cloud-run-web/
  └── cloud-run-job/

platform/google-cloud/      # 環境ごとの実装
  ├── pivot-stg/
  │   ├── cloud-run/       # 全てのCloud Runサービス
  │   ├── cloud-run-jobs/  # 全てのバッチジョブ
  │   └── ...
  └── pivot-prod/
      └── ...

この構成のメリット:

1. 横並びでの比較が容易: 同じリソース種別（例: Cloud Run）の設定が一箇所に集まっているため、設定の統一や比較が簡単
2. 固定担当者の見通しの良さ: 担当が固定されている場合、リソース種別で整理されている方が認知負荷が低い

もし複数プロダクトを複数チームで開発する状況になれば、プロダクトチームごとの管理を検討することになるでしょう。しかし現時点では、リソース種別ベースで横並び管理することが、最も見通しがよく効率的だと判断しました。

AI時代を見据えた設計判断

上記の選択において、実はAI活用という観点が重要な判断軸になっていました。

モノレポがAI活用に有利な理由

コンテキストが一箇所に集約されることで、Claude CodeやCodex CLIが全体を理解しやすくなります。実際に分散管理を試してみて、同じリソース種別が複数箇所に散らばることの煩雑さを体感したことが、モノレポ化の強い動機になりました。

AIツールは関連するコードが近くにあることで、より適切な提案ができます。リソースが点在していると、AIは「どのリポジトリのどのファイルか」を探すところから始める必要があります。

リソース種別ベースがAI活用に有利な理由

同じリソース種別が横並びで存在することで、AIが既存設定を参考にしやすくなります。具体的には：

• 「既存のバッチジョブと同じ構成で新しいデータ処理ジョブを作って」: 同じ cloud-run-jobs/ ディレクトリ内の設定を参照して適切に生成
• 「全てのCloud Runサービスのタイムアウトを60秒に統一して」: cloud-run/ ディレクトリ全体を一度に処理できる
• 「このAPIサーバーのCloud Monitoringアラートで、エラー率5%以上で通知して」: monitoring/ と cloud-run/ を横断的に参照して設定

また、変数名や命名規則が統一されているため、AIが既存パターンを学習しやすく、一貫性のある変更提案が得られます。

AI時代のインフラ運用

従来は「Terraformの書き方」を覚える必要がありましたが、AI時代では「何をしたいか」を自然言語で伝えれば、AIが適切なTerraformコードに変換してくれます。

この時、参考にできるコードが近くにあることが重要になります。モノレポかつリソース種別ベースの構成は、この要件を満たす理想的な形です。

そして、GitOpsフロー（PR→plan、merge→apply）を構築することで、Terraformの書き方を知らないメンバーでも、AIに自然言語で指示してTerraformコードを生成し、PRを作成してレビューを受けることで、安全にインフラ変更を提案できるようになりました^[3]。

状況依存の意思決定

Terraform構成に「絶対的な正解」は存在しません。チーム規模、成長フェーズ、インフラ担当の体制、プロダクトの独立性など、様々な要素で最適解は変わります。

我々の判断軸（2025年時点）：

1. 小規模チームのフットワークの軽さを活かす: 固定メンバーで見通しよく管理、素早い意思決定と変更
2. AI時代のコード構成への配慮: コンテキスト集約によるAI活用の最大化、自然言語でのインフラ操作を前提とした設計
3. 将来の拡張性: GitHub管理のIaC化、他サービス・他クラウドの追加も見据えた箱作り

この構成がフィットしなくなるタイミング（プロダクトチームが複数に増える、インフラ担当が複数になる、プロダクトごとのデプロイサイクルが完全に独立する）では、改めて再検討すればよいと考えています。

現在の到達点

実現できたこと

• プロダクト開発に関わる主要リソースのTerraform化完了
• モノレポ × リソース種別ベースの構成確立
• AI支援によるインフラ操作の民主化: Terraformの書き方を知らないメンバーでも、AIに自然言語で指示してPRを作成し、レビューを受けることで安全にインフラ変更を提案できる環境

今後の課題

現在はプロダクト開発に関わる主要リソースのTerraform化を完了していますが、まだ残っているリソースがあります。次のステップは以下です：

• ネットワーク周りなど基盤的なリソースのTerraform化: VPCやサブネットなど、まだコンソールで管理しているリソースを順次Terraform化
• GitHub組織管理のIaC化: チーム・リポジトリ管理もコード化し、全てのインフラをIaCで管理する状態を目指す

おわりに

振り返ると、Terraform構成をゼロから設計したことは、中長期のインフラ管理の効率やチームの運用のしやすさを左右する重要な機会でした。

今回の取り組みを通じて学んだことは、ベストプラクティスは参考にしつつも、自分たちのチームの状況、成長フェーズ、文化に合わせて選択することの重要性です。そして、状況が変われば構成も変える柔軟性を持つことが大切だと感じています。

特に印象的だったのは、AI活用を前提にした設計の重要性です。これからのインフラ運用では、AIがコードを読み書きすることが前提になります。コンテキストの集約、参照可能性、一貫性といった要素が、従来以上に重要になってきています。

この記事が、同じような状況にあるチームの参考になれば幸いです。もし質問やフィードバックがあれば、ぜひコメントやXでお気軽に声をかけてください。

脚注

1. オンプレ時代にはローカルファイルにキャッシュを置くなどStatefulな構成で、そのままGoogle Cloud上のVMに移行していました。サーバーをGoで書き直しながら、ステートレスな構成にしてCloud Runに載せるアーキテクチャ刷新を進めていました。このあたりの話も別途記事にするかもしれません。

2. Terraform運用のベストプラクティス - LayerX Tech Blog LayerXは、メンバーが多く、プロダクト側にインフラ責務を渡してもよさそうな規模でも、メンテコスト観点で中央管理を選択していました。大規模チームでさえ中央管理なら、小規模チームの我々はより一層、集約管理が合理的だと考えました。また、GitHub組織管理、マルチクラウド等も視野に入れたディレクトリ構成を参考に、我々も将来的にGitHub組織・チーム・リポジトリ管理(modules/github/)なども追加できる箱を作っています。

3. GitHub Actions + Workload Identity Federationによる自動plan/apply、複数tfstateの並列処理などの詳細は別記事で紹介予定です。