Migrations on Strata Documentation

Binary consolidation

Mon, 01 Jan 0001 00:00:00 +0000

Migrating to the unified `strata` binary#

Strata used to ship eleven cmd/* binaries — one gateway plus a long tail of single-purpose worker daemons. The codebase now ships exactly one:

strata — the gateway plus every long-running background worker (selected at startup via STRATA_WORKERS= / --workers=), with one-shot operator commands available as strata admin <subcommand> against the same binary.

This guide is the operator-facing checklist for upgrading an existing deploy. There is no schema migration, no data migration, and no env-var rename — the move is purely a packaging change.

GC + lifecycle Phase 2

Mon, 01 Jan 0001 00:00:00 +0000

Migrating to gc / lifecycle Phase 2 (sharded leader-election)#

Phase 1 (cycle ralph/gc-lifecycle-scale, commit 6561845) lifted the per-leader concurrency cap via bounded errgroup fan-out (STRATA_GC_CONCURRENCY / STRATA_LIFECYCLE_CONCURRENCY). The leader was still single-replica.

Phase 2 (cycle ralph/gc-lifecycle-scale-phase-2) shards the leader-election space so multiple replicas process disjoint slices of the queue in parallel:

gc gets gc-leader-0..N-1 lease keys driven by STRATA_GC_SHARDS (default 1, range [1, 1024]). Each replica races for one or more of the per-shard leases and drains only the entries it owns via Meta.ListGCEntriesShard. The legacy global gc-leader lease is retired.
lifecycle gets per-bucket leases (lifecycle-leader-<bucketID>) plus a distribution gate (fnv32a(bucketID) % STRATA_GC_SHARDS == myReplicaID, where myReplicaID = min(GCFanOut.HeldShards())). The legacy global lifecycle-leader lease is retired.
Backwards-compat: STRATA_GC_SHARDS=1 (default) reproduces Phase 1 behaviour byte-for-byte. Existing make smoke / make smoke-tikv / make smoke-lab-tikv continue to pass without configuration changes.

This guide is the operator-facing checklist for the schema cutover and the multi-replica rollout.

Compose collapse

Mon, 01 Jan 0001 00:00:00 +0000

Migrating to the single-strata compose shape#

docker compose up -d used to bring up two strata services in parallel on the same Cassandra metadata: a single-cluster strata (port 9999, knew only the default RADOS cluster) and a profile-gated strata-multi (port 9998, knew default + cephb). Both raced for the same global worker leases (gc-leader-N, rebalance-leader-N, lifecycle-leader-<bucketID>, etc.) on Cassandra. Whichever container started first won — and when the single-cluster winner popped a GC entry for cephb, deletion failed forever (no cephb connection), the queue piled up, deregister_ready stuck false, and drain wedged.

Drain progress physical chunks

Mon, 01 Jan 0001 00:00:00 +0000

Migrating to the physical-chunk drain progress#

GET /admin/v1/clusters/<id>/drain-progress and the operator console <DrainProgressBar> used to surface chunks_on_cluster — the manifest-derived chunk count — as the sole headline metric. After the ralph/drain-progress-physical cycle (US-001..US-003) the response gains three additive fields and the UI renders a 3-state machine that distinguishes manifest progress from physical pool state.

This page documents the wire shape change, the back-compat fallback for backends without the new probe, and the operator-visible state machine. There is no schema migration; no data migration; the change is purely additive on the /drain-progress JSON shape.

TiKV-default lab

Mon, 01 Jan 0001 00:00:00 +0000

Migrating to the TiKV-default 2-replica lab#

docker compose up -d used to bring up a single Cassandra-backed strata service on :9999 plus a ceph + ceph-b multi-cluster RADOS pair. TiKV was opt-in via --profile tikv (strata-tikv) or --profile lab-tikv / --profile lab-tikv-3 for 2- and 3-replica labs, and a parallel 3-replica Cassandra lab lived under --profile lab-cassandra-3. Four distinct profile shapes plus the always-on bare default — each rarely-used, each one a maintenance surface to keep green across CI + smoke + bench scripts.

Migrations on Strata Documentation

Binary consolidation

Migrating to the unified strata binary#

GC + lifecycle Phase 2

Migrating to gc / lifecycle Phase 2 (sharded leader-election)#

Compose collapse

Migrating to the single-strata compose shape#

Drain progress physical chunks

Migrating to the physical-chunk drain progress#

TiKV-default lab

Migrating to the TiKV-default 2-replica lab#

Migrating to the unified `strata` binary#