Twelve-Factor App

Twelve-Factor App とは

Twelve-Factor App は、SaaS として提供する Web アプリケーションを構築するための 12 項目の方法論である。原典は 12factor.net で公開されており、著者名義は Heroku の共同創業者 Adam Wiggins、初出は 2011 年で、同社のプラットフォーム上で多数のアプリを開発 / 運用 / スケールさせた経験が根拠として示されている。特定の言語やフレームワークには依存しない。

原典が掲げる狙いは冒頭に列挙されている。宣言的なセットアップで新規参加者の立ち上がり時間とコストを下げる、実行環境との契約を薄く保って移植性を確保する、サーバー管理を不要にするクラウド上への配置に適合する、開発と本番の差を詰めて継続的デプロイを可能にする、道具立てやアーキテクチャを変えずにスケールアップできる、の 5 点である。逆に言えば、この 5 点を必要としないソフトウェアへ当てはめる根拠は原典にない。「あらゆる環境に効く普遍原則」として読むより、手元の対象がこの狙いを共有しているかを先に確かめる方が実用的だ。

12 の原則

コードベース: バージョン管理される 1 つのコードベースから、複数の環境にデプロイする
依存関係: 依存関係を明示的に宣言し、分離する (package.json, requirements.txt)
設定: 設定を環境変数に格納する。コードに設定をハードコードしない
バッキングサービス: データベースやキューなどの外部サービスを、アタッチされたリソースとして扱う
ビルド、リリース、実行: ビルド、リリース、実行の 3 ステージを厳密に分離する
プロセス: アプリケーションをステートレスなプロセスとして実行する
ポートバインディング: ポートバインディングによってサービスを公開する
並行性: プロセスモデルによってスケールアウトする
廃棄容易性: 高速な起動とグレースフルシャットダウンで堅牢性を最大化する
開発/本番一致: 開発、ステージング、本番をできるだけ一致させる
ログ: ログをイベントストリームとして扱う
管理プロセス: 管理タスクを 1 回限りのプロセスとして実行する

コンテナ / マネージドサービスとの対応

原典が書かれた 2011 年の実装手段は仮想マシンと PaaS だったが、原則の多くはその後の実行基盤の機能へ写像できる。2026 年 8 月時点の対応例を挙げる。

原則 3 (設定) → Kubernetes の ConfigMap / Secret、Lambda の環境変数
原則 4 (バッキングサービス) → マネージドサービス (RDS, DynamoDB, SQS) の活用
原則 6 (プロセス) → 呼び出しごとに独立した実行を前提とする関数の実行モデル。プロセスに状態を持たせない設計の詳細はステートレスで扱う
原則 8 (並行性) → コンテナのオートスケーリング、Lambda の同時実行
原則 9 (廃棄容易性) → コンテナの高速起動、Lambda のコールドスタート最適化

写像が崩れやすい 3 箇所

対応表は便利だが、原則の文言をそのまま守ると意図から外れる箇所がある。

設定 (原則 3) は「環境変数へ格納する」と書かれている。これは設定項目が少数だった時代の格納先の指定であって、原則の意図はコードから設定を切り離すことにある。環境変数は子プロセスへ継承され、クラッシュ時のダンプや起動ログに載り得るため、機密情報まで実体を環境変数へ展開すると露出面が広がる。実務では秘密情報だけシークレット管理サービスの参照名を渡し、実体はプロセス内で取得して保持する形に分ける。

ログ (原則 11) は標準出力へイベントストリームとして書き捨て、収集 / 保管 / 検索は実行環境の仕事とする。ここで見落としやすいのは形式である。集約先が構造化イベントを前提にしている場合、人が読む前提の行を流すだけでは検索も集計もできない。ストリームとして扱う原則を守りながら、1 行 1 件の機械可読な形式にする必要がある。

ビルド、リリース、実行 (原則 5) は、コンテナではイメージがビルド成果物、イメージと設定の組み合わせがリリース、起動したコンテナが実行に対応する。崩れるのはイメージへ環境固有の設定を焼き込んだときだ。環境ごとにビルドが必要になり、本番で動くイメージが検証したイメージと別物になる。同一のイメージを全環境へ配って設定だけ差し替えられるかが、3 段が分離できているかの判定基準になる。

実務での適用

すべての原則を厳密に適用する必要はなく、プロジェクトの状況に応じて優先度をつける。特に重要なのは以下の 4 つだ。

原則 3 (設定の外部化): 環境ごとの設定をコードから分離する。最も基本的で効果が高い
原則 6 (プロセス): 水平スケールと障害耐性の基盤。状態をどこへ追い出すかが設計の中心になる
原則 10 (開発/本番一致): 「開発環境では動くのに本番で動かない」問題の防止
原則 11 (ログのストリーム化): CloudWatch Logs や Datadog への集約を前提とした設計

原典の現況

原典本文の最終更新は 2017 年である (12factor.net のフッター表記)。2024 年 11 月に、方法論を改めてオープンソースとして公開し、以後の改訂は公開リポジトリでの議論を通じて進めるという告知が原典のブログに出た。ただし 2026 年 8 月時点で、そのリポジトリからリリースとして公開された改訂版はなく、12factor.net が示す項目は初出の 12 項目のままである。原則の文面を引く場合は、この「本文は据え置き、議論は別の場所」という状態を踏まえて、どの時点の記述かを添えて引用するのが安全だ。

適用するかどうかの判断

12 項目すべてを満たすことが目的ではない。次の 3 点で線を引く。

要求量に応じて同じプロセスを増やす必要があるか。単一プロセスで足り増やす予定もない社内ツールでは、プロセスモデル (原則 8) と廃棄容易性 (原則 9) への投資は回収できない
環境が 2 つ以上あるか。開発と本番を分けた時点で設定 (原則 3) と開発/本番一致 (原則 10) は効き始め、ステージングや検証環境が増えるほど効果が伸びる
状態をアプリの外へ出せるか。出せない要件 (ローカルに置く大きな中間ファイル、常駐させたまま使う計算資源など) がある場合は、原則 6 を諦める代わりに何を失うか (無停止での入れ替え、任意時点での再起動、障害時の別ノードへの移動) を先に把握しておく

サイト情報