---
title: "Route storage requests with a partition map"
description: "Design the control plane that maps key ranges to storage nodes while keeping routing caches fresh, safe, and fast."
canonical_url: "https://fanout.sh/system/archive/partition-manager-and-map-table"
md_url: "https://fanout.sh/system/archive/partition-manager-and-map-table.md"
access: "public"
---

# Route storage requests with a partition map

Design the control plane that maps key ranges to storage nodes while keeping routing caches fresh, safe, and fast.

## Public overview

Partition Manager And Map Table

Once storage is range-partitioned, the system needs a control plane that answers:

Component Responsibility --- --- Partition map table durable mapping from range to partition server Partition manager split ranges, assign ranges, react to load/failure Partition server serve assigned ranges Lock service leader election and ownership coordination

Hot Path vs Control Path

The partition manager should not be in every request path if avoidable.

API server reads/caches the partition map. API server talks directly to the partition server. Partition manager updates the map only when ownership changes.

This keeps the control plane off the hot path.

API servers usually cache the partition map to avoid a metadata lookup on every request. That cache needs a correctness protocol.

Case Required Behavior --- --- API routes to old owner old owner rejects with stale-owner or epoch error API has missing range refresh map before failing the request partition move in progress writes use fencing token/epoch to prevent split brain map table unavailable cached reads may continue only within the allowed staleness contract

The map should include an epoch or generation number. Partition servers compare request epochs against their current lease before accepting writes.

A range has exactly one active owner for writes. A partition server can own multiple ranges. Partition changes are visible through the partition map. Old ownership must be invalidated before new writes are accepted. Failover must not create split-brain writes for the same range.

When a partition server fails:

This is safe only if durable bytes live outside the failed partition server or are replicated elsewhere.

Planned movement should look like failover: ownership changes through the same lease and map machinery, not through an ad hoc admin path.

How stale can an API server's cached partition map be? What error tells an API server to refresh ownership? Can two partition managers run at once? Is the map update atomic with ownership handoff? What happens during planned rolling upgrades?

---
This representation contains public Fanout content only. Protected Pro lessons, account data, billing, checkout, and pricing are not included.

Browse the public content map: https://fanout.sh/sitemap.md