ContextQMD
Back to Rustfs

Storage, Control Plane, And Background Controllers

docs/architecture/storage-control-data-plane.md

1.0.0-rc.12.3 KB
Original Source

Storage, Control Plane, And Background Controllers

This document defines migration boundaries for the storage hot path and adjacent control-plane responsibilities.

Storage API Contracts

Storage API contracts must not absorb implementation details from ECStore or the reader pipeline.

Out of scope for the contract layer:

  • KMS/SSE implementation.
  • Range and compression behavior.
  • Erasure coding and bitrot logic.
  • Remote disk transport and recovery.

No-drift behavior:

  • Object-to-set hash remains unchanged.
  • Write quorum remains unchanged.
  • Reader decryption, etag/checksum, version, and delete-marker behavior remain unchanged.
  • Public compatibility paths remain available through temporary re-exports or wrappers during pure moves.

Cluster Control Plane

ClusterControlPlane starts as a read-only facade inside crates/ecstore/src/cluster. Do not create a standalone cluster crate until internal dependencies are stable.

Initial scope:

  • Topology snapshot.
  • Membership snapshot.
  • Lock registry snapshot.
  • Peer health snapshot.
  • Pool state snapshot.

The first read-only implementation lives behind rustfs_ecstore::api::cluster. It maps existing endpoint pools into the shared storage-api topology contract and an ECStore-owned static membership snapshot. It must not expose local disk paths, start health checks, mutate endpoint ownership, or change placement/readiness. The same facade also owns static pool-state, local-node storage, and peer-health status projections. Peer health remains explicitly unknown until a later slice wires real health signals; this document does not authorize background probes or RPC-based health checks. Readiness impact for storage, lock quorum, peer health, probes, admin routes, RPC, and the S3 data plane is recorded in readiness-matrix.md.

Risk controls:

  • Distributed lock quorum remains per set.
  • RemoteDisk suspect/offline/recovery, timeout, and connection eviction semantics must not be simplified.
  • Health impact behavior must be feature-gated if it changes production behavior.

Background Controllers

Scanner, heal, lifecycle, replication, config reload, metrics, and auto-tuning controllers should move behind explicit controller boundaries after lifecycle contracts are stable.

The first controller work should be read-only status and shutdown ordering, not behavior changes.