2026-08-09 MLflow Deployment Atlas

What I set out to do

Understand what an MLflow tracking server deployment actually consists of when running on a PostgreSQL backend store with GCS artifact storage: the database tables and their schemas, the artifact layout and root prefixes in the bucket, and the full REST API surface (the “swagger table”). Package it as a polished HTML report.

What I actually did

Ran three parallel codebase explorations against mlflow/mlflow (master @ 79163356e) and synthesized the results into a single interactive HTML report (“MLflow Deployment Atlas”), published as a Claude artifact.

• Database: catalogued all 59 tables in the tracking + model-registry database (alembic head 6f8d9c3b2a1e) plus 12 in the separate basic-auth/RBAC database (head f1a2b3c4d5e6), with full columns, types, PKs, FKs, indexes, and constraints, grouped by functional area (experiments/runs, traces/spans, logged models, registry, AI gateway, MCP registry, auth).
• GCS layout: documented the prefix hierarchy gs://root/<experiment_id>/<run_id>/artifacts plus the traces/ and models/m-<uuid>/ subtrees, direct vs mlflow-artifacts: proxied access (identical on-bucket layout), and env-var configuration.
• API: enumerated ~280 REST routes from the protobuf rpc options, Flask handlers, and FastAPI routers, with method, path, description, and visibility status.

What was striking

• MLflow intentionally serves no swagger/OpenAPI UI: docs_url/redoc_url/openapi_url are all disabled in the FastAPI wrapper. The protobuf definitions are the only machine-readable spec.
• Trace data is always stored as file artifacts in GCS even with a SQL backend; the DB holds only trace metadata and span rows.
• The GCS repo silently falls back to an anonymous client when credentials fail to resolve, and delete_artifacts does raw prefix matching (deleting foo also hits foobar).
• Prompts have no dedicated tables or routes; they are registered models with a tag.
• A malformed proto path registers /api/2.0mlflow/experiments/search-datasets (missing leading slash).

Related

Report artifact: MLflow Deployment Atlas