Route Migration Guide

Route Migration Guide#

Last updated: 2026-04-23

This guide is for operators and control-plane callers that need to submit explicit key-level route migration tasks in mooncake-store-rs.

1. Capability Summary#

The current implementation exposes two explicit route-migration task types.

copy
- requires an explicit source_segment
- accepts one or more explicit target_segments
- keeps the source replica and appends the target replica set to the authoritative route
move
- requires an explicit source_segment
- currently accepts exactly one target_segment
- removes the source replica from the authoritative route after the target replica is committed

Shared constraints:

the migration granularity is tenant/domain/object_set/key
the durable truth remains the object route, not the admin task record
the admin task queue exists only in the memory of mooncake-store-rs-admin server
multi-target copy currently uses all-or-nothing semantics
task_executor must be explicitly selected

2. Operator Surfaces#

The current product surface exposes two operator entry points:

admin HTTP API
mooncake-store-rs-admin --admin-url ... CLI

There is currently no dedicated Python route-migration API.

2.1 HTTP API#

Endpoint paths, request fields, and retry semantics are documented in the Store-RS Admin HTTP API reference.

2.2 CLI#

mooncake-store-rs-admin is an operator client for the admin HTTP surface. It does not own a private task queue.

Current commands:

mooncake-store-rs-admin ... migrate copy
mooncake-store-rs-admin ... migrate move
mooncake-store-rs-admin ... migrate task list
mooncake-store-rs-admin ... migrate task get

Implementation entry point:

mooncake-store-rs-admin.rs

Key constraints:

migrate commands must pass --admin-url
the CLI does not start an in-process task queue
route migration is asynchronous; it is not a synchronous CLI subcommand
submit request bodies accept only the documented fields; legacy mode or other unknown fields return 400

3. Execution Flow and Responsibility Boundaries#

The current end-to-end flow is:

the caller submits a task through admin HTTP or through mooncake-store-rs-admin --admin-url ...
mooncake-store-rs-admin server stores the task in an in-memory queue
admin resolves the live lease for the selected task_executor
admin submits SubmitMigrationTask through control-plane RPC to the chosen executor runtime
the executor runtime receives the task in LocalMigrationAdapter
the executor runtime reuses execute_explicit_route_migration(...)
the executor writes the target replica set and CAS-publishes the new route
admin polls GetMigrationExecutionStatus; if executor status is lost, admin falls back to authoritative route visibility

Key implementation locations:

admin scheduling and retry:
- service.rs
control-plane migration service:
executor-side worker:
- state_adapters.rs
migration execution kernel:
- runtime_io.rs

4. What `task_executor` Means#

task_executor is not a temporary thread and it is not the admin process.

It means:

which stable runtime is responsible for executing the migration task

Current executor-side implementation:

each runtime can host a long-lived LocalMigrationAdapter
the adapter owns a long-lived worker thread
each task is queued to that worker instead of spawning a one-off execution thread

The current model is therefore “select a runtime and let its background worker execute the task”, not “one task equals one thread”.

5. Recommended Usage#

5.1 Operator or Script Usage#

Prefer the CLI for manual operations or lightweight scripts:

mooncake-store-rs-admin \
  --metadata-url redis://127.0.0.1:6380/0 \
  --admin-url http://127.0.0.1:18080 \
  migrate copy \
  --authority source-store \
  --tenant tenant-a \
  --domain domain-a \
  --object-set set-a \
  --key object-a \
  --source-segment source-segment \
  --target-segment target-segment-a \
  --target-segment target-segment-b \
  --task-executor executor-store \
  --max-retries 5

Query tasks:

mooncake-store-rs-admin \
  --metadata-url redis://127.0.0.1:6380/0 \
  --admin-url http://127.0.0.1:18080 \
  migrate task list

mooncake-store-rs-admin \
  --metadata-url redis://127.0.0.1:6380/0 \
  --admin-url http://127.0.0.1:18080 \
  migrate task get \
  --task-id route-migration-1

5.2 Programmatic Controller Usage#

Prefer direct admin HTTP calls from an operator/controller:

curl -X POST http://127.0.0.1:18080/v1/route-migrations/copy \
  -H 'Content-Type: application/json' \
  -d '{
    "authority": "source-store",
    "tenant": "tenant-a",
    "domain": "domain-a",
    "object_set": "set-a",
    "key": "object-a",
    "source_segment": "source-segment",
    "target_segments": ["target-a", "target-b"],
    "task_executor": "executor-store",
    "max_retries": 5
  }'

Query tasks:

curl http://127.0.0.1:18080/v1/route-migrations
curl http://127.0.0.1:18080/v1/route-migrations/<task_id>

6. Request Fields#

See the HTTP API request reference for field names and request constraints.

7. Failure and Retry Semantics#

See the HTTP API retry reference for completion and failure semantics.

8. Scope Boundaries#

What this feature is:

an explicit operator/control-plane migration surface
a task-based way to pre-place or rebalance selected keys
a route-authoritative migration mechanism

What this feature is not:

not a full-segment migration API
not a durable scheduler that survives admin restart
not a replacement for the normal put/get/remove data plane