エージェントコンテナインストールマニュアル¶

このドキュメントでは、Docker および Kubernetes を使用して obs-agent をインストールする方法を説明します。Kubernetes にインストールする場合は Helm を推奨します。

コンテナは起動時に BEAK_WS_URL、AGENT_ID、AGENT_API_KEY を使用して Beak からランタイム設定を読み込み、エージェントを起動します。

永続ストレージはランタイムの前提条件です。 /app はアクティブなセッション/タスクの JSONL 履歴および関連データを保存し、他の 2 つのディレクトリはプロファイルおよび Owl のデータを保存します。Docker、Kubernetes YAML、Helm のいずれのデプロイでも、/app、/var/lib/obs-agent/profile-cache、/app/.owl に永続ストレージを提供する必要があります。Owl ボリュームは /app/.owl に個別にマウントしてください。そうしないと、コンテナまたは Pod の再構築やアップグレード後に、アクティブなセッション/タスクを継続できなくなる可能性があります。

コンテナノードが Beak、LLM、その他の公開サービスに直接アクセスできない場合は、まず obs-agent のフォワードプロキシを設定する を参照してください。

接続情報の準備¶

Beak コンソールまたはインストールページから、以下の 3 つの値をコピーします。

export BEAK_WS_URL='https://agent-api.guance.com'
export AGENT_ID='replace-with-agent-uuid'
export AGENT_API_KEY='replace-with-agent-api-key'

イメージアドレスを準備します。

export OBS_AGENT_IMAGE='pubrepo.guance.com/guance/obs-agent:v0.5.0'

Docker でインストールする¶

Docker デプロイでは、以下に示す 3 つの名前付きボリュームを作成して再マウントする必要があります。アップグレードや再起動の際は同じボリューム名を再利用し、コンテナの一時ディレクトリで置き換えないでください。コンテナとは独立して管理されるバインドマウントもサポートされています。

env ファイルを作成します。

cat > obs-agent.env <<EOF
BEAK_WS_URL=${BEAK_WS_URL}
AGENT_ID=${AGENT_ID}
AGENT_API_KEY=${AGENT_API_KEY}
EOF

コンテナを起動します。

docker run -d \
  --name obs-agent \
  --restart unless-stopped \
  --env-file ./obs-agent.env \
  -v obs-agent-work:/app \
  -v obs-agent-profile-cache:/var/lib/obs-agent/profile-cache \
  -v obs-agent-owl:/app/.owl \
  "${OBS_AGENT_IMAGE}"

ステータスを確認します。

docker ps --filter name=obs-agent
docker logs -f obs-agent

以下のログ行は、起動が成功したことを示します。

obs-agent profile request loaded
obs-agent websocket connected

イメージをアップグレードします。

OBS_AGENT_IMAGE="${OBS_AGENT_IMAGE%:*}:v0.5.0"
docker pull "${OBS_AGENT_IMAGE}"
docker rm -f obs-agent
docker run -d \
  --name obs-agent \
  --restart unless-stopped \
  --env-file ./obs-agent.env \
  -v obs-agent-work:/app \
  -v obs-agent-profile-cache:/var/lib/obs-agent/profile-cache \
  -v obs-agent-owl:/app/.owl \
  "${OBS_AGENT_IMAGE}"

Docker インストールを削除します。

以下の docker volume rm コマンドは、セッション/タスク履歴および関連データを完全に削除します。復元または継続が必要なタスクがないことを確認してから実行してください。

docker rm -f obs-agent
docker volume rm obs-agent-work obs-agent-profile-cache obs-agent-owl

Kubernetes YAML でインストールする¶

Helm を使用しない場合は、OSS に公開されているベースマニフェストを直接使用できます。

ベースマニフェストは 3 つの PVC（20 GiB、5 GiB、5 GiB）を作成してマウントします。インストール前に、クラスターには動的プロビジョニング用のデフォルト StorageClass、または PVC がバインドできる事前作成済みの PV が必要です。PVC がバインドされていない間、Pod は Pending のままになります。Pod の再構築やアップグレードによってアクティブなセッション/タスクの JSONL 履歴および関連データが失われるため、emptyDir で置き換えないでください。

マニフェストをダウンロードします。

curl -fsSL https://static.guance.com/obs-agent/obs-agent.yml -o obs-agent.yml

特定バージョンのマニフェストをダウンロードします。

curl -fsSL https://static.guance.com/obs-agent/obs-agent-v0.5.0.yml -o obs-agent.yml

名前空間を作成します。

kubectl create namespace obs-agent

マニフェスト内のプレースホルダーを現在のエージェント情報に置き換えます。

sed -i.bak \
  -e "s#replace-with-beak-ws-url#${BEAK_WS_URL}#g" \
  -e "s#replace-with-agent-uuid#${AGENT_ID}#g" \
  -e "s#replace-with-agent-api-key#${AGENT_API_KEY}#g" \
  obs-agent.yml

obs-agent.yml にはすでに Kubernetes の Secret が含まれています。このセクションを直接編集することもできます。

apiVersion: v1
kind: Secret
metadata:
  name: obs-agent-secret
type: Opaque
stringData:
  AGENT_API_KEY: "replace-with-agent-api-key"
  AGENT_ID: "replace-with-agent-uuid"

インストールします。

kubectl -n obs-agent apply -f obs-agent.yml

ステータスを確認します。

kubectl -n obs-agent get pods
kubectl -n obs-agent get deploy
kubectl -n obs-agent logs -f deploy/obs-agent

アップグレードする際は、新しい obs-agent.yml をダウンロードし、現在の BEAK_WS_URL、AGENT_ID、AGENT_API_KEY を維持したうえで、次を実行します。

kubectl -n obs-agent apply -f obs-agent.yml

アップグレード中は既存の PVC を保持して再利用してください。PVC または名前空間を削除すると、StorageClass の再利用ポリシーによっては、基盤となる PV データも削除される場合があります。

YAML インストールを削除します。

以下のコマンドは、マニフェストによって作成された PVC を削除します。基盤となる PV データが保持されるかどうかは、StorageClass の再利用ポリシーによって異なります。復元または継続が必要なタスクがないことを確認してから実行してください。

kubectl -n obs-agent delete -f obs-agent.yml
kubectl delete namespace obs-agent

Kubernetes Helm でインストールする¶

Helm チャートはデフォルトで 3 つの PVC（20 GiB、5 GiB、5 GiB）を作成してマウントします。インストール前に、デフォルトの StorageClass を設定するか、persistence.work.existingClaim、persistence.profileCache.existingClaim、persistence.owl.existingClaim を通じてバインド済みの 3 つの PVC を指定してください。Pod の再構築やアップグレードによってアクティブなセッション/タスクの JSONL 履歴および関連データが失われるため、これらの永続化エントリを無効にしないでください。

Helm リポジトリアドレスを設定してから、リポジトリを追加します。

Helm リポジトリアドレスはコンテナイメージリポジトリとは異なります。後述の image.repository パスを helm repo add に使用しないでください。

export OBS_AGENT_HELM_REPO_URL='https://pubrepo.guance.com/chartrepo/obs-agent'
helm repo add obs-agent "${OBS_AGENT_HELM_REPO_URL}"
helm repo update obs-agent
helm search repo obs-agent

名前空間を作成します。

kubectl create namespace obs-agent

エージェントシークレットを作成します。

kubectl -n obs-agent create secret generic obs-agent-secret \
  --from-literal=AGENT_ID="${AGENT_ID}" \
  --from-literal=AGENT_API_KEY="${AGENT_API_KEY}"

インストールします。

helm upgrade --install obs-agent obs-agent/obs-agent \
  --namespace obs-agent \
  --set image.repository=pubrepo.guance.com/guance/obs-agent \
  --set image.tag=v0.5.0 \
  --set-string config.BEAK_WS_URL="${BEAK_WS_URL}" \
  --set secret.existingSecret=obs-agent-secret

ステータスを確認します。

kubectl -n obs-agent get pods
kubectl -n obs-agent get deploy -l app.kubernetes.io/instance=obs-agent
kubectl -n obs-agent logs -f deploy/obs-agent

Deployment 名が obs-agent でない場合は、kubectl get deploy で得られる実際の名前を使用してログを表示してください。

アップグレードします。

helm upgrade obs-agent obs-agent/obs-agent \
  --namespace obs-agent \
  --reuse-values \
  --set image.tag=v0.5.0

Helm インストールを削除します。

helm uninstall はチャートによって作成された PVC を削除し、kubectl delete namespace はその名前空間内の PVC も削除します。基盤となる PV データが保持されるかどうかは、StorageClass の再利用ポリシーによって異なります。これらのコマンドは、復元または継続が必要なタスクがないことを確認してから実行してください。

helm uninstall obs-agent -n obs-agent
kubectl delete namespace obs-agent

利用可能な環境変数を確認する¶

インストール手順で必要なのは BEAK_WS_URL、AGENT_ID、AGENT_API_KEY のみです。以下の変数は、トラブルシューティングやデフォルト値の上書きに使用します。特定の必要がない限り設定しないでください。

注意事項¶

• Docker と Helm は、同じ AGENT_ID を同時にオンラインで使用することはできません。実行中の各インスタンスには独立したエージェントが必要です。
• イメージのみを置き換えてアップグレードした古いデプロイでは、Owl ボリュームが /var/lib/obs-agent/work/.owl にマウントされたままの場合、OWL_DIR が未設定であればエントリポイントがそれを検出して引き続き使用します。新しい Compose、Kubernetes、Helm のテンプレートは /app/.owl を使用します。移行中は両方の Owl ボリュームをマウントしないでください。
• obs-agent.yml は専用の ServiceAccount を作成し、Kubernetes のサービスアカウントトークンの自動マウントを無効にします。
• コンテナはホストインストールスクリプトを実行せず、systemd に依存しません。
• コンテナ化されたデプロイでは、ローカルの自己更新は有効になりません。イメージのタグまたはダイジェストを置き換えてアップグレードしてください。
• 本番環境では、イメージダイジェストを使用してバージョンを固定してください。