Skip to Content
We are live but in Staging 🎉
Overview

VBase Service Overview

Last validated: 2026-05-11

VBase is Dodil’s control-plane and access layer for Milvus-based vector services.

At a high level, VBase provides:

  • Tenant-scoped service provisioning (cluster and database service lifecycle)
  • Tenant access resolution (endpoint, port, database name)
  • Unified command forwarding to Milvus (RunCommand)
  • Backup and backup-policy management for tenant services
  • Per-tenant proxying with auth/UMA/billing enforcement (through vbase-proxy)

Core Service Modes

VBase supports two runtime service types:

Cluster service (dedicated mode)

  • Represents a dedicated Milvus deployment for a tenant
  • Provisioned through CreateCluster
  • Exposed as ServiceType=CLUSTER
  • Managed with scale/delete/task/access APIs

Database service (shared mode)

  • Represents a tenant database allocated into a shared cluster pool
  • Provisioned through AllocateDatabase
  • Exposed as ServiceType=DATABASE
  • Managed with delete/list/access APIs

Core Concepts

Service ID vs Cluster ID

  • service_id: tenant-facing identifier used in most API calls
  • cluster_id: underlying infrastructure cluster identifier

For dedicated services, service_id and cluster_id are linked through cluster_services metadata. For shared databases, service_id points to database_services and an associated shared cluster_id.

Service Access

GetServiceAccess returns connection details used by clients and CLI:

  • endpoint
  • port
  • db_name (for shared database tenants)

RunCommand

RunCommand executes Milvus RPC operations by method name and JSON payload through VBase’s Milvus operation bridge.

Backup Jobs and Policies

Backup APIs track stateful backup/restore jobs and policy schedules in metadata tables, with a background worker handling status checks and policy-triggered runs.

Lifecycle and Status Model

VBase surfaces service lifecycle through ServiceStatus values in proto:

  • CREATING
  • RUNNING
  • UPDATING
  • DELETING
  • DELETED
  • ERROR
  • STOPPING
  • STOPPED
  • UPDATE_FAILED
  • RESIZING
  • UNKNOWN

Service Boundaries

VBase is not only a Milvus passthrough.

The runtime is split across:

  1. vbase-app (management/orchestration API)
  2. vbase-proxy (tenant ingress proxy for Milvus APIs)
  3. Milvus upstream clusters/databases

The management API handles provisioning, tenancy, and policy orchestration. The proxy handles request-time auth checks, scope checks, metering, and forwarding.

What Is Live vs Internal-Only

Live user-facing management surfaces:

  • Cluster create/get/scale/delete and in-progress task lookup
  • Database allocate/delete
  • Service list/get/access
  • RunCommand
  • Backup and backup policy APIs

Internal/admin-only surface:

  • VBaseAdminService/GetClusterTenants (used by proxy tenant validation, not documented as public user API)

Practical Mental Model

Use VBase in two layers:

  1. Use management APIs/CLI (db commands) to provision and select tenant services.
  2. Use the resulting endpoint/db context to execute Milvus data operations (collections, index, insert, search, query).

For architecture details and flows, see docs/02-architecture.md.

Auth and Access