配備の鍵を扱う
配備のすべてを守る 2 つの鍵、AF_MASTER_KEY と AF_COOKIE_SECRET の要件と、変えたときに何が起きるかがわかります。
鍵なしで動かしてきた配備に鍵を入れる手順と、鍵の前に保存された値を封じる手順も扱います。KMS で鍵を守る方法とホームごとの鍵は 保存時の鍵を AWS KMS にする にあります。
| あなたがやること | Agent Fleet がやること |
|---|---|
| 2 つの鍵をランダムに生成して設定する | 起動のときに長さを確かめ、足りなければ起動を止める |
| 鍵のない配備に、後から鍵を入れる | 以後の値を封じる。鍵の前の値は残っている間、警告を出し続ける |
af-cp rewrap-keys --seal-plaintext で古い値を封じる |
1 行ずつ封じ、開き直して照らし合わせてから書く |
どちらも、選んだ値の強さが上限になります。
AF_MASTER_KEY |
AF_COOKIE_SECRET |
|
|---|---|---|
| 守るもの | 封じたすべての値（クライアントシークレット、MCP のヘッダー、ハンドオフ、受信箱）の根、メンバーごとの認証情報のストアの鍵、ワークスペースが Control Plane を呼び返すトークン | セッション・サインインの state・プレビューの各 cookie の署名 |
| 要件 | ランダムな 32 バイト以上（hex か base64。そのままの文字列なら 43 文字以上）。パスフレーズは使えません | 同じ |
| 作り方 | head -c 32 /dev/urandom | base64 |
head -c 32 /dev/urandom | base64 |
| 変えたときの代償 | 動いている配備では変えないでください。 古い値で封じたものがすべて開かなくなり、鍵を付け替えるコマンドはありません | 全員が一度サインインし直します（全員のセッションを今すぐ切る） |
作る手順と保管は インストールする にあります。
起動のときの検査
Section titled “起動のときの検査”- 測るのは長さだけです（数種類のバイトの繰り返しも弾きます）。長いパスフレーズとランダムなバイト列は見分けられないので、値は必ず生成してください
AUTH=dev以外では、検査に通らない値だと Control Plane は起動のときに止まり、変数の名前（AF_MASTER_KEY・AF_COOKIE_SECRET、またはその両方）を示します- 検査は値をログに出しません
- ECS の
standup.shも、保存したパラメータを同じ基準で調べ、OK か too short だけを示します
起動を拒む版に上げる前に
Section titled “起動を拒む版に上げる前に”今の値を確かめ、短いものは先に入れ替えます。
AF_COOKIE_SECRETが短いときは簡単です。新しく作って設定し、再起動します。全員が一度サインインし直しますAF_MASTER_KEYが短いときは、そうはいきません。その値で封じたものが開かなくなり、付け替えるコマンドもありません。アップグレードの前に、生成した鍵への移行（メンバーが保存した認証情報のつなぎ直しを含む）を計画してください。古い値のままでは Control Plane は起動しません
鍵のない配備に鍵を入れる
Section titled “鍵のない配備に鍵を入れる”AF_MASTER_KEY がないと、メンバーが保存した認証情報は、各ホームに暗号化されずに置かれます。これは AUTH=dev のための動きです。
ほかの AUTH でも Control Plane は起動しますが、起動時にログへ WARNING を出し、管理画面に警告の帯を出します。
後から鍵を入れるのは透過ではないので、メンバーと段取りしてこの順で進めます。
- 鍵を設定して、Control Plane を再起動します
- 今あるワークスペースをすべて停止してから、起動し直します。 動き続けているものは鍵を持たず、平文で書き続けます
- メンバーに、保存していた認証情報をつなぎ直してもらいます
- 暗号化されていない古いファイル（各ホームの
~/.config/agent-fleet/secrets.json）を消し、そこにあった認証情報をローテーションします。このファイルはバックアップにも入っています
鍵の前に保存された値を封じる
Section titled “鍵の前に保存された値を封じる”AF_MASTER_KEY のない Control Plane は、一部の値を暗号化せずに保存しました。後から鍵を設定しても、それらは封じられず、そのまま読まれます。
- 対象: テナントのサインインと Git OAuth のクライアントシークレット、MCP のヘッダーとクライアントシークレット、エンジンのトークン、ハンドオフ、共有の提案、受信箱のメッセージ
- 残っている間は、起動時にログへ
WARNINGを出し、管理画面に警告の帯を出します（plaintext_sealed）
管理者が編集していないときに、Control Plane と同じ設定・データベースで実行します。
af-cp rewrap-keys --seal-plaintext --dry-run # 数えるだけで、何も変えないaf-cp rewrap-keys --seal-plaintext- ローカルの鍵でも
AF_KEY_CUSTODIAN=kmsでも動き、設定されているほうで封じます - 1 行ずつ封じ、封じた値を開き直して照らし合わせてから書きます。最後の読み取りだけの確認で残りがないときだけ、終了コード 0 で終わります
- 警告の帯は数分以内（か次の再起動）で消えます
- KMS も使うときは、続けて 保存時の鍵を AWS KMS にする の
af-cp rewrap-keysを行います
これらの値は、データベースとバックアップから読める状態でした。発行元でもローテーションしてください（IdP と Git OAuth のクライアントシークレット、MCP のトークン、Hugging Face・Civitai・ComfyUI のトークン）。要らないバックアップは消します。
cookie の鍵を用途ごとに分ける
Section titled “cookie の鍵を用途ごとに分ける”Control Plane は、セッション・サインインの state・プレビューの各 cookie を、用途ごとに別の鍵で署名します。ある用途の cookie は、ほかの用途では通りません。これが既定です。 0.42.0 より前のレプリカは新しい形式を読めないので、この順で上げます。
- まず、すべてのレプリカを 0.42.0 以降にします。 両方の形式を読めます
- そのあとで、用途ごとの鍵を発行する版に上げます。古い形式も、起動ごとにセッション 1 回分の期間（
AF_SESSION_TTL、既定 7 日）は受け付けるので、ローリング更新や再起動でも誰もサインアウトされません
- サインインの state とプレビューのトークンは数分で切れます。その期間は、古い形式は用途で分かれていません
- もう 1 版だけ前の形式で発行したいときは、
AF_COOKIE_PURPOSE_KEYS=0を設定します（ECS では ingress スタックのパラメータCookiePurposeKeysを0にして更新します）。この退避の設定は、古い形式とともに後の版でなくなります - 新しい形式を発行したあとで 0.42.0 より前の版に戻したときだけ、全員がサインアウトされます
- 同じ更新で
AF_SESSION_TTLを短くしないでください。古い形式を受け付ける期間も短くなります
- インストールする：鍵を作って保管する
- 保存時の鍵を AWS KMS にする：KMS で鍵を守る、ホームごとの鍵
- バックアップして復元する：復元には同じ
AF_MASTER_KEYが要る - 脅威モデルと残るリスクを知る
エージェント向け
この指示をエージェントに送ると、このページを読ませられます。
https://agent-fleet.org/docs/ja/operate/secure/deployment-keys/index.md を読んで