[takemi-ohama]

手元で動かす OpenBao のサーバにも、コンテナの中の bao から届くようにしました。接続先が loopback のときは host.docker.internal に置き換えます。あわせて、サーバの用意の文書・ポリシーの雛形・試用の構成を加え、確定仕様からサーバの前提を外しました（#295）。

利用者向けの変化

• 手元で動かす OpenBao のサーバを指す loopback の接続先は、コンテナの中では host.docker.internal に置き換わります。これでコンテナの中の bao からサーバへ届きます。
• OpenBao のサーバの用意の手順は docs/user/openbao-server.md にあります。
• ポリシーの雛形（devbase-user と、v1・v2 の team-read / team-write）と試用の構成（docs/user/openbao/compose.yml）を使えます。
• コンテナの BAO_ADDR を置き換えない場合は、network_mode: host の dev サービスを足す手順を docs/user/env-backend.md で案内します。

移行の手順

• 無し

変更の要点

• lib/devbase/commands/container.py: コンテナへ渡す OpenBao の接続先が loopback のとき、host.docker.internal に置き換えます。
• lib/devbase/volume/compose.py: コンテナから host.docker.internal でホストへ届くための構成を加えました。
• docs/user/openbao-server.md と docs/user/openbao/: サーバの用意の文書、ポリシーの雛形、試用の構成を置きました。接続の文書は利用の形に揃えました。
• 確定仕様: サーバの前提を外しました。代わりに、サーバに求める条件とコンテナから見た接続先を書いています。
• docs/user/env-backend.md: コンテナの BAO_ADDR を置き換えない場合の、network_mode: host の dev サービスを書き足しました。
• 用語集の 6 語の出所を確定仕様に改め、CHANGELOG に OpenBao backend を、利用者が個人・チームで自分のサーバを立てて使う前提の文書と雛形に揃える #295 を書きました。

テスト

• 次のテストを加えました。
  • tests/commands/test_container_bao.py: コンテナの bao の接続先の置き換え
  • tests/volume/test_compose_host_gateway.py: ホストへの経路の構成
  • tests/docs/test_openbao_templates.py: ポリシーの雛形と試用の構成の形
• supervise.py の run のステップ:

ステップ	exit	結果
test-limited	0	範囲テスト 1 本（168.0 秒 / 戦略 local-full）が ok
design-tests	0	設計文書 1 件（issues/issue-295-design.md）。設計に名前の出るテストは 0 件
design-specs	0	変えたパス 19・シンボル 53 を含む既存の確定仕様と変更履歴 15 件を確認

設計と違う点

設計の箇所	違い	理由
決定 4（http の loopback の openbao.url はローカル扱いのときだけ BAO_ADDR を置き換え、host-gateway の行を足す）	ローカル扱いでも、dev サービスが network_mode: host のときは置き換えず extra_hosts も足さない（_apply_host_gateway）。決定 4 の本文はこの除外を書いていない	「未確認のまま残ること」の network_mode: host の項で、生成の側で判定できるか確かめるとしていた。host のネットワークでは loopback がそのまま届き、extra_hosts も使えないため除外した。確定仕様（secret-backend.md）・CHANGELOG・env-backend.md には書いてある

設計と違えたところ

設計	実装	理由
_bao_environment がコンテナから見た接続先を決め、extra_hosts の行も返す	_bao_environment() は今のまま openbao.url を返し、置き換えは新しい container_bao_address(url, remote=) と _host_gateway_kwargs が決める。置き換えた値は generate_scaled_compose(host_gateway_environment=…) で別に渡し、生成の側が dev のインスタンスへ BAO_ADDR の上書きと host-gateway の行をまとめて当てる	設計の「未確認のまま残ること」の network_mode: host を生成の側で判定するため。network_mode: host の dev サービスでは上書きも行も当てず、openbao.url のまま残す（loopback がそのまま届き、extra_hosts も使えない）。_bao_environment の形を変えないので、tests/commands/test_container_up_order.py の差し替え（lambda: {}）も触らずに済む
テスト設計 I10: 文書に --secret-id <値>・BAO_TOKEN=<値>・root token の値が無いことを pytest で見る	書いていない	この課題の指示が「.md の文言を照合するテストは書かない」としているため。レビューで見る
雛形の検査に「特定の組織の名前が無い」	pytest では見ていない	固有の語の検査（proper_term_check.py）の持ち場のため

手で確かめたこと（macOS の Docker Desktop・Docker 29.4.3 linux/arm64・OpenBao 2.6.2）

試用の構成（docs/user/openbao/compose.yml）で立てたサーバに、文書の管理の手順を上から打った。

• 受け入れ条件 4: 5 つの雛形がどれも bao policy write で通った（version: 2 は __GROUP__ を personal に置き換えて書き込んだ）

• 受け入れ条件 14: member01（personal の書き込みあり）・member02（読み取りだけ）の AppRole でログインして打った

  操作	結果
  member01 が users/member01/personal/global を書く・読む	200 / 200
  member01 が本人の未作成のパスを読む	404
  member02 が users/member01/personal/global を読む	403
  member02 が users/ 直下を一覧する	403
  member01 / member02 が team/personal/global へ書く	200 / 403
  member01 / member02 が team/personal/global を読む	200 / 200
  member02 が team/other/global を読む・member01 が書く	403 / 403
  version: 1: member02 が users/member01/global を読む	403
  version: 1: member01 / member02 が team/global へ書く	200 / 403
  version: 1: member01 / member02 が team/global を読む	200 / 200
  version: 1: member02 が team/projects/web へ書く	403
  member02 が sys/policy を読む	403

• チームの節の、entity の policies の書き換えで書き込みを許す・外す手順: 許した後のチーム共通への書き込みが 200、外した後が 403（発行済みの token にもすぐ効いた）。ロールと entity の削除も通った

• 受け入れ条件 13・8: この作業場所を DEVBASE_ROOT にし（age の鍵は作業用の別の置き場）、DEVBASE_ACCOUNT_GROUP=personal を宣言した作業用のプロジェクトで、secret_id を発行のコマンドから devbase env backend use openbao --url http://127.0.0.1:8200 --user member01 --role-id … --secret-id-stdin へパイプで渡して接続した。env backend test が 4 参照を読み、env set / env set --user → env get が書いた値を返し、devbase up のコンテナの環境変数に両方の値があった。生成した構成の dev-1 は BAO_ADDR=http://host.docker.internal:8200 と extra_hosts: [host.docker.internal:host-gateway] を持ち、コンテナの中の bao kv get -mount=devbase users/member01/personal/global が本人の値を読み、users/member02/… は permission denied だった

• 受け入れ条件 15: member02 に端末 2 台分（m2-laptop・m2-desktop）の secret_id を metadata 付きで発行し、文書の一覧の手順（accessor と secret-id-accessor/lookup）で m2-laptop を選んで secret-id-accessor/destroy した。m2-laptop の資格では devbase env backend test が「認証が拒まれました: HTTP 400」で終了コード 1、m2-desktop では 0

• 受け入れ条件 7: 文書の片付け（退避が無いとき）の手順を打ち、devbase env backend status が plaintext (設定なし) を指すことを確かめた

• 受け入れ条件 17: env -u DEVBASE_ROOT uv run --locked pytest tests/ -q が 4300 passed / 27 skipped。uvx ruff check --select=E9,F63,F7,F82 lib も通った

• grep -rn '社内メールアドレス\|運用側のリポジトリ' docs/user docs/specifications/secret-backend.md が 0 件

残した事項

• 受け入れ条件 18: この端末には固有の語の一覧（~/.config/devbase/proper-terms.txt）が無く、proper_term_check.py は「語の一覧が無いため飛ばした」で終わった。一覧のある端末で打つ必要がある
• Linux の Docker では確かめていない。ホストの 127.0.0.1 にだけ公開したポートへ host-gateway から届かない見込みで、文書と確定仕様に「確かめた環境は macOS の Docker Desktop」「Linux の Docker では確かめていない」と書いた
• 試用の devbase up は作業用のプロジェクトで打ったが、グループ personal のボリューム devbase_home_personal・共有の devbase_home_ubuntu・devbase_work_1 はこの端末に既にあり、作業用のコンテナはそれらを付けて起動した。自動スナップショットが作業場所の backups/ に作ったフル（約 3 GB）は消し、作業用のプロジェクト・secrets/・VS Code Server のボリューム・試用のサーバも片付けた
• 受け入れ条件 16 は、env-backend.md の接続の手順のコマンドと引数を変えていないことと、https の URL で生成した構成が今と同じこと（pytest）で見た。既存のサーバへの実際の接続は確かめていない

モード: standard / 通した工程: 実装 → 完了判定 → Pull Request

🤖 Generated with Claude Code