배포

두 가지 배포 모델

로컬: Docker Compose

프레임워크 저장소에는 애플리케이션, PostgreSQL(pgvector 포함), Redis, Vault, 관측성 스택으로 구성된 두 가지 완전한 스택이 포함되어 있습니다.

docker compose -f compose-grafana.yml up --build      # Grafana stack
docker compose -f compose-opensearch.yml up --build   # OpenSearch Dashboards stack

스캐폴딩된 프로젝트에는 자체 compose.yml(app + postgres + redis + vault)이 포함됩니다. 첫 번째 에이전트를 참고하세요.

프로덕션: Terraform을 사용한 Kubernetes

Agent-Lab은 애플리케이션과 그 의존성을 Kubernetes에 배포하는 Terraform 스크립트를 제공합니다. 이 안내에서는 참고용으로 Minikube 클러스터를 사용합니다. 실제 배포에는 프로덕션 수준의 클러스터를 사용하세요.

사전 요구 사항

• Terraform
• kubectl
• jq

Kubernetes 클러스터 설정

Minikube (Linux) — 충분한 리소스를 할당하세요(레퍼런스 스택은 무겁습니다).

minikube start --memory=20g --cpus=4

클러스터 IP를 확인하고 서비스 도메인을 해당 IP에 매핑하세요.

minikube ip
# 192.168.49.2

192.168.49.2 vault.my-domain.com kibana.my-domain.com elasticsearch.my-domain.com agent-lab.my-domain.com litellm.my-domain.com

Docker Desktop (Mac / Windows) — 기본 제공되는 Kubernetes를 활성화하세요.

Docker Desktop에서는 도메인이 localhost로 해석됩니다.

127.0.0.1 vault.my-domain.com kibana.my-domain.com elasticsearch.my-domain.com agent-lab.my-domain.com litellm.my-domain.com

의존성 프로비저닝

아래의 모든 모듈은 terraform/에 있습니다. 각 디렉터리에서 다음 순서대로 terraform init && terraform apply를 실행하세요.

Keycloak 인스턴스(09_keycloak-instance/)를 적용한 뒤 관리자 비밀번호를 가져오세요.

echo "$(kubectl --namespace keycloak get secret/keycloak-initial-admin -o go-template='{{index .data "password" | base64decode}}')"

Keycloak 인증에 따라 OIDC 연결을 구성하거나, 아래의 12_agent-lab-auth-realm/ 모듈이 처리하도록 하세요.

Vault 초기화(08_vault-instance/ 적용 후) — 초기화하고 봉인을 해제하세요.

kubectl --namespace vault exec vault-0 -- vault operator init \
    -key-shares=1 \
    -key-threshold=1 \
    -format=json > cluster-keys.json

export VAULT_UNSEAL_KEY=$(jq -r ".unseal_keys_b64[]" cluster-keys.json)
kubectl --namespace vault exec vault-0 -- vault operator unseal $VAULT_UNSEAL_KEY

관측성(선택 사항이지만 권장) — 시뮬레이션 스위트와 트레이싱 백엔드가 사용하는 LLM 관측성 플랫폼입니다.

Elastic 자격 증명을 가져오세요.

echo "$(kubectl --namespace elastic get secret elasticsearch-es-elastic-user -o=jsonpath='{.data.elastic}' | base64 --decode)"

echo "$(kubectl --namespace elastic get secret/elastic-eck-apm-server-apm-token \
    -o go-template='{{index .data "secret-token" | base64decode}}')"

OpenTelemetry Collector(11_otel-instance/) — 앱이 데이터를 내보내는 OTLP 엔드포인트입니다(관측성).

LiteLLM 게이트웨이(17_litellm-instance/) — 가상 키, 비용 추적, 관리자 UI(/ui)를 제공하는 자체 호스팅 OpenAI 호환 LLM 게이트웨이입니다.

echo "$(kubectl --namespace litellm get secret/litellm-masterkey -o go-template='{{index .data "masterkey" | base64decode}}')"

curl -s https://<litellm_fqdn>/health/readiness

Agent-Lab 배포

세 개의 모듈이 모든 것을 연결합니다.

cd terraform/12_agent-lab-auth-realm/ && terraform init && terraform apply
cd terraform/15_agent-lab-dependencies/ && terraform init && terraform apply
cd terraform/16_agent-lab-instance/ && terraform init && terraform apply

시크릿 참고: 배포된 앱은 시작 시 Vault(secret/app_secrets)에서 구성을 읽습니다. 페이로드 키는 구성 레퍼런스에 나열되어 있습니다.

Helm 차트

저장소에는 Helm 차트 charts/agent-lab도 포함되어 있습니다. 이 차트는 웹 에이전트용 Headless Chrome(CDP), HPA, 인그레스, 구성, 서비스 계정 등의 사이드카와 함께 애플리케이션 배포를 패키징합니다. 의존성을 이미 직접 운영하고 있으며 앱만 설치하려는 경우에 사용하세요.

체크리스트

완료하기 전에 다음을 확인하세요.

• GET /status/liveness와 GET /status/readiness가 200을 반환함
• GET /docs가 렌더링되고 GET /agents/list가 응답함(인증이 켜져 있으면 토큰 사용)
• 트레이스가 OTLP 엔드포인트에 도착함(관측성 참고)
• Vault에 모든 페이로드 키가 담긴 secret/app_secrets가 있음
• Keycloak 렐름에 클라이언트와 서비스 계정이 있음