Concepts on Strata Documentation

S3 surface

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

S3 surface#

Strata speaks the AWS S3 REST API over HTTP. The goal is compatibility with the Amazon S3 client ecosystem — the same aws s3 / aws s3api / mc commands and the same SDK calls work against Strata with only the endpoint URL changed. Compatibility is measured against Ceph’s upstream s3-tests suite; the running pass rate lives on the S3 Compatibility page.

The rest of this page introduces each major operation family. None of the details below depend on which metadata or data backend you pick — the S3 surface is identical across backends.

Multi-cluster routing

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

Multi-cluster routing#

A single Strata gateway can fan writes across multiple data clusters. The clusters can be Ceph RADOS pools, S3-compatible buckets in different regions or providers, or a mix. The routing decision happens on every PutObject and works the same for chunked RADOS writes and S3-over-S3 pass-through.

The two layers#

Routing is decided by two independent inputs, evaluated in order:

Bucket placement policy. A bucket can carry an explicit Placement map — {cluster-a: 70, cluster-b: 30} — set via PUT /admin/v1/buckets/{name}/placement. When present, this policy wins. The gateway weighted-picks among the live clusters in the policy and never routes the bucket elsewhere.
Cluster weights. When the bucket has no explicit policy, the gateway synthesizes a default policy from per-cluster weights set via PUT /admin/v1/clusters/{id}/weight {weight: N}. Weights are integers in [0, 100]; clusters with weight 0 accept reads and explicit-policy writes but receive no new default-routed writes.

The two layers do not combine. If a bucket has an explicit placement, the cluster-weight wheel is ignored for that bucket.

Drain & rebalance

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

Drain & rebalance#

Taking a data cluster out of rotation is a multi-step process: stop new writes, move existing bytes off, then remove the cluster from the configuration. Strata models this as an explicit lifecycle so operators can follow progress and abort partway through if needed.

Lifecycle#

stateDiagram-v2
 [*] --> pending: cluster added to env
 pending --> live: activate
 live --> draining_readonly: drain mode=readonly
 live --> evacuating: drain mode=evacuate
 draining_readonly --> evacuating: upgrade
 draining_readonly --> live: undrain
 evacuating --> live: undrain
 evacuating --> removed: deregister
 removed --> [*]

pending — a new cluster ID was added to STRATA_RADOS_CLUSTERS or STRATA_S3_CLUSTERS but the gateway has not yet been told to route default traffic to it. Reads and explicit-policy writes work; default routing skips it.
live — normal operating state. The cluster participates in the default-routing weight wheel.
draining_readonly — operator-initiated stop-write drain. New PUTs refuse with 503 DrainRefused. Reads, deletes, and in-flight multipart sessions keep working. The rebalance worker does not actively move data — use this for maintenance windows.
evacuating — operator-initiated decommission drain. Same write refusal as draining_readonly, plus the rebalance worker scans the cluster and migrates chunks to the remaining clusters honoring each bucket’s placement policy. A live progress chip in the operator console shows bytes moved, estimated time remaining, and per-bucket breakdown.
removed — cluster is gone. Excluded from every code path.

Drain refusal semantics#

While a cluster is draining, the gateway answers PUTs that would have landed on it with 503 DrainRefused and a Retry-After: 300 header. This is PUT only — reads, deletes, HEAD, multipart UploadPart / CompleteMultipartUpload / AbortMultipartUpload, and ListObjects continue working against the draining cluster. The intent is stop-write, not stop-read.

Workers

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

Workers#

A Strata deployment runs the same strata binary in two modes: the gateway handles S3 traffic, and one or more workers handle the background work that does not belong on the request path. Workers run inside the same binary you already deploy — set STRATA_WORKERS=gc,lifecycle,… on a gateway replica and it spawns those loops alongside the HTTP listener.

Every worker is leader-elected: across N gateway replicas, one replica acquires the lease for a given worker and runs it; the others stand by and take over if the leader’s lease expires. Leases are scoped per-worker, so different replicas can lead different workers — gc on replica A, lifecycle on replica B. Workers panic-restart on exponential backoff so a single iteration error never takes a worker offline permanently.