スプリント m8b

CHANGELOG.md

@@ -4,6 +4,15 @@
 
 ## [Unreleased]
 
+### Added
+- **自分で OpenBao サーバを立てて使うための文書とポリシーの雛形・試用の構成を足しました（#295）。**
+  [OpenBao サーバを用意する](docs/user/openbao-server.md)が、個人の形（自分で 1 台）・チームの形（チームで 1 台）・
+  既存のサーバの形（組織のサーバへ接続）の 3 つを分け、KV v2 のマウント・AppRole・ポリシー・entity と alias・
+  ロール・端末ごとの `secret_id` の発行と失効を `bao` のコマンドで示します。ポリシーの雛形（`version: 1` / `2`）と、
+  開発モードの OpenBao を手元に立てる試用の構成（`compose.yml`）は `docs/user/openbao/` にあります。
+  個人の形もアカウントグループごとの置き場（`version: 2`）を使い、プロジェクトで `DEVBASE_ACCOUNT_GROUP=personal` を
+  宣言します。接続のコマンドと引数、既存のサーバへの接続の手順は変わりません。
+
 ### Changed
 - **シェル補完（bash・zsh）が、`--context NAME` を受け付けるすべてのサブコマンドで `--context` を出すようにしました（#435）。**
   これまでは `open` と `project post-start` だけでした。`up`・`down`・`ps`・`login`・`scale`・`build`・`rebuild`、
@@ -22,6 +31,21 @@
   既存の世代はそのまま一覧・復元できます。
 
 ### Fixed
+- **接続先 URL が手元のサーバ（`http://127.0.0.1:8200` など `http` の loopback）のとき、`devbase up` したコンテナの中の
+  `bao` がサーバへ届くようにしました（#295）。** これまではコンテナへ渡す `BAO_ADDR` がそのまま `127.0.0.1` を指し、
+  コンテナ自身へつながっていました。Docker が手元の端末のものなら、コンテナの `BAO_ADDR` のホストを
+  `host.docker.internal` にし、dev コンテナへ `host.docker.internal:host-gateway` の行を足します。`https` の URL・
+  別の端末の Docker（`docker.context`）・`network_mode: host` の dev サービスでは今のままです。手元の devbase が使う
+  URL は変わりません。次の `devbase up` から効きます。確かめた環境は macOS の Docker Desktop です。
+- **既にある世代の名前で `devbase snapshot create --name <名前> --full` を打つと、その世代を今のボリュームの全体で
+  作り直すようにしました（#458）。** これまでは `full.tar.zst` を作り直せずに終了コード 1 で止まり、そのとき
+  `snapshot.snar` だけが進んでいました。作り直した世代は前のフルと差分を持たず、その世代から前の時点へは戻せません。
+  前の時点を残したいときは別の名前で作るか、先に `devbase snapshot copy` で写してください。控えに失敗したときは
+  世代が打つ前のまま残ります。入れ替えの途中で止まった世代は `restore` がボリュームを消す前に止まり、同じ名前で
+  もう一度 `--full` を打つと作り直せます。
+  **これまでに既存の世代の名前へ `--full` を打って失敗したことがあり、その後に同じ世代へ差分が積まれていれば、
+  その世代の差分は失敗の前の変更を欠いていることがあります。** 世代のファイルからは見分けられないため、
+  心当たりがあれば新しい世代を作ってください（`devbase snapshot create`）。
 - **プロジェクトの `env` に `DEV_SERVICE_NAME=` と空で書いたとき、開発サービス名を `dev` として扱うようにしました（#425）。**
   これまで `devbase build` は `dev` を建てる一方、`up`・`login`・`open`・`post-start`・`scale`・`--expires` の判定・
   token の配布は空の名前のサービスを探して開発サービスを見失っていました。未設定や空でない値のプロジェクトは変わりません。

docs/README.md

@@ -49,6 +49,7 @@ graph TD
 | [環境変数ガイド](user/environment-variables.md) | 3レベル構造、コレクター、ソース同期 |
 | [環境変数の暗号化](user/env-encryption.md) | 認証情報を暗号化して保存する / 鍵とチーム共有 / 平文へ戻す |
 | [機密の保存先を選ぶ](user/env-backend.md) | OpenBao サーバへ載せ替える / 個人単位の機密 / 不達時のキャッシュ |
+| [OpenBao サーバを用意する](user/openbao-server.md) | 個人・チーム・既存のサーバの 3 つの形 / ポリシーの雛形 / 試用の構成 |
 | [コンテナ操作ガイド](user/container-operations.md) | ライフサイクル、並行開発、ボリューム構造 |
 | [スナップショットガイド](user/snapshot-guide.md) | 増分バックアップ、世代管理、復元手順 |
 | [トラブルシューティング](user/troubleshooting.md) | カテゴリ別の問題と解決策 |
@@ -108,6 +109,8 @@ docs/
 │   ├── environment-variables.md       ← 環境変数ガイド
 │   ├── env-encryption.md              ← 環境変数の暗号化
 │   ├── env-backend.md                 ← 機密の保存先を選ぶ (OpenBao)
+│   ├── openbao-server.md              ← OpenBao サーバを用意する
+│   ├── openbao/                       ← ポリシーの雛形と試用の構成 (compose.yml)
 │   ├── container-operations.md        ← コンテナ操作ガイド
 │   ├── snapshot-guide.md              ← スナップショットガイド
 │   └── troubleshooting.md             ← トラブルシューティング
@@ -134,6 +137,7 @@ docs/
 | 環境変数を設定する | [環境変数ガイド](user/environment-variables.md#環境変数の操作) |
 | 認証情報を暗号化して保存する | [環境変数の暗号化](user/env-encryption.md) |
 | 機密を OpenBao サーバで管理する | [機密の保存先を選ぶ](user/env-backend.md) |
+| 自分の OpenBao サーバを立てる | [OpenBao サーバを用意する](user/openbao-server.md) |
 | 複数コンテナで並行開発する | [コンテナ操作ガイド](user/container-operations.md#並行開発) |
 | 1 つのコンテナで複数リポジトリを扱う | [project.yml リファレンス](user/project-yml.md#複数リポジトリ) |
 | データをバックアップ・復元する | [スナップショットガイド](user/snapshot-guide.md) |

docs/glossary.md

@@ -94,12 +94,12 @@ up の後に VS Code で dev コンテナを開く（docs/specifications/editor-
 | region の出所 | — | 参照の AWS_DEFAULT_REGION へ書く値をどこから得たか。参照に既にある・ホストの region・利用者の入力・既定の値（ap-northeast-1）の 4 つ | — | — | `docs/specifications/secret-backend.md` |
 | 鍵の確認の結果 | — | AWS の方法 3 で、ホストの [default] の鍵を取り込むかを決めた結果。受け入れた・断った・確認しなかった（ホストに鍵が無い）の 3 つ。方針が import なら受け入れた。skip ならホストに鍵があれば断った、無ければ確認しなかったになる | — | — | `docs/specifications/secret-backend.md` |
 | 鍵ファイルの発見 | — | ~/gcp-credentials/ の *.json を読み、正規化したプロファイル名から鍵ファイルへの対応を作ること。出力を持たない | — | — | `docs/specifications/secret-backend.md` |
-| 利用の形 | — | OpenBao サーバの持ち方の 3 つの区分。個人の形（1 人で 1 台）・チームの形（チームで 1 台、チーム共通と個人の置き場を分ける）・既存のサーバの形（組織が運用するサーバへ接続する） | — | — | — |
-| ポリシーの雛形 | — | devbase が前提にする権限を OpenBao のポリシー（HCL）として書いた、docs/user/openbao/policies/ のファイル。管理する人が自分のサーバへ書き込んで使う | — | — | — |
-| 試用の構成 | — | docs/user/openbao/compose.yml で開発モードの OpenBao を手元に立て、devbase の接続を試して片付けるまでの最小の構成 | — | — | — |
-| 利用者の識別子 | — | secrets/backend.yml の openbao.user。サーバの entity 名と同じ値にし、個人単位の置き場のパスに使う | — | — | — |
-| コンテナから見た接続先 | — | dev コンテナへ BAO_ADDR として渡す OpenBao の接続先。openbao.url が http の loopback でローカル扱いのときはホストを host.docker.internal に置き換えた値、それ以外（https を含む）は openbao.url のまま | — | — | — |
-| 管理する人 | — | 利用者の OpenBao サーバで、マウント・AppRole・ポリシー・entity を作る人。個人の形では利用者本人 | — | — | — |
+| 利用の形 | — | OpenBao サーバの持ち方の 3 つの区分。個人の形（1 人で 1 台）・チームの形（チームで 1 台、チーム共通と個人の置き場を分ける）・既存のサーバの形（組織が運用するサーバへ接続する） | — | — | `docs/specifications/secret-backend.md` |
+| ポリシーの雛形 | — | devbase が前提にする権限を OpenBao のポリシー（HCL）として書いた、docs/user/openbao/policies/ のファイル。管理する人が自分のサーバへ書き込んで使う | — | — | `docs/specifications/secret-backend.md` |
+| 試用の構成 | — | docs/user/openbao/compose.yml で開発モードの OpenBao を手元に立て、devbase の接続を試して片付けるまでの最小の構成 | — | — | `docs/specifications/secret-backend.md` |
+| 利用者の識別子 | — | secrets/backend.yml の openbao.user。サーバの entity 名と同じ値にし、個人単位の置き場のパスに使う | — | — | `docs/specifications/secret-backend.md` |
+| コンテナから見た接続先 | — | dev コンテナへ BAO_ADDR として渡す OpenBao の接続先。openbao.url が http の loopback でローカル扱いのときはホストを host.docker.internal に置き換えた値、それ以外（https を含む）は openbao.url のまま | — | — | `docs/specifications/secret-backend.md` |
+| 管理する人 | — | 利用者の OpenBao サーバで、マウント・AppRole・ポリシー・entity を作る人。個人の形では利用者本人 | — | — | `docs/specifications/secret-backend.md` |
 
 ## スナップショット（`snapshot`）
 

docs/glossary/glossary.json

@@ -959,43 +959,37 @@
       "term": "利用の形",
       "context": "secret",
       "meaning": "OpenBao サーバの持ち方の 3 つの区分。個人の形（1 人で 1 台）・チームの形（チームで 1 台、チーム共通と個人の置き場を分ける）・既存のサーバの形（組織が運用するサーバへ接続する）",
-      "source": "",
-      "pending_source": "issues/issue-295-design.md"
+      "source": "docs/specifications/secret-backend.md"
     },
     {
       "term": "ポリシーの雛形",
       "context": "secret",
       "meaning": "devbase が前提にする権限を OpenBao のポリシー（HCL）として書いた、docs/user/openbao/policies/ のファイル。管理する人が自分のサーバへ書き込んで使う",
-      "source": "",
-      "pending_source": "issues/issue-295-design.md"
+      "source": "docs/specifications/secret-backend.md"
     },
     {
       "term": "試用の構成",
       "context": "secret",
       "meaning": "docs/user/openbao/compose.yml で開発モードの OpenBao を手元に立て、devbase の接続を試して片付けるまでの最小の構成",
-      "source": "",
-      "pending_source": "issues/issue-295-design.md"
+      "source": "docs/specifications/secret-backend.md"
     },
     {
       "term": "利用者の識別子",
       "context": "secret",
       "meaning": "secrets/backend.yml の openbao.user。サーバの entity 名と同じ値にし、個人単位の置き場のパスに使う",
-      "source": "",
-      "pending_source": "issues/issue-295-design.md"
+      "source": "docs/specifications/secret-backend.md"
     },
     {
       "term": "コンテナから見た接続先",
       "context": "secret",
       "meaning": "dev コンテナへ BAO_ADDR として渡す OpenBao の接続先。openbao.url が http の loopback でローカル扱いのときはホストを host.docker.internal に置き換えた値、それ以外（https を含む）は openbao.url のまま",
-      "source": "",
-      "pending_source": "issues/issue-295-design.md"
+      "source": "docs/specifications/secret-backend.md"
     },
     {
       "term": "管理する人",
       "context": "secret",
       "meaning": "利用者の OpenBao サーバで、マウント・AppRole・ポリシー・entity を作る人。個人の形では利用者本人",
-      "source": "",
-      "pending_source": "issues/issue-295-design.md"
+      "source": "docs/specifications/secret-backend.md"
     }
   ]
 }

docs/specifications/cli-argument-resolution.md

@@ -121,13 +121,14 @@ graph TD
 | 走査 | `_create_parser()` の木を入れ子の parser まで辿る。別名のグループ（`ct`）は `cli.GROUP_ALIASES` で正式の名前に直して数える |
 | `[name]` の集合 | 位置引数 `name` を持つ parser のうち、トップレベルと `project` グループ（入れ子の `profile` を含む）の道。`plugin` / `snapshot` / `env backend use` の `name` は含めない |
 | `--context` の集合 | `--context` を持つすべての parser の道に、トップレベルの `build`（ラッパーだけが受け付ける）を名指しで足したもの |
+| `--context` を取らない末端の道 | 子の parser を持たない parser の道から `--context` の集合を引いたもの。補完の `--context` の余分を比べる道で、親の道（`project profile` など）は含めない。親の道の zsh の分岐は子の分岐を含み、子の `--context` を拾うため |
 | 走査の健全性 | どちらの集合も空でなく、入れ子の道（3 語）を含み、`[name]` の集合が `plugin` / `snapshot` / `env` の道を含まない |
 
 | 写し | 比べ方 |
 | --- | --- |
 | `bin/devbase` の `_PROJECT_NAME_SUBCOMMANDS` | `project` の直下で `[name]` を取る parser の名前の集合に等しい |
 | `bin/devbase` の `_NAME_RESOLVABLE_SHORTCUTS` | `cli.SHORTCUTS` のキーと `build` の和に等しい。あわせて、トップレベルで `[name]` を取る parser がすべて `cli.SHORTCUTS` にあること |
-| `etc/devbase-completion.bash` | 一時ディレクトリの `projects/` を `DEVBASE_ROOT` にして補完を実行し、`[name]` の集合から補完の例外を引いたすべての道の名前の位置でプロジェクト名が候補に出る。`--context` の集合のすべての道（`container` の道は `ct` で始めても）で `devbase <道> -` の候補に `--context` が出る。`[name]` の集合から補完の例外を引いた道では、`devbase <道> web -` の候補にも `--context` が出る。`project` / `container` の直下で `[name]` か `--context` を取るサブコマンド（入れ子は親の `profile` として数える）が、そのグループのサブコマンドの候補に含まれる |
+| `etc/devbase-completion.bash` | 一時ディレクトリの `projects/` を `DEVBASE_ROOT` にして補完を実行し、`[name]` の集合から補完の例外を引いたすべての道の名前の位置でプロジェクト名が候補に出る。`--context` の集合のすべての道（`container` の道は `ct` で始めても）で `devbase <道> -` の候補に `--context` が出る。`[name]` の集合から補完の例外を引いた道では、`devbase <道> web -` の候補にも `--context` が出る。`--context` を取らない末端の道では、`devbase <道> -` の候補に `--context` が出ない。`project` / `container` の直下で `[name]` か `--context` を取るサブコマンド（入れ子は親の `profile` として数える）が、そのグループのサブコマンドの候補に含まれる |
 | `etc/_devbase` | zsh を起動せず内容を読む。`case "$words[2]"` から字下げの深さで道の分岐（`up\|down)` のような `\|` 区切りの見出し）を辿り、`[name]` の集合から補完の例外を引いた道の本体に `_devbase_project_names` がある。`--context` の集合のすべての道の本体に、値の補完を持たない `'--context[...]:context:'`（`:context:` の後ろに補完の関数を置かない形）がある。`project_subcommands` / `container_subcommands` の一覧に bash と同じサブコマンドが含まれる |
 | この節の 2 つの表 | 見出し `` #### `[name]` を受け付けるサブコマンド `` と `` #### `--context` を受け付けるサブコマンド `` の直後の表を読む。1 列目は `devbase <グループ...> <sub>` の形で、間の語が道の頭になる。2 列目にバッククォートで並べた語を `<sub>` に入れる。表は `[name]` の集合・`--context` の集合にそれぞれ等しい |
 
@@ -139,13 +140,14 @@ graph TD
 `tests/cli/test_completion.py` が `--context` の直後の候補が 0 件であることを代表の道で確かめる。
 
 一致テストは zsh の補完を内容で読む。zsh が実際に出す候補そのものは、補完の実行テストが見る
-（[zsh の補完の実行テスト](#zsh-の補完の実行テスト)）。
+（[zsh の補完の実行テスト](#zsh-の補完の実行テスト)）。zsh の `--context` の余分（取らない道で出す）は、
+分岐の文字列でなく実行テストの候補で比べる（X1）。
 
 #### 補完が `--context` を出す位置
 
 | 位置 | 例 | bash | zsh |
 | --- | --- | --- | --- |
-| (a) 道の直後 | `devbase up -`・`devbase env exec -`・`devbase ct profile up -` | `--context` の集合のすべての道で出す | `--context` の集合のすべての道の分岐で出す |
+| (a) 道の直後 | `devbase up -`・`devbase env exec -`・`devbase ct profile up -` | `--context` の集合のすべての道で出し、`--context` を取らない末端の道では出さない | 同じ（`--context` の集合のすべての道の分岐で出し、取らない末端の道では出さない） |
 | (b) プロジェクト名の直後 | `devbase up web -`・`devbase project open web -` | `[name]` の集合から補完の例外を引いた道で出す | `_arguments` が位置を問わず出す |
 | (c) `--context` の直後（値） | `devbase up --context <TAB>` | 候補は 0 件 | 説明だけを出し、候補は 0 件 |
 | (a)・(b) より後ろ | `devbase scale web 3 -`・`devbase env exec -- ls -` | 出すことを求めない | 出し得る（argparse では、`env exec` のコマンドの後の `--context` はそのコマンドへ渡る） |
@@ -179,6 +181,7 @@ zsh（`etc/_devbase`）は、サブコマンドの分岐から `_arguments` を
 | I3 | `--context` の集合のすべての道（`container` の道は `ct` で始めても）の `devbase <道> -` | 候補に `--context` が入る |
 | I4 | `[name]` の集合から補完の例外を引いた道のうち `--context` の集合にもある道の `devbase <道> proj-a -` | 候補に `--context` が入る |
 | I5 | `--context` の集合のすべての道（`ct` で始めても）の `devbase <道> --context ` | 候補が 0 件 |
+| X1 | `--context` を取らない末端の道の `devbase <道> -` | 候補に `--context` が入らない |
 
 | 項目 | 規則 |
 | --- | --- |