GenD API의 핵심 환경 변수와 설정 방법입니다. 모든 변수는 GEND_ 접두사를 사용합니다. 전체 목록은 apps/api/src/gend_api/config.py의 Settings를 참조하세요 (본 문서는 자주 쓰는 부분집합).
apps/api/src/gend_api/config.py의 Settings(BaseSettings) 클래스에서 정의됩니다. model_config = {"env_prefix": "GEND_"}로 설정되어 있어, 예를 들어 trino_host 필드는 GEND_TRINO_HOST 환경 변수에 대응합니다.
핵심 서비스 연결
| 환경 변수 | 기본값 | 설명 |
|---|
GEND_DATABASE_URL | (필수) | PostgreSQL 연결 문자열 |
GEND_TRINO_HOST | trino | Trino 호스트명 |
GEND_TRINO_PORT | 8080 | Trino 포트 |
GEND_TRINO_USER | gend-api | Trino 접속 사용자 |
GEND_TRINO_DEFAULT_CATALOG | iceberg | 기본 카탈로그 |
GEND_TRINO_DEFAULT_SCHEMA | default | 기본 스키마 |
GEND_ARANGODB_PASSWORD | (필수) | ArangoDB 비밀번호 — 기본값 없음, 미설정 시 부팅 실패 |
GEND_ARANGODB_URL | http://arangodb.gend.svc.cluster.local:8529 | ArangoDB 연결 URL (Knowledge Graph) |
GEND_ARANGODB_USERNAME | root | ArangoDB 사용자 (⚠️ GEND_ARANGODB_USER 아님) |
| 환경 변수 | 기본값 | 설명 |
|---|
GEND_BUILD_SHA | unknown | 이미지 빌드 git sha (7자리). CI 가 --build-arg 로 주입, GET /version 이 노출 |
GEND_BUILD_DATE | unknown | 이미지 빌드 일시 (UTC ISO). 주입 경로 동일 |
제품 버전 자체는 환경 변수가 아니라 루트 VERSION 파일 → gend_api.__version__ 으로 빌드에 포함됩니다.
PostgreSQL TLS 회귀 안전망 (#874)
| 환경 변수 | 기본값 | 설명 |
|---|
GEND_PG_REQUIRE_TLS | false | 부팅 시 PG 연결이 pg_stat_ssl.ssl=true 이어야 함. false → 경고만, true → 부팅 거부. prod 는 manifest 에서 true |
GEND_S3_REQUIRE_CREDENTIALS | false | 부팅 시 S3 ingestion bucket head_bucket 성공해야 함. prod 는 true |
GEND_ALLOW_PLAINTEXT_DB | false | asyncpg DSN 의 ssl=disable|0|false|off|no 명시적 opt-in. false 이면 부팅 거부 (§DSN 회귀 안전망) |
GEND_SKIP_S3_HEALTHCHECK | false | true 이면 startup 의 S3 probe 자체 skip — DNS 가 없는 CI smoke / dev 클러스터용. prod 에서 사용 금지 |
GEND_PG_SSL_CA_PATH | (빈 문자열) | asyncpg verify-full 용 CA 번들 경로. prod manifest 가 /etc/postgresql-tls/ca.crt 마운트 |
인증 (Keycloak)
| 환경 변수 | 기본값 | 설명 |
|---|
GEND_AUTH_ENABLED | true | 인증 활성화 |
GEND_KEYCLOAK_URL | http://keycloak:8080/auth | Keycloak 내부 URL |
GEND_KEYCLOAK_ISSUER_URL | (빈 문자열) | 외부 issuer URL |
GEND_KEYCLOAK_REALM | gend | Realm 이름 |
GEND_KEYCLOAK_CLIENT_ID | gend-api | 클라이언트 ID |
Vault / 보안
| 환경 변수 | 기본값 | 설명 |
|---|
GEND_VAULT_ADDR | http://vault:8200 | Vault 주소 |
GEND_VAULT_TOKEN | (빈 문자열) | Vault 토큰 |
GEND_VAULT_ENABLED | false | Vault 연동 활성화 |
AI / LLM
| 환경 변수 | 기본값 | 설명 |
|---|
GEND_AI_EMBEDDING_PROVIDER | openai | 임베딩 제공자 (openai/local) |
GEND_AI_LLM_PROVIDER | openai | LLM 제공자 |
GEND_LLM_OPENAI_API_KEY | (빈 문자열) | OpenAI API 키 |
GEND_LLM_DEFAULT_MODEL | gpt-4o | 기본 LLM 모델 |
쿼리 / 스키마
| 환경 변수 | 기본값 | 설명 |
|---|
GEND_QUERY_CACHE_ENABLED | true | 쿼리 캐시 활성화 |
GEND_MAX_ROWS_PER_PAGE | 1000 | 페이지당 최대 행 수 |
GEND_SCHEMA_SYNC_ENABLED | true | 스키마 자동 동기화 |
GEND_SCHEMA_SYNC_INTERVAL_SECONDS | 300 | 동기화 주기 (초) |
MLflow 외부 SDK 접근 (ADR-0038)
| 환경 변수 | 기본값 | 설명 |
|---|
GEND_MLFLOW_TRACKING_URL | http://mlflow.gend.svc.cluster.local:5000 | /api/v1/mlflow-sdk/* 프록시가 pass-through 하는 내부 MLflow 트래킹 서버 URL |
GEND_MLFLOW_ARTIFACT_MAX_MB | 2048 | artifact(체크포인트·모델) 프록시 업로드 단일 파일 크기 상한(MB). 초과 시 413 — 실험 추적 가이드 의 "2GB" 는 이 값의 기본값이며 튜너블이다 |
GEND_PERSONAL_TRACKING_KEY_QUOTA | 5 | 개인 트래킹 키(v1.2+, ADR-0043) 사용자당 활성 상한. 초과 발급 요청은 409 |
학습 데이터셋 (v1.2+) (#2989 M0)
| 환경 변수 | 기본값 | 설명 |
|---|
GEND_DATASET_DEFAULT_QUOTA_BYTES | 0 | 쿼터 행이 없는 워크스페이스의 스토리지 hard 기본값(bytes). 0 = 무제한 (안전 롤아웃 기본) — 워크스페이스별 한도는 스토리지 쿼터 관리 의 admin API 로 등록한다 |
DMZ / 보안 감사
| 환경 변수 | 기본값 | 설명 |
|---|
GEND_DMZ_ENABLED | false | DMZ Relay 연동 |
GEND_DMZ_HMAC_SECRET | (빈 문자열) | HMAC-SHA256 시크릿 |
GEND_ABUSE_DETECTION_ENABLED | false | 오남용 탐지 활성화 |
GEND_OPENSEARCH_URL | http://opensearch....:9200 | 감사 로그 저장소 |
관련 문서