Store-RS Admin HTTP API

Store-RS Admin HTTP API#

This reference documents HTTP endpoints served by the standalone mooncake-store-rs-admin server. Operator workflows and CLI examples are in the route migration guide and Store-RS operations.

Route Migration API#

HTTP endpoints#

The long-lived mooncake-store-rs-admin server exposes:

  • POST /v1/route-migrations/copy

  • POST /v1/route-migrations/move

  • GET /v1/route-migrations

  • GET /v1/route-migrations/<task_id>

Implementation entry points:

Request fields#

The current request surface uses these key fields:

  • authority

    • route authority stable id

  • tenant

    • required

  • domain

    • optional, defaults to the default domain

  • object_set

    • optional, defaults to the default object set

  • key

    • logical object key

  • source_segment

    • segment that currently hosts the source replica

  • target_segments

    • explicit target segment list

  • task_executor

    • stable id of the runtime that executes the task

  • max_retries

    • admin-side retry budget override; default is 5

Constraints:

  • copy requires at least one target

  • move currently requires exactly one target

  • task_executor must not be empty

  • the admin queue is not persisted; queued tasks are lost if the admin server restarts

Retry and completion#

Retry is owned by the admin server, not by the CLI.

Current semantics:

  • while admin is alive, it automatically retries executor loss and transient RPC failures

  • the default retry budget is 5

  • if executor status is lost but the authoritative route already shows the task is complete, admin marks the task as succeeded

  • if the admin process restarts, the in-memory queue is lost; the durable truth remains the route

Task states currently exposed to callers:

  • pending

  • dispatching

  • running

  • retry_wait

  • succeeded

  • failed

Reserved but not currently exposed in P1:

  • cancelled

Cold-Tier Device Administration#

The Admin HTTP API uses /v1/cold-tier as its base path. It manages Mooncake cold tier devices, not operating-system block devices or mounts. Operating-system provisioning remains the responsibility of deployment tooling.

Device identity fields:

Field

Meaning

device_id

Mooncake-managed logical device identity used by routes and placement

cold_tier_id

Human-readable cold tier alias, for example ssd-0

stable_id

Storage runtime stable identity

epoch

Current live runtime incarnation for fencing

kind

Cold tier kind, for example ssd or nfs

target

Runtime-resolved target spec such as a directory or filesystem UUID

root_dir

Resolved cold root directory

state

Device lifecycle state

schedulable

Whether the device accepts new offload placement

Implemented device operations include create, list, get, register, unregister, disable, enable, drain, blockers query, manual GC, manual free, object cold backing query, pending offload trigger, offload task status/listing, and quarantine reporting.

register and unregister are Mooncake registry operations. unregister without force must not strand cold-only objects on the removed device. Safe forced unregister is allowed only when materialized objects still have hot replicas and can be marked PendingDelete.

Contents