EVA Agent Installation

EVA Agent는 EVA 서비스에서 지능형 추론과 데이터 처리를 담당하는 핵심 컴포넌트입니다. 의존성 스택(Qdrant + vLLM) 설치를 완료한 뒤 진행하세요.

🛠️ 사전 준비 사항

설치를 시작하기 전에 아래 도구가 준비되어 있는지 확인하세요.

• Kubernetes 클러스터: EVA가 구동될 클러스터가 필요합니다.
• kubectl 설치: 설치 가이드 바로가기
• Helm 설치: 설치 가이드 바로가기
• AWS CLI 설정: S3 sync/ECR refresh용 AWS credentials를 동기화하거나 ECR 이미지를 사용할 때 필요합니다.

aws configure
# 안내에 따라 AWS Access Key ID, Secret Access Key 등을 입력합니다.

---

🚀 EVA Agent 설치하기

1단계: Helm 저장소 등록 및 업데이트

최신 버전의 차트를 가져오기 위해 레포지토리를 추가한 뒤 업데이트합니다.

helm repo add eva-agent https://mellerikat.github.io/eva-agent
helm repo update

---

2단계: 설정 파일(values) 템플릿 다운로드

환경에 맞게 설정할 수 있도록 필요한 템플릿 파일을 다운로드합니다.

• 공통 values 템플릿
• 공통 secret values 템플릿
• k3s values 템플릿
• AWS values 템플릿
• NCP values 템플릿

RELEASE_VERSION="2.7.0"
BASE_URL="https://raw.githubusercontent.com/mellerikat/eva-agent/chartmuseum/release/2.7.0"

mkdir -p eva-agent
curl -L "$BASE_URL/eva-agent/values.yaml" -o eva-agent/values.yaml
curl -L "$BASE_URL/eva-agent/values-secret.yaml" -o eva-agent/values-secret.yaml
curl -L "$BASE_URL/eva-agent/values-aws.yaml" -o eva-agent/values-aws.yaml
curl -L "$BASE_URL/eva-agent/values-ncp.yaml" -o eva-agent/values-ncp.yaml
curl -L "$BASE_URL/eva-agent/values-k3s.yaml" -o eva-agent/values-k3s.yaml

---

3단계: 사용자 환경에 맞게 설정 업데이트

eva-agent/values.yaml과 eva-agent/values-secret.yaml 파일을 열어 주요 환경 변수를 수정합니다.

NCP는 전용 NCP values 템플릿을 사용하세요.

배포 환경

구성 영역

세부 항목

Category	Name	Description	값	비고
Runtime	replicaCount	replica 수	1

Storage mode와 S3 sync

• Cloud StorageClass(예: EFS CSI) 환경은 sharedPvcStorage.mode: dynamic을 사용하세요.
• k3s NFS 환경은 sharedPvcStorage.mode: static을 사용하고 sharedPvcStorage.nfs.server/path를 설정하세요.
• S3 init sync 컨테이너를 비활성화하려면 persistence.s3Sync.enabled: false로 설정하세요.

⚠️ 주의: Secret 중 OPENAI_API_KEY 항목은 미사용 시에도 더미 값을 넣어두어야 오류가 발생하지 않습니다. (주석 처리 금지)

ℹ️ OTEL 헤더 값 설정

OTEL_EXPORTER_OTLP_HEADERS는 아래와 같이 설정합니다.

LANGFUSE_SECRET_KEY="sk-lf-..."
LANGFUSE_PUBLIC_KEY="pk-lf-..."
LANGFUSE_AUTH=$(printf '%s:%s' "$LANGFUSE_PUBLIC_KEY" "$LANGFUSE_SECRET_KEY" | base64 | tr -d '\r\n')
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ${LANGFUSE_AUTH}"

---

4단계: EVA Agent 설치 실행

환경별 값을 설정한 후 아래 스크립트로 설치를 진행합니다.

Script options

필요한 옵션을 추가해 실행하세요.

• --namespace <ns>: 설치할 namespace (기본: eva-agent)
• --context <ctx>: 사용할 kube context (기본: 현재 context)
• --base-dir <dir>: eva-agent/ 폴더가 있는 기준 디렉토리 (기본: 현재 디렉토리)
• --chart <chart>: Helm chart 경로 (기본: eva-agent/eva-agent)
• --chart-version <ver>: Helm chart 버전 (기본: 2.7.0)
• --image <tag>: 이미지 태그 override
• --ecr-host <host>: ECR host (기본: 339713051385.dkr.ecr.ap-northeast-2.amazonaws.com)
• --ecr-repo <repo>: ECR repo 이름 (기본: mellerikat/release/eva-agent)
• --profile <aws-profile>: AWS profile (기본: default)
• --check-digest <0|1>: 같은 태그일 때 digest 비교 (기본: 0)
• --force-conflicts <0|1>: 업그레이드 시 drift된 리소스를 Helm 기준으로 강제 반영 (기본: 0)
• --aws-credentials-secret <name>: AWS credentials secret 이름 (기본: aws-credentials)
• --sync-aws-credentials <0|1>: AWS credentials secret 생성/갱신 (기본: 1)
• -f, --values <file>: 추가 values 파일 (반복 가능)

기본 로드: eva-agent/values.yaml, eva-agent/values-secret.yaml.

스크립트는 기본적으로 S3 sync initContainer와 ECR refresh를 위해 AWS credentials를 클러스터에 동기화합니다. 직접 관리한다면 --sync-aws-credentials 0으로 비활성화하세요.

ServiceAccount: 차트 기본값은 pre-created ServiceAccount(sa-eva-agent)를 사용합니다. 미리 생성하거나 serviceAccount.create=true로 변경하세요.

# Download the install script
curl -L "https://raw.githubusercontent.com/mellerikat/eva-agent/chartmuseum/install_eva_agent.sh" \
  -o install_eva_agent.sh
chmod +x install_eva_agent.sh

# k3s example
./install_eva_agent.sh \
  --image 2.7.0 \
  -f eva-agent/values-k3s.yaml

# AWS example
./install_eva_agent.sh \
  --image 2.7.0 \
  -f eva-agent/values-aws.yaml

# NCP example
./install_eva_agent.sh \
  --image 2.7.0 \
  -f eva-agent/values-ncp.yaml

---

5단계: 설치 상태 확인

설치가 완료되면 모든 서비스가 정상적으로 올라왔는지 확인하세요.

kubectl get all -n eva-agent