最初の owner と利用者 key の発行

作業内容見出しのリンクをコピー

最初の owner と workspace を作成し、利用者ごとに API key を発行します。API key の廃止とセッション実行権限の取り消しを区別します。

準備見出しのリンクをコピー

設置とアクセス経路の準備が必要です。bootstrap トークンとログは運用者だけが読み取ります。Kubernetes では複数 replica に同じ BOOTSTRAP_TOKEN を渡すよう Secret と catalogEnv を構成します。

手順見出しのリンクをコピー

1. 最初の owner の作成見出しのリンクをコピー

ブラウザの /bootstrap に固定した BOOTSTRAP_TOKEN、owner 情報、workspace 名を入力します。トークン未設定の test-ops 単一 API 環境では、scripts/test-ops.sh bootstrap-token が自動生成されたトークンを一度だけ出力します。再実行しても出力されず、コンテナログは読みません。それ以外の単一 API 構成（scripts/local.sh など）では API の起動ログ（docker logs <this-installation-api-container-id>）に出力されます。既定 replica が 2 の Kubernetes では自動生成に頼らず、Secret の固定トークンを使います。最初の owner 作成後に同じトークンを再利用すると 409 BOOTSTRAP_DONE です。/login でログインします。

2. 利用者ごとの key 発行見出しのリンクをコピー

KEY="$(scripts/test-ops.sh key create <owner_id> \
  --scopes sessions:read,sessions:write,sessions:approve,sessions:control,sessions:recover)"

<owner_id> は、この key のセッションをまとめる名前です。利用者ごとに異なる値を決めます。Web コンソールのアカウントとは別であり、workspace id は使いません。

SDK と HTTP API はこのサーバーアドレスと key で接続します（SDK のインストール）。

Kubernetes では次を使います。

先に設置環境の context・namespace・fullname の確認に従います。次の werft はその設置例の名前です。

kubectl -n werft exec deploy/werft-api -c api -- \
  bun run apps/control-host/src/api/keys.ts create <owner_id> \
  --scopes sessions:read,sessions:write,sessions:approve,sessions:control,sessions:recover

stdout には平文 key が一度だけ、stderr には key id が出力されます。平文は公開ログに保存せず、対象の利用者へ安全に渡します。利用者ごとの key 所有者識別子と Web コンソールのアカウントは別です。API key の scope は作業に必要な範囲に絞ります。

3. 廃止時の連絡と実行権限見出しのリンクをコピー

key を廃止する際の連絡先を利用者に案内します。checkout の運用者 CLI は次のとおりです。

scripts/test-ops.sh key revoke <key_id>
API_CONTAINER='<api-container-id-from-this-installation>'
docker exec "$API_CONTAINER" bun run apps/control-host/src/api/grants.ts revoke <session_id> --reason <text>
docker exec "$API_CONTAINER" bun run apps/control-host/src/api/grants.ts restore <session_id> --reason <text>

API_CONTAINER は、この環境の status と Docker project label で確認した API コンテナ id に置き換えます。Kubernetes では設置バージョンのリポジトリ checkout とホストの Bun・kubectl を準備し、keys:k8s と grants:k8s を使います。NAMESPACE と RELEASE の既定値はいずれも werft です。

確認見出しのリンクをコピー

各利用者の key で /v1/sessions を読むと許可範囲の応答が返り、key なしなら 401 になる必要があります。廃止した key は認証されないことを確認します。grants 出力の receipt と execution 状態を確認し、受理と実際の終了を区別します。

よくある問題見出しのリンクをコピー

replica ごとに自動生成した bootstrap トークンが異なると、別の Pod に届いた要求が 401 になる場合があります。固定トークンを全 Pod に渡します。Secret に名前が欠けていると Pod は起動しません。CLI の owner id に workspace id を指定しないでください。

元に戻す見出しのリンクをコピー

作成済みの最初の owner を削除する目的で環境を reset しないでください。誤って発行した key を revoke し、正しい scope で新しい key を作成します。grants restore は以前の実行が消えた後だけ行います。

次に読む見出しのリンクをコピー

モデル接続、SDK のインストール。