photoncloud-monorepo/docs/architecture/baremetal-mesh-migration.md

ベアメタル向けサービスメッシュ移行計画

本ドキュメントでは、既存の PhotonCloud サービス群を、 Deployer/NodeAgent＋mTLS Agent ベースのサービスメッシュ風アーキテクチャに 段階的に移行するためのマイルストーンを定義する。

1. 現状整理フェーズ（完了済み前提）

• baremetal/first-boot:
  • 役割: 初回ブート時のクラスタ join・基本サービス起動。
  • 常駐ではなく oneshot 系 systemd unit 群。
• deployer/:
  • 役割: Phone Home によるノード登録と最低限の Node/Config 管理。
  • まだ常駐型 NodeAgent や ServiceInstance Reconcile は未実装。
• mTLS:
  • 各サービスごとに ad-hoc な TLS/mTLS 設定が存在。
  • dev ではしばしば平文／-k での接続。

2. フェーズ 1: Chainfire モデルと Deployer 拡張

目的: Chainfire をクラスタ状態のソース・オブ・トゥルースにする土台を作る。

• M1-1: specifications/deployer/README.md に定義した Cluster / Node / Service / ServiceInstance / MTLSPolicy モデルを Chainfire 上に作成。
  • PoC 用に photoncloud-ctl 的な小さな CLI で CRUD を実装。
• M1-2: deployer-server が NodeInfo を Chainfire にも書き出すように拡張。
  • 既存のローカルストレージ（ファイル or メモリ）は残しつつ、 Chainfire を optional backend として追加。
• M1-3: 管理 API に「サービス配置」を表すエンドポイントを追加。
  • 例: /api/v1/admin/services/{service}/instances で、 Node とインスタンス数を指定できるようにし、内部で ServiceInstance を生成。

3. フェーズ 2: NodeAgent（常駐型 Reconciler）の導入

目的: 各ノードで Desired State → Observed State の Reconcile を開始する。

• M2-1: plasmacloud-reconciler を NodeAgent として再定義/拡張。
  • --node-id と --chainfire-endpoint を引数に取り、無限ループで動作。
• M2-2: NodeAgent が自ノードの Node と ServiceInstance を watch し、 ログ出力のみ行う「read-only モード」を実装。
  • まだ systemd 操作やプロセス起動はしない。
• M2-3: systemd 統合（ベアメタルノード側）。
  • NixOS モジュールで services.node-agent.enable = true; を追加。
  • 既存 first-boot の後に NodeAgent を常駐させる。

4. フェーズ 3: サービスプロセス管理の Reconcile

目的: NodeAgent が実際にサービスプロセスを起動/停止できるようにする。

• M3-1: 各サービスの NixOS モジュールを見直し、 enable = false をデフォルトにした上で、 NodeAgent から systemctl start/stop で制御しやすい形に整理。
• M3-2: NodeAgent 内に「ServiceInstance → systemd unit 名」のマッピングを追加。
  • 例: service="chainfire" → unit="chainfire.service"
  • 単純な 1:1 マッピングからスタート。
• M3-3: Reconcile ループにプロセス制御を追加。
  • Desired にあるのに起動していなければ systemctl start。
  • Desired にないのに起動していれば systemctl stop。
• M3-4: 起動結果/ヘルスを Chainfire にフィードバック。
  • instances/{service}/{instance_id}.state を ready / unhealthy に更新。

5. フェーズ 4: mTLS Agent の導入（プレーンプロキシ）

目的: サービスメッシュの「形」を先に作り、まだ TLS を強制しない。

• M4-1: 新クレート mtls-agent（名称要検討）を作成。
  • 最初は平文 TCP/HTTP プロキシとして実装。
  • ローカル app_port ←→ mesh_port の中継のみを行う。
• M4-2: NodeAgent が ServiceInstance 起動時に、 mTLS Agent を隣に起動するフローを追加。
  • config ファイル生成 → systemctl start mtls-agent@{service} など。
• M4-3: Chainfire 上の ServiceInstance に mesh_port を登録。
  • 他サービスからの接続先として mesh_port を使う用意をする。
• M4-4: 一部サービス間通信（例: apigateway → creditservice）を mTLS Agent 経由に切り替える PoC。
  • アプリ側は client-common 抽象を通じて http://127.0.0.1:<mesh_control_port> を叩く。

6. フェーズ 5: mTLS 対応とポリシー制御

目的: mTLS/TLS/平文を Chainfire のポリシーで切り替えられるようにする。

• M5-1: mTLS Agent に TLS/mTLS 機能を実装。
  • dev では平文、stg/prod では mTLS をデフォルトに。
  • 証明書/鍵は既存の T031 TLS 自動化の成果物を利用。
• M5-2: Chainfire の MTLSPolicy を反映するロジックを Agent に実装。
  • (source_service, target_service) と Cluster の environment からモード決定。
• M5-3: Deployer から MTLSPolicy を編集できる管理 API を追加。
  • 例: /api/v1/admin/mtls/policies。
• M5-4: ステージング環境で「全経路 mTLS on」を試験。
  • 問題があればポリシーを permissive や plain に戻せることを確認。

7. フェーズ 6: 既存 ad-hoc mTLS 実装の段階的削除

目的: サービスコードから mTLS 実装を徐々に削除し、Agent に集約する。

• M6-1: 既存の各サービスから「直接 TLS ソケットを開いているコード」を列挙。
  • grep ベースで rustls, native-tls, tls 関連を洗い出し。
• M6-2: 重要なサービスから順に、通信経路を client-common 抽象経由に置き換え。
  • まずは dev 環境でのみ mTLS Agent 経由にする feature flag を導入。
• M6-3: 本番で mTLS Agent 経由通信が安定したら、 対象サービスから ad-hoc な TLS 設定を削除。
• M6-4: 最終的に、サービス側は「平文 HTTP/gRPC over localhost」という前提のみを持ち、 セキュリティ/暗号化はすべて mTLS Agent に移譲。

8. 段階ごとのロールバック戦略

• 各フェーズは Chainfire のキー空間と Deployer 設定で制御 できるようにする。
  • 例: NodeAgent を停止すれば、従来通り first-boot ベースの静的構成に戻せる。
  • 例: MTLSPolicy を削除すれば、Agent は平文モードに戻る（または完全停止）。
• NodeAgent/mTLS Agent を導入するときは、必ず 「全てのノードで Agent を止めると従来構成に戻る」状態を維持したまま進める。