ADR-0038: MLflow 외부 SDK 접근 — gend-api 앱 레이어 프록시 (인프라 우회 비채택)

• 상태: 승인
• 날짜: 2026-08-06
• 관련: ADR-0037, 이슈 #2968, spec docs/superpowers/specs/2026-08-06-mlflow-external-sdk-access-design.md

맥락

외부 학습 서버의 mlflow SDK 는 브라우저 SSO 를 탈 수 없어 gend.genon.ai/mlflow (oauth2-proxy ForwardAuth) 에서 403 이다 (2026-08-06 실측). MLflow 2.19 는 자체 인증이 없고, artifact 는 client-direct S3 모드인데 SeaweedFS 는 내부 전용이다.

결정

1. 앱 레이어 프록시 (wandb 동형): gend-api 가 /api/v1/mlflow-sdk/* 에서 MLflow REST 를 pass-through 한다 — 기존 JWT Bearer 검증·AuditMiddleware 재사용, 게이트웨이/oauth2-proxy 무변경. oauth2-proxy 에 bearer 를 허용하는 인프라 우회는 인가·감사가 비어 기각.
2. allowlist fail-closed: 로깅 필요 경로만 허용, delete·레지스트리 쓰기 차단.
3. workspace 는 토큰 클레임: service-client 생성 시 Keycloak hardcoded-claim mapper 로 gend_workspace 를 주입 — DB 테이블 없이 무상태 해석, experiments/create 시 서버가 gend.workspace 태그를 기본 부여 (클라이언트 덮어쓰기 가능 — 무결성 보증은 enforce 단계의 별도 결정, #2913 I3 해소).
4. artifact 는 MLflow 의 artifact 프록시(--serve-artifacts, 2.19 기본 활성)를 그대로 쓰되, --default-artifact-root s3:// 를 --artifacts-destination s3:// 로 교체해 신규 실험의 artifact 트래픽이 서버 REST 를 타게 한다(2026-08-06 실측: 막고 있던 것은 프록시 비활성이 아니라 artifact_location 스킴이었다). gend-api 는 전용 스트리밍 마운트로 중계하며 S3 외부 노출은 하지 않는다. mpu(멀티파트 업로드)는 presigned S3 URL 을 발급해 클라이언트가 이 프록시를 우회하게 하므로 비허용한다(2026-08-06 실측, #2977).
5. 토큰 수명은 gend-cli 의 mlflow request_auth 플러그인(MLFLOW_TRACKING_AUTH=gend) 으로 해결한다 — MLflow 가 요청마다 get_auth() 를 호출하므로(2.19 실측) 별도 갱신 스레드 없이 resolver 의 캐시·만료마진이 그대로 자동 갱신이 된다. 만료 없는 자체 API 키 체계는 도입하지 않는다(Keycloak 단일 자격증명 원천 유지).

결과

• 외부 학습 서버 설정 2쌍이면 끝: MLFLOW_TRACKING_URI=https://gend.genon.ai/api/v1/mlflow-sdk
  • M2M 토큰. 모든 로깅 호출이 감사 로그에 남고 workspace 태깅 커버리지가 생긴다.
• MLflow 업그레이드(3.12+ static-prefix REST 변화) 시 프록시 대상 경로 재검증 필수.