IaCのリポジトリ構成の設計 — モノレポとマルチレポの分け方

IaCのリポジトリ構成は、コードを書き始めた後では変えにくい判断のひとつだ。パイプラインの参照先、stateのバックエンド設定、チームのアクセス権限、CI/CDのトリガーがすべて構成に依存するためで、「後から整理する」が実際には大規模な移行プロジェクトへと膨らみやすい。モノレポとマルチレポのどちらを選ぶかは一概に決まらないが、「何を一緒に管理し、何を切り離すか」という境界を最初に設計しておかないと、変更のたびに複数リポジトリを横断する調整が慢性的に発生する。本記事では、構成の違いが引き起こす問題の構造と、チーム・環境・コンポーネントの軸で境界を引く判断基準を整理する。

コードの置き場所を決めずに増やして依存が絡む構造

暗黙の依存が顕在化するタイミング

構築の初期段階では、Terraformのコードを1つのリポジトリにまとめておくことが多い。対象が数台・3環境以下のうちはディレクトリ構造だけで管理できるが、担当者が増え、環境数が10を超えてくると「あのモジュールを変えると、どの環境のstateに影響が出るか分からない」という状態に陥りやすい。暗黙の依存は、コードを増やした段階ではなく、変更を加えようとした段階で初めて顕在化する。気づいたときには数十のディレクトリが同一リポジトリに混在しており、切り離すコストがすでに膨らんでいる。

マルチレポに分散した後の連鎖変更問題

「チームごとに独立したリポジトリを持たせる」という判断は一見すっきりしているが、共通モジュールを参照している場合、モジュール側の変更をリリースするたびに参照側のリポジトリすべてでバージョンを上げる作業が発生する。リポジトリ数が5〜6本なら許容範囲だが、20本を超えると横断的なアップデートに数日単位の工数がかかるようになる。「モジュールを更新したが、古いバージョンを参照したまま本番に適用してしまった」という事故は、こうした構成から生まれやすい。連鎖変更の管理が追いつかなくなると、モジュールの更新そのものが後回しになり、セキュリティパッチの適用遅延につながることもある。

「とりあえず」の構成が移行コストを生む理由

リポジトリ構成を後から変えることは、コードのリファクタリングより難しい。パイプラインの参照先、stateのバックエンド設定、チームの作業習慣、CI/CDのトリガー設定がすべて構成に依存しているためだ。ある現場では「最初は小さいから後で考える」という判断が、3年後に数百のTerraform workspaceと15以上のリポジトリを整理する大規模な移行プロジェクトへと発展した、という話を耳にすることがある。構成の設計は、コードを書き始める前に一度だけ投資すべき判断であり、その場しのぎの選択が後になって大きなコストとして戻ってくる。

モノレポが向く構築・マルチレポが向く構築の違い

モノレポが効くのは変更の波及を一元管理したいとき

インフラのコードはアプリのコードと異なり、変更が複数の環境・複数のリソースに同時に影響することが多い。ネットワーク基盤、IAM、セキュリティグループといった「全体に波及するレイヤー」を持つ構築では、モノレポに一元化することで変更の影響範囲をリポジトリをまたがずに把握できる。開発・ステージング・本番の3環境で同一モジュールを使っているなら、1つのPRで3環境の変更を同時にレビューできる構成の方が整合性を保ちやすい。チームが10人以下で担当領域が重なる場合も、モノレポの方がコンテキストを共有しやすい。

マルチレポが効くのはリリースサイクルと権限を分けたいとき

チームが独立してリリースを進められる状態にあるなら、マルチレポの方が摩擦が少ない。ネットワーク基盤チームとアプリインフラチームが別々のスプリントで動いている場合、同一リポジトリでのコンフリクトや承認待ちがボトルネックになりやすい。また、セキュリティ上の理由でリポジトリへのアクセスを分離したい場合——本番のIAMコードを開発チームのメンバーから見せたくないケース——もマルチレポが適している。アクセス制御の粒度がリポジトリ単位になるため、権限設計とコード構成を一致させやすい。

判断の起点：変更の単位とレビューの単位が一致するか

モノレポかマルチレポかを選ぶ前に確認すべきは「変更の単位とレビューの単位が一致しているか」だ。一つの変更が常に複数コンポーネントにまたがるなら、それをリポジトリで分割しても境界に意味がない。逆に、コンポーネントごとに独立したリリース判断が必要なら、同一リポジトリに置くことで余計な制約が生まれる。チームの構造と変更の粒度を先に整理し、その結果として構成を決める順序が重要だ。構成ありきで境界を引こうとすると、実態と合わない分割が生まれやすい。

環境・コンポーネント・チームでどう分けるかの判断

環境軸で分けるパターンの落とし穴

環境（dev/stg/prod）をリポジトリで分ける構成は一見シンプルだが、実際には本番と開発の構成が乖離しやすくなる。「stgでテストしたコードが、prodリポジトリには別の書き方で実装されていた」という問題が起きやすく、差分の把握が困難になる。環境差分はリポジトリで管理するより、同一リポジトリ内のtfvarsやワークスペースで吸収する方が整合性を保ちやすい。環境をリポジトリで分けることが有効なのは、本番環境へのアクセス権限を完全に分離しなければならないセキュリティ要件がある場合に限られる。

コンポーネント軸で分けるときの依存方向の設計

ネットワーク・コンピュート・データベース・IAMといったコンポーネント単位でリポジトリを分ける構成は、責任範囲の明確化に向いている。ただしコンポーネント間で参照が発生する場合——VPC IDをコンピュートが参照するケース——は、terraform_remote_stateかデータソースで橋渡しが必要になる。この橋渡しが増えるほど変更のトレースが難しくなる。コンポーネント軸で分ける場合は、依存の方向を一方向に保つことが設計上の原則となる。循環依存が生まれた時点で、その分割は設計ミスとして見直す必要がある。

チーム軸の分割と横断変更への備え

チームごとにリポジトリを持たせる構成は所有者の明確化という点で分かりやすいが、チームをまたぐ変更——セキュリティポリシーの更新がネットワークとIAMの両方に影響する場合——が増えると、複数リポジトリのPRを同時に管理する必要が生じる。この調整コストは予想以上に大きく、変更が後回しになりセキュリティ上のリスクを抱えたまま運用が続く、という話を現場ではよく聞く。チーム軸の分割を採用するなら、横断変更のプロセス——誰が起点になり、どの順序でマージするか——を設計に組み込んでおく必要がある。

比較表: モノレポ／マルチレポ／ハイブリッドの向き不向き

構成パターン	向く場面	向かない場面	主なリスク
モノレポ	チームが小さく変更が複数コンポーネントにまたがる／全環境を一括レビューしたい／モジュールの影響範囲を一目で把握したい	チームが大きくアクセス制御を細かく分けたい／コンポーネントごとに独立したリリースが必要	リポジトリが肥大化しパスフィルタの設定ミスで無関係のパイプラインが動く／権限制御が粗くなる
マルチレポ	チームが独立してリリースできる／アクセス権限をリポジトリ単位で分けたい／コンポーネントのライフサイクルが明確に独立している	共通モジュールへの依存が多い／横断的な変更が頻繁に発生する	共通モジュールのバージョン管理が煩雑になる／横断変更の追跡コストが増大する
ハイブリッド（基盤はモノレポ・アプリ層はマルチレポ）	ネットワーク・IAMなど共通基盤と、アプリ別インフラが明確に分離できる／チームの境界と技術の境界が一致している	境界の引き方が曖昧なまま採用すると両方の欠点を引き継ぐ	基盤側の変更がアプリ側にどう伝播するかを別途管理する必要がある

state・モジュール・パイプラインとの境界の合わせ方

stateの境界とリポジトリの境界を一致させる

Terraformのstateファイルは、変更の影響範囲を決定する最重要の境界だ。リポジトリの境界とstateの境界がずれていると、「同じstateを複数のディレクトリから操作できてしまう」か、「別stateのリソースをリポジトリ内から直接変更しようとする」か、どちらかの混乱が起きる。設計の原則として、1つのstateバックエンドに書き込むのは1つのリポジトリ（またはディレクトリ）だけ、という境界を守ることが重要だ。state参照（terraform_remote_state）は読み取り専用の橋渡しとして使い、書き込み権限の重複を避ける。

モジュールのバージョン管理とリポジトリの独立性

共通モジュールをどこに置くかは、リポジトリ構成の中でも特に判断が難しい部分だ。モノレポなら同一リポジトリ内のローカルパスで参照できるが、変更の影響を閉じ込めにくい。マルチレポなら、Gitタグによるバージョン管理で影響範囲を制御できるが、更新のタイミングを各リポジトリで意識的に管理する必要がある。安定しやすいパターンとして、モジュール専用のリポジトリを独立させ、セマンティックバージョニングでリリースを管理する構成がある。モジュールの変更が全リポジトリに即時伝播することを避けるバッファとして機能し、各チームが自分のペースでアップデートを取り込める。

パイプラインのトリガー設計とリポジトリ境界の整合

CI/CDパイプラインのトリガーは、リポジトリ境界に強く依存する。モノレポでは、特定ディレクトリの変更だけに反応するパスフィルタを設定しないと、無関係の変更でも全環境のパイプラインが動いてしまう。マルチレポでは各リポジトリが独立したパイプラインを持つためシンプルだが、横断的な変更を複数のパイプラインで追跡する必要がある。パイプライン設計は後から変えにくいため、リポジトリ構成と同時に設計しておくことが望ましい。「パイプラインのトリガー単位＝変更の影響単位」になっているかを確認することが、設計の整合性チェックになる。

分けすぎて横断変更が回らなくなる境界

リポジトリ数が増えるほど調整コストが増大する

リポジトリを細かく分けすぎると、変更のたびに複数のPRを出し、複数のレビューを依頼し、複数のパイプラインを確認する作業が発生する。リポジトリが15本以上になっている環境では、横断的な変更1件に対して半日から1日の調整コストがかかるようになる、という話は珍しくない。「責任範囲が明確になる」という利点が、調整コストの増大によって相殺されてしまう。分割の判断は「独立性を高めるコスト」と「調整コストの増大」のトレードオフとして設計段階で見積もっておく必要がある。

分割の一次条件と二次条件

リポジトリを分ける価値があるのは「そのコンポーネントが他と独立したタイミングでリリースできる」場合に限られる。依存関係があって結局は同時にリリースせざるを得ないなら、分割しても境界に意味がない。「独立してリリースできるか」を分割判断の一次条件とすることで、不必要な分割を防げる。あわせて「そのリポジトリへのアクセス制御が独立して必要か」を二次条件とすると、セキュリティ要件との整合も取りやすい。この2条件のどちらも当てはまらない場合は、分割しないことを原則とする方が後の調整コストを抑えられる。

統合のタイミングと移行コストの現実

分けすぎた構成を統合するコストは、分割するコストより大きい。stateのバックエンド統合、パイプラインの再設計、チームの作業フローの変更が同時に発生するためだ。「分けるのは簡単、まとめるのは難しい」という原則を念頭に、最初から統合しやすい粒度で設計しておくことが現実的な選択だ。分割を検討する際は「後から統合できるか」を確認してから判断することで、可逆性のない設計判断を減らせる。手を動かす前に構成の変更コストを見積もるプロセスを設けておくと、後になって「やっぱり戻したい」という事態を回避しやすくなる。

リポジトリ構成設計チェックフレーム

以下のチェックフレームは、リポジトリ構成を決定する前に確認する判断の順序を示したものだ。上位の項目ほど優先度が高く、下位に進むほど細部の設計に入る。

1. 変更の単位を確認する：一つの変更が常に複数コンポーネントにまたがる場合は、分割しても境界に意味が薄い。変更の単位がコンポーネントごとに独立しているか確認する。
2. リリースの独立性を確認する：そのコンポーネントは他と独立したタイミングでリリースできるか。依存関係があって常に同時リリースが必要なら分割の優先度は低い。
3. アクセス制御の要件を確認する：リポジトリ単位でアクセス権限を分離しなければならないセキュリティ要件があるか。ない場合は、権限設計を理由に分割する必要はない。
4. stateの境界を先に決める：リポジトリ構成を決める前に、stateの境界（何が1つのstateバックエンドに入るか）を確定する。stateの境界がリポジトリの境界と一致するように構成を合わせる。
5. 共通モジュールの配置を決める：共通モジュールをモノレポのローカルパスで参照するか、独立リポジトリでバージョン管理するかを決定する。リポジトリ数が増える構成なら、モジュール専用リポジトリとセマンティックバージョニングが安定しやすい。
6. パイプラインのトリガー単位を確認する：選択したリポジトリ構成で、パイプラインのトリガー単位が変更の影響単位と一致しているかを確認する。ズレがある場合はパスフィルタか構成の見直しを行う。
7. 横断変更のプロセスを設計する：チームや構成をまたぐ変更が発生した場合の手順（誰が起点になり、どの順序でマージするか）を文書化しておく。プロセスのないまま分割すると、横断変更が慢性的に滞る。
8. 統合コストを見積もる：採用する構成を後から変えるとしたら何が必要か（state移行・パイプライン再設計・権限変更）を事前に洗い出す。変更コストが高い場合は、より統合しやすい構成に戻して設計を再検討する。

リポジトリ構成の設計は一度決めると変えにくい判断だが、上記のフレームに沿って整理することで「なぜこの構成を選んだか」の根拠を持ちやすくなる。構成の選択そのものより、境界の引き方とその理由を記録しておくことが、チームが拡張した後でも構成を維持しやすくする。手を動かす実装の詳細はセミナーや専門書に委ねるとして、判断の根拠を設計段階で固めておくことが、後の混乱を防ぐ最も効果的な投資になる。