사전 요구 사항
- 컨테이너 이미지 풀 및 아티팩트 다운로드를 위한 GitHub PAT (enterprise-docs/github-token.md 참고)
- 전용 Kubernetes 클러스터 (아래 요구 사항 참고)
- 데이터베이스 백업을 위한 스토리지 버킷
- 네트워크 연결: 클러스터 로드 밸런서로 인바운드 443 포트 개방
1단계: 전용 Kubernetes 클러스터 프로비저닝
AgentEye 전용 Kubernetes 클러스터를 생성합니다. 다른 워크로드와 공유하지 않아야 플랫폼 전체(애플리케이션 서비스, 데이터베이스, 분석, 캐싱)가 격리된 환경에서 실행되어 기존 인프라에 영향을 주지 않습니다.| 요구 사항 | 세부 내용 |
|---|---|
| 배포판 | EKS, GKE, AKS 또는 자체 관리형 등 표준 Kubernetes |
| 버전 | 1.27 이상 |
| 노드 풀 | 최소: 노드 3개, 각 4 vCPU / 8 GB RAM (범용 표준 인스턴스) |
| 스토리지 | 블록 볼륨을 프로비저닝하는 기본 StorageClass (예: AWS의 gp3, GCP의 pd-ssd) |
| 로드 밸런서 | 클라우드 LoadBalancer 서비스 프로비저닝 가능해야 함 (EKS, GKE, AKS 기본 지원) |
Exosphere는 클러스터 내부의 모든 것을 설치하고 관리합니다: 인그레스 컨트롤러, TLS 인증서, 데이터베이스, 캐싱, 모니터링, 모든 애플리케이션 배포.
2단계: AgentEye 팀에 접근 권한 부여
Exosphere는 네임스페이스, 커스텀 리소스 정의, 인그레스 컨트롤러, 스토리지 프로비저너를 관리하기 위해 cluster-admin 권한(또는 이에 준하는 광범위한 RBAC)이 필요합니다.| 요구 사항 | 세부 내용 |
|---|---|
| 접근 방식 | IAM 역할 (EKS/GKE에 권장), kubeconfig, 또는 SSO 기반 접근 |
| VPN / 배스천 | Kubernetes API 서버가 프라이빗 환경이라면 Exosphere 운영팀에 VPN 자격 증명 또는 배스천 접근 정보 제공 |
3단계: 네트워크 연결 구성
네트워크 팀에서 클러스터 로드 밸런서로의 443 포트 인바운드 트래픽을 허용해야 합니다. 배포는 두 개의 별도 로드 밸런서를 사용합니다: 하나는 이벤트 수집용(mTLS 보호), 다른 하나는 대시보드용입니다.| 트래픽 | 출발지 | 목적지 | 보안 |
|---|---|---|---|
| 이벤트 수집 | 클러스터 내 수집기 파드 | 수집 LoadBalancer, 443 포트 | mTLS(클라이언트 인증서) + API 키 |
| 대시보드 | 개발자 브라우저 | 대시보드 LoadBalancer, 443 포트 | 도메인에 HTTPS, 비밀번호 없는 이메일 OTP 로그인 |
agenteye.your-company.example)으로, Exosphere가 제공하는 로드 밸런서 호스트명을 가리키면 됩니다. Exosphere가 두 호스트명에 대해 갱신을 포함한 공개 신뢰 TLS 인증서를 자동으로 프로비저닝합니다.
80 포트 참고: 자동 인증서 발급 및 갱신은 각 로드 밸런서의 80 포트 HTTP를 통해 검증됩니다. 보안 정책상 대시보드 로드 밸런서를 사내 IP 범위로 제한해야 하는 경우 Exosphere에 먼저 알려 주세요. DNS 기반 인증서 검증 방식(여러분 측에 DNS 레코드 하나 추가)으로 전환하여 제한 환경에서도 갱신이 계속 작동하도록 합니다.
아웃바운드: 클러스터 노드는ghcr.io에서 컨테이너 이미지를 받기 위해 인터넷 접근이 필요합니다. 아웃바운드 트래픽을 제한하는 네트워크 환경이라면ghcr.io를 허용 목록에 추가하거나 내부 레지스트리에 이미지를 미러링하세요.
4단계: 백업 스토리지 버킷 제공
데이터베이스 백업은 여러분이 소유한 클라우드 스토리지 버킷에 저장됩니다.| 요구 사항 | 세부 내용 |
|---|---|
| 서비스 | S3 (AWS), GCS (GCP), 또는 Azure Blob Storage |
| 접근 | IRSA (EKS) 또는 Workload Identity (GKE)를 통한 IAM 역할로 클러스터 노드에 쓰기 권한 부여, 또는 자격 증명 직접 제공 |
| 보존 기간 | 버킷의 수명 주기 정책(보존 기간, 아카이브 규칙)은 여러분이 직접 제어합니다. Exosphere는 백업을 기록하며, 보존 기간은 여러분이 결정합니다 |
5단계: 담당자 지정
클러스터 수준 문제(노드 상태, 클라우드 계정 한도, 네트워크 변경)에 대응할 담당자 1명 또는 Slack/Teams 채널을 지정해 주세요. 일상적인 운영에서는 해당 담당자가 관여할 필요가 없습니다.배포되는 컴포넌트
Exosphere가 클러스터 접근 권한을 확보하면 다음 컴포넌트들이 배포되고 관리됩니다.| 컴포넌트 | 역할 |
|---|---|
| AgentEye 서버 | 수집기로부터 이벤트를 받아 분석을 실행하고 대시보드에 데이터를 제공하는 HTTP API |
| 대시보드 | 에이전트 세션, 도구 호출, 모델 요청, 오류를 확인하는 웹 인터페이스; 선택적 읽기 전용 AI 어시스턴트 포함 |
| ClickHouse | 수집된 이벤트, 분석, 평가를 위한 필수 정규 스토어 |
| PostgreSQL | 조직, API 키, 사용자, 대시보드, 저장된 쿼리를 위한 관계형 스토어 |
| Redis | 선택적 공유 캐시 및 속도 제한 백엔드; 사용 불가 시 플랫폼이 점진적으로 성능을 낮춰 계속 동작 |
| AI 어시스턴트 (선택) | 내부 읽기 전용 어시스턴트 컨테이너; LLM 엔드포인트가 구성될 때까지 비활성화 상태 유지 |
| 인그레스 컨트롤러 | 두 개의 로드 밸런서(mTLS 보호 수집용, 대시보드용)로 TLS를 종료하고 공개 신뢰 자동 갱신 인증서 사용, 수집 엔드포인트에 mTLS 적용 |
| cert-manager | TLS 인증서 프로비저닝 및 mTLS 클라이언트 인증서 발급 자동화 |
| 인증서 모니터링 | 주기적으로 인증서 만료를 확인하고 갱신 시점이 가까워지면 알림(예: Slack) 발송 |
제공 내용
배포가 완료되면 다음 항목이 제공됩니다.| 항목 | 세부 내용 |
|---|---|
| 대시보드 URL | 여러분의 도메인 아래 호스트명(예: https://agenteye.your-company.example), 공개 신뢰 자동 갱신 TLS 인증서 적용. 제공된 로드 밸런서 호스트명으로 CNAME 하나 생성; 비밀번호 없는 이메일 OTP 로그인 |
| 수집기 엔드포인트 | 수집 호스트명의 /events 경로(예: https://ingest.your-company.example/events), mTLS 보호 |
| 클라이언트 인증서 번들 | 클러스터별 제공: 클라이언트 인증서, 개인 키, CA 인증서가 Kubernetes Secret 매니페스트로 전달됨. 클러스터당 1회 적용 |
| GitHub PAT | 수집기 바이너리 및 Python SDK 패키지 다운로드용 |
| 수집기 API 키 | events:add 권한이 부여된 범위 지정 키, 수집기 배포당 1개 |
| 설치 가이드 | 수집기 및 Python SDK에 대한 단계별 문서 |
설정 이후 수행 사항
이후의 지속적인 작업은 AgentEye 클러스터가 아닌 여러분의 에이전트 머신에서만 이루어집니다.- AI 에이전트가 실행되는 각 Kubernetes 클러스터에 수집기를 설치합니다: 클라이언트 인증서를 마운트하고 엔드포인트 URL과 API 키를 구성합니다. enterprise-docs/collector-installation.md 참고.
- 에이전트 코드에 Python SDK를 연동합니다. enterprise-docs/python-sdk.md 참고.
- 브라우저에서 대시보드를 열어 에이전트 활동을 확인합니다.
보안
- 데이터는 여러분의 클라우드 계정에 머뭅니다. 클러스터, 스토리지, 데이터베이스 모두 여러분의 환경에서 실행됩니다. 어떠한 데이터도 경계 밖으로 나가지 않습니다.
- 접근 제어는 여러분이 합니다. 클러스터는 여러분의 계정에 있습니다. Exosphere의 접근 권한을 언제든지 감사, 모니터링, 취소할 수 있습니다. 모든 작업은 클라우드 감사 로그(CloudTrail, GCP Audit Logs 등)에 기록됩니다.
- 이벤트 수집에 mTLS 적용. 모든 수집기 요청은 유효한 클라이언트 인증서와 API 키를 모두 요구합니다. 키가 유출되어도 인증서 없이는 무용지물이며, 인증서가 탈취되어도 유효한 키 없이는 사용할 수 없습니다.
- 대시보드 접근 제어. 대시보드는 이벤트 수집과 분리된 자체 로드 밸런서에서 실행되며, 로그인은 허용 목록에 등록된 이메일 주소/도메인으로 제한된 비밀번호 없는 이메일 OTP 방식입니다. 요청 시 로드 밸런서에 IP 소스 범위 허용 목록을 적용할 수 있으며, 자동 인증서 갱신이 로드 밸런서에 도달해야 하므로 Exosphere는 제한과 함께 DNS 기반 인증서 검증을 사용하여 갱신이 계속 작동하도록 합니다.
- 클러스터별 인증서. 각 클러스터는 고유한 클라이언트 인증서를 받습니다. 특정 클러스터가 침해당하더라도 해당 인증서만 독립적으로 취소되며 다른 클러스터에는 영향을 주지 않습니다.
배포 일정
| 단계 | 기간 | 고객 참여 사항 |
|---|---|---|
| 클러스터 프로비저닝 | 1~2일 | 클러스터 프로비저닝 및 Exosphere 접근 권한 부여 |
| 플랫폼 설정 | 1일 | 없음; Exosphere가 모든 인프라 컴포넌트 설치 |
| 애플리케이션 배포 | 1일 | 없음; Exosphere가 서버, 대시보드 배포 및 API 키 생성 |
| 수집기 롤아웃 | 1~3일 | 클러스터에 수집기 설치 (Exosphere의 안내 포함) |
| 프로덕션 안정화 | 1주 | 없음; Exosphere가 모니터링 및 튜닝 |
지원
문의 사항이나 문제가 있으시면support@exosphere.host로 Exosphere에 연락하세요.
다음 단계
- 시작하기: 처음부터 끝까지 전체 안내
- 수집기 설치: 수집기 설치 및 구성
- Python SDK: 에이전트 코드 계측
- API 키: 접근 권한 및 퍼미션 관리
- 문제 해결: 일반적인 문제 및 해결 방법