에이전트 컨테이너 설치 매뉴얼¶

이 문서는 Docker 및 Kubernetes로 obs-agent를 설치하는 방법을 설명합니다. Kubernetes에 설치하는 경우 Helm 사용을 권장합니다.

컨테이너가 시작되면 BEAK_WS_URL, AGENT_ID, AGENT_API_KEY를 사용하여 Beak에서 런타임 구성을 로드한 다음 에이전트를 시작합니다.

영구 스토리지는 런타임 필수 요건입니다. /app은 활성 세션/작업 JSONL 기록 및 관련 데이터를 저장하며, 나머지 두 디렉터리는 프로필 및 Owl 데이터를 저장합니다. Docker, Kubernetes YAML, Helm 배포는 /app, /var/lib/obs-agent/profile-cache, /app/.owl에 대해 영구 스토리지를 제공해야 합니다. Owl 볼륨은 /app/.owl에 별도로 마운트하십시오. 그렇지 않으면 컨테이너 또는 Pod 재빌드나 업그레이드 후 활성 세션/작업을 이어갈 수 없게 될 수 있습니다.

컨테이너 노드가 Beak, LLM 또는 기타 공용 서비스에 직접 접근할 수 없는 경우 먼저 obs-agent 정방향 프록시 구성을 참고하십시오.

연결 정보 준비¶

Beak 콘솔 또는 설치 페이지에서 다음 세 값을 복사하십시오:

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 배포는 아래에 표시된 세 개의 명명된 볼륨을 생성하고 다시 마운트해야 합니다. 업그레이드 및 재시작 시 동일한 볼륨 이름을 재사용하십시오. 컨테이너 임시 디렉터리로 대체하지 마십시오. 컨테이너와 독립적으로 관리되는 바인드 마운트도 지원됩니다.

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에 게시된 기본 매니페스트를 직접 사용할 수 있습니다.

기본 매니페스트는 세 개의 PVC(20 GiB, 5 GiB, 5 GiB)를 생성하고 마운트합니다. 설치 전에 클러스터에 동적 프로비저닝을 위한 기본 StorageClass가 있거나 PVC가 바인딩할 수 있는 사전 생성된 PV가 있어야 합니다. PVC가 바인딩되지 않은 동안 Pod는 Pending 상태로 유지됩니다. 이를 emptyDir로 대체하지 마십시오. Pod 재빌드나 업그레이드 시 활성 세션/작업 JSONL 기록 및 관련 데이터가 손실되기 때문입니다.

매니페스트를 다운로드하십시오:

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 차트는 기본적으로 세 개의 PVC(20 GiB, 5 GiB, 5 GiB)를 생성하고 마운트합니다. 설치 전에 기본 StorageClass를 구성하거나 persistence.work.existingClaim, persistence.profileCache.existingClaim, persistence.owl.existingClaim을 통해 바인딩된 세 개의 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에 의존하지 않습니다.
• 컨테이너화된 배포는 로컬 자체 업데이트를 활성화하지 않습니다. 이미지 태그 또는 다이제스트를 교체하여 업그레이드하십시오.
• 프로덕션에서는 이미지 다이제스트를 사용하여 버전을 고정하십시오.