mirror of
https://github.com/kvcache-ai/Mooncake.git
synced 2026-11-05 01:17:55 +00:00
[GH-ISSUE #4837] [RFC]: [Store] HA: Protect in-flight PutStart allocations across failover with a segment-owner ledger #1232
Labels
No labels
ascend
auto-closed
bug
bug
CI/Build
Common
documentation
enhancement
feature request
good first issue
help wanted
high priority
MetaX
nightly-failure
pull-request
PyTorch Backend
question
RFC
Roadmap
stale
Store
Tests
Transfer Engine
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
kvcache-ai/Mooncake#1232
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @SongOf on GitHub (Oct 21, 2026).
Original GitHub issue: https://github.com/kvcache-ai/Mooncake/issues/4837
Changes proposed
Summary
In HA mode, memory allocations (
PutStart,UpsertStart,CopyStart,MoveStart,PromotionAllocStartand their variants) are not written to the OpLog. After a failover, the promoted leader therefore cannot see ranges that are still being written. It may give such a range to another key, or serve an object asCOMPLETEwhile an in-place upsert is still overwriting it. Either way a reader can get wrong bytes, with no error.The HA roadmap (#3808, RL02, from RFC #2979) fixes this by making
REPLICA_CREATEdurable beforePutStartreturns. That adds at least one etcd commit to every write.This RFC proposes a lighter protection for memory replicas, with no quorum write on the write path. The process that owns a segment keeps a small ledger of the ranges being written in it, fenced by the leader's term. At failover, the promoted leader learns those ranges from the owners and keeps them reserved.
It is a proposal for review. Nothing here is implemented.
Motivation
UpsertStartrewrites the existing buffers in place. A promoted leader still sees the old object asCOMPLETE.Goals and non-goals
Goals:
takeoverorenforce.Non-goals:
PUT_ENDon failover. Per #3885, that is part of the cache contract.Proposal
Overview
Ledger on the segment owner. Each client that mounts a memory segment keeps an in-process ledger of the ranges that may still be written in it. A segment's memory and its RDMA registration live and die with that process, so no quorum store is needed.
Register before writing. A writer registers each range with the segment's owner before its first transfer to it, under the term of the leader that allocated the range. The owner returns a unique ledger token for that write attempt. The writer writes only after the registration is acknowledged.
Fencing by term. A term is the pair (
view_version, leader session token). The owner accepts registrations only under its current term.Takeover on mount and remount. When the owner mounts or remounts a segment, it moves to the current leader's term and reports its entries before the remount. From then on it rejects registrations under any other term. The leader accepts a report only under its own term, and applies it before the segment can be allocated from.
Reconciliation. For each reported entry, the leader does one of three things:
Completion identity. Completion RPCs (
PutEnd,PutRevokeand the others) carry the term of their allocation. A leader rejects completions from another term, so a write that started before a failover cannot complete or free a write started after it.Safe clearing. A writer clears its entry by token, and only after both of these:
The owner tells the leader when reported entries are cleared, so the leader can release them.
Why this is safe
Within the scope below, every writer of a segment registers. The owner processes a registration and a takeover in some order. If the registration comes first, the takeover reports it, and the new leader protects the range. If the takeover comes first, the registration carries an older term and is rejected, so the writer never writes. A stale leader that keeps allocating is fenced the same way.
The argument rests on six rules, none of which involves a timeout or a clock:
Terms are safe on all three HA backends (etcd, Redis, k8s), because session tokens are unique per leadership. If a backend's
view_versionever goes backwards, the affected segments stop accepting remounts until an operator intervenes. That loses capacity, not data.Scope
enforce. The guarantee is per segment, because an unregistered writer could corrupt a registered one. So inenforcethe leader refuses memory allocations to clients that have not declared ledger support.offandshadowthey behave exactly as today.Compatibility
struct_pack::compatiblefields: the issuing term inObjectMeta, the session token and the cluster's ledger mode inPingResponse, and the ledger address inSegment. Also a few new RPCs: registration, clear, ledger report, address lookup, a capability declaration (also used to acknowledge mode changes), and term-carrying variants of the non-struct completion RPCs. Old peers fall back to today's behavior. No allocation RPC signature changes.offandshadow, any mix behaves as today.takeoverneeds ledger-enabled masters and owners, andenforcealso needs every client upgraded.Performance
shadowmode measures the cost on real workloads before enforcement is proposed. If the cost is not acceptable, the feature stays off, and RL02 remains the alternative.Alternatives considered
REPLICA_CREATEThe ledger and RL02 can coexist, for example the ledger for memory and RL02 for NoF.
Implementation plan
The work is split into small PRs. One setting,
allocation_ledger_mode, gates it, with four levels:off: the default; no ledger work at all;shadow: register and report, but only count failures and mismatches;takeover: also reconcile reported entries after a failover;enforce: also reject unregistered writes and refuse allocations to undeclared clients.The mode is set on the masters. The leader advertises it in
PingResponse, and clients follow it, so a single setting switches the whole cluster. Clients learn of a change only at their next ping. So a raise takes effect only after every connected client has acknowledged the new mode, or has left. Clients acknowledge by resending their capability declaration. This way a client never acts on a lower mode than the leader. A client that reconnects pings before it allocates, so it starts with the current mode. A lowering takes effect at once.I plan to implement it once the direction is agreed.
PingResponse; client term tracking; capability declaration and mode acknowledgement2. Completion identity: issuing term on completion RPCs
3. Ledger RPC service on segment providers; ledger address lookup
shadow5. Writer-side registration in
TransferSubmitter's write entry points, covering every write pathshadow7. Reconciliation: reserve, hide and remove, release on clear
takeover9. Reclaim orphaned entries
enforce11. Benchmarks against no ledger and an RL02-style prototype
12. Documentation and an operations guide
Dependencies:
Rollout process
off. Nothing changes.shadow. Watch registration latency and failures, owner load, live entry counts, and completion-term mismatches.takeover. Run the fault-injection suite and real failovers. Verify that no protected range is reused, and that hidden replicas are removed rather than served.takeover, then toenforce, one cluster at a time. A cluster moves toenforceonly after every client in it has declared ledger support.offdefault once maintainers accept the benchmark results and the staging evidence.Rollback: lowering the mode, down to
off, takes effect immediately and returns the cluster to today's protection. No persistent state needs migration, because ledger entries and reservations live only in memory.Open questions
Related
Issues and PRs: #2979, #3808, #4491, #3885, #3030, #2953, #3819, #3826, #4780, #4802, #3666, #4700, #4801, #3848.
AI assistance disclosure
The analysis and this text were prepared with an AI coding assistant (Claude Code), which read the code on
mainat042ab8a1. The submitter directed and reviewed it.Before submitting a new issue...
@github-actions[bot] commented on GitHub (Oct 21, 2026):
Thanks for opening this issue, @SongOf!
46475785A maintainer will triage this when possible. To help us respond faster, please include:
Useful links: Documentation · Contributing guide