Region clusters

A region cluster is a pool of services that distributes a region's volume load. It groups the cluster-scoped services and the volumes assigned to them into one partition, and every cluster in a region shares that region's one database and one vault. Tenancy lives a level up: the account is the tenant, and a cluster only spreads that region's volumes across more service pools. A cluster is not a second region and not a new infrastructure tier, it is a partition under an existing region.

Where a cluster sits

mountOS nests a deployment from the top down. The global HUB (appserv) sits above everything and answers discovery. An account is the tenant: it owns its regions, users, and storages. Each region belongs to one account and owns its own database and vault. File content lives behind the account's storages, region-scoped records pointing at S3-compatible or Azure stores, one or many per region. Inside a region, one or more region clusters each run their own pool of cluster-scoped services and own a slice of the region's volumes.

• HUB (appserv): one logical instance per deployment, replicated for HA. It owns the admin database (accounts, users, regions, volumes), authenticates every request, and resolves which cluster serves a given volume. It does not belong to any account, region, or cluster.
• Account (tenant): the top-level tenant. An account owns its regions, its users, and its storage backends. A region belongs to exactly one account.
• Region: a deployment locality with its own database, its own vault, one or more account-owned storages pointing at S3-compatible or Azure stores, and DNS for its client-facing services. A volume lives in exactly one region and its data never crosses a region boundary at serving time.
• Region cluster: a volume-load partition inside a region. The cluster-scoped services, dataserv and gcserv, each serve only the volumes pinned to the cluster. Block storage is the exception: its block volumes deliberately span distinct clusters for fault isolation, so it is not a cluster-scoped pool. All clusters in a region share that region's single database and vault.

What a cluster is for

A cluster does three things, always within one region.

• Distributes volume load. It binds a pool of cluster-scoped services (dataserv, gcserv) to the volumes assigned to it, so a region can spread its volumes across several independent service pools.
• Keeps each pool to its own volumes. Discovery is filtered per cluster, so one pool never routes across to another cluster's nodes. A node resolves its own cluster identity and rejects a request that points at a different cluster rather than proxy it. This is load separation, not tenant isolation. The tenant boundary is the account, one level up.
• Has a lifecycle. A cluster can be marked ready or not ready, active or deactivated, and one cluster per region is the default that receives new volumes.

Identifying a cluster

Each region and each cluster is identified by a UUID. An in-region service boots with only its cluster UUID (REGION_CLUSTER_ID) in its environment.

At startup the service resolves that UUID against the HUB before it can register or serve traffic. Resolution is strict and has no fallback. An empty cluster id, an unknown cluster, and a deactivated cluster are all refused. A misconfigured service starts but does not register. It raises a critical topology alert and retries until the topology is fixed, instead of landing on the wrong cluster.

Cluster lifecycle

A cluster is a control-plane record created through the HUB's admin API, not a separate orchestration step. Creating a region inserts a single default cluster automatically, and the region can take additional clusters later.

• Ready. A cluster that is not ready blocks volume assignment. The first cluster-scoped service that registers into a cluster flips it to ready, after which volumes can be assigned.
• Active. Deactivating a cluster blocks its use without deleting it. Services configured for a deactivated cluster start but refuse to register, raise a topology alert, and retry until the topology is fixed.
• Default. Exactly one cluster per region is the default. Volumes created without an explicit cluster land on it.

Volumes and routing

A volume is pinned to exactly one cluster within one region. That assignment is what routes clients. Clients do not need to know their cluster up front: they call the HUB's discovery endpoint with their access key, the HUB looks up the volume's owning region and cluster, and it returns that cluster's dataserv endpoints. The client then pins to the owning cluster for the life of the session.

Moving a volume between clusters

A volume can be relocated to another cluster in the same region. The move is not an instant cutover. The source cluster keeps serving the volume through a handover window. After the handover the destination cluster takes ownership, the client re-resolves through the HUB, and it retries on the new cluster. The move is transparent to the client.

What clusters share, and what they do not

Because the database and vault are regional, adding a cluster does not add a database or a vault to operate. It adds another pool of services that takes a share of the region's volumes, on top of the existing regional infrastructure. gcserv runs as its own pool per cluster. To stand a cluster up, see Deploy.