Secrets Management
参照元: LiveKit Agents Documentation ロードマップ: 学習ロードマップ
What（何についてか）
Agentが使用する機密情報（API key、DB credentials、auth token等）の管理。LiveKit Cloudが暗号化して保存し、ランタイム時にコンテナに安全に注入する。
Why（なぜ必要か）
Agentは外部サービス（LLM provider、DB等）と通信するためにAPI key等の機密情報を必要とする。これらをソースコードやGitに含めることはセキュリティリスクになる。LiveKit Cloudは書き込み専用の暗号化ストアを提供し、ランタイム時のみ平文としてAgentに提供する。
How（どう動くか）
Secretの基本モデル
Secretは暗号化されてCloud側に保存され、Agentコンテナ起動時に環境変数として注入される。値はCLIやDashboardから取り出せない（書き込み専用）。これにより誤って値が漏洩するリスクを排除している。
設定方法
3つのパターンがある。
1. Secrets file（ファイルからの読み込み）
CLIは引数なしの場合、自動的に .env / .env.local / .env.production を探す。明示指定も可能：
lk agent create --secrets-file=path/to/secrets.env
ファイルは KEY=value 形式で1行に1つ。LiveKit Cloud credentials（LIVEKIT_URL 等）は除外される。
2. Secrets flag（個別指定）
lk agent update-secrets --secrets "SECRET_A=foo" --secrets "SECRET_B=bar"
複数なら --secrets フラグを複数渡す。デフォルトは「既存を保持しつつ追加・更新」。
3. 上書きモード
全入れ替えの場合：
lk agent update-secrets --secrets-file=new-secrets.env --overwrite
--overwrite で既存secretを全削除してから新しいものを設定。
Secret更新時の挙動
Secretの更新は rolling restart をトリガーする。新しいセッションから更新されたsecretが使われる。既存セッションは旧インスタンスで継続（Deployment ManagementのGraceful shutdownと同じ仕組み）。
一覧確認
lk agent secrets で名前・作成日・更新日を表示。値は表示されない。
LiveKit Cloud自動提供
LiveKit Cloudは以下の環境変数を自動的にAgentに注入する。ユーザーが設定・変更する必要はない。
LIVEKIT_URL— Cloud server URLLIVEKIT_API_KEY— projectのAPI keyLIVEKIT_API_SECRET— projectのAPI secret
File-mounted secrets
環境変数ではなくファイルとしてマウントする仕組み。GoogleのJSON認証ファイル等で必要。
lk agent update-secrets --secret-mount ./google-application-credentials.json
コンテナ内に /etc/secrets/<filename> としてマウントされる。
Key Concepts
| 用語 | 説明 |
|---|---|
| Secret | 暗号化された環境変数。ランタイム時にコンテナに注入 |
--secrets-file | .envファイルからsecretを読み込む |
--secrets | 個別にsecretを指定（複数可） |
--overwrite | 既存secretを全削除してから新しいものを設定 |
--secret-mount | ファイルを /etc/secrets/ にマウント |
| Rolling restart | Secret更新時にトリガー。新セッションから新secretが有効 |
制約事項
- Secret name: 英字・数字・アンダースコアのみ、最大70文字、大文字小文字区別あり
- Secret value: 最大16KB、暗号化保存、取り出し不可
- LiveKit credentials: 自動注入、ユーザー設定不可
一言まとめ
LiveKit CloudのSecret管理は書き込み専用の暗号化ストア。.env ファイル、--secrets フラグ、--secret-mount の3パターンで設定可能。値はCLI/Dashboardから取り出せず、ランタイム時のみ環境変数として提供される。更新時はrolling restartで安全に反映。