Deployment Management

参照元: LiveKit Agents Documentation ロードマップ: 学習ロードマップ

What（何についてか）

Agentを一度デプロイした後の継続的なバージョン管理。設定ファイルの構造、新バージョンのデプロイ戦略、ロールバック手法、コールドスタートの挙動を扱う。

Why（なぜ必要か）

Agentは開発中にコードが変わり続ける。本番環境でダウンタイムなく安全にバージョンを切り替える仕組みがなければ、ユーザー体験を損なうリスクがある。LiveKit Cloudはローリングデプロイとヘルスチェックでこの問題を解決する。

How（どう動くか）

Configuration（livekit.toml）

デプロイ設定の中核ファイル。CLIはカレントディレクトリのこのファイルを自動的に検索する。

[project]
subdomain = "<my-project-subdomain>"
 
[agent]
id = "<agent-id>"

• project.subdomain でCloud projectを特定
• agent.id でデプロイ対象のAgentを識別
• lk agent config で再生成可能

Deploying new versions（ローリングデプロイ）

lk agent deploy で新バージョンを本番に反映。ローリングデプロイ戦略によりダウンタイムなしで切り替わる。

graph TD
    A["lk agent deploy"] --> B["Build: コードアップロード + コンテナイメージビルド"]
    B --> C["Deploy: 新インスタンスを既存と並行起動"]
    C --> D["Route: 新インスタンスがhealthyになったら新セッションをそちらへルーティング"]
    D --> E["Graceful shutdown: 旧インスタンスは新セッション受付停止、既存セッションは最大1時間維持"]
    E --> F["Autoscale: 需要に応じて新インスタンスを自動増減"]

Graceful shutdownの設計が重要。旧インスタンスは新規セッションの受け付けを停止するが、既に確立しているセッションは最大1時間まで完了できる。これによりユーザー側から切断を感じさせない。

Health checks

新インスタンスが正常に動作するまで、旧インスタンスにトラフィックを流し続ける安全装置。

• 新Agentのhealth check endpointが通るまでは旧インスタンスがトラフィックを処理
• タイムアウトは5分
• prewarm 関数が5分以上かかるとヘルスチェックが通らず、旧インスタンスが残り続ける

この仕組みにより、新バージョンに問題があっても本番への影響を防げる。

Rolling back

lk agent rollback で再ビルドなしに前バージョンに即座に戻せる。前バージョンのコンテナイメージがCloud側に保持されているため、ビルド不要で即座にデプロイ可能。デプロイと同じローリング方式で切り替わる。

注意：有料プラン限定機能。Free planではコードを手動で戻して lk agent deploy し直す必要がある。

Cold start

特定プランではAgentをゼロレプリカまでスケールダウン可能。新ユーザー接続時にインスタンスを起動するが、通常より接続に時間がかかる。詳細はQuotas and limitsページを参照。

Key Concepts

用語	説明
livekit.toml	デプロイ設定ファイル（project subdomain + agent id）
lk agent deploy	ローリングデプロイで新バージョンを反映
lk agent rollback	再ビルドなしで前バージョンに即座に戻す（有料プラン限定）
Graceful shutdown	旧インスタンスが既存セッションを最大1時間維持する仕組み
Health check	新インスタンスが正常起動するまで旧インスタンスを保持（5分タイムアウト）
Cold start	ゼロレプリカからのインスタンス起動（接続遅延あり）

一言まとめ

LiveKit Cloudのデプロイ管理は lk agent deploy によるローリングデプロイが中心。Graceful shutdownで既存セッションを保護し、Health checkで新バージョンの安全性を担保する。問題があれば lk agent rollback で即座に前バージョンに戻せる。