Architecture

Metadata clusters

A metadata cluster is a pool of services that distributes a region's volume load. It groups the cluster-scoped services and the volumes that mountOS assigns to them into one partition under an existing region. Every metadata cluster in a region shares that region's one database and one vault.

HUB, region, and the metadata clusters inside it

flowchart TD client["mountOS client filesystem mount, S3, HDFS, CSI resolves volume once, pins to owning metadata cluster"] subgraph hubtier ["Tier 1: client + global HUB"] hub["Global HUB · appserv discovery, accounts, volumes, topology one logical HUB · N instances, HA"] admindb["Admin DB regions, metadata clusters, service nodes, volumes"] hubvault["Hub vault HUB signing keys · service-verifier set"] end hub --> admindb hub --> hubvault client -->|"discover: access key to owning metadata cluster (control)"| hub subgraph rega ["Region · eu-west-1 (own database, vault · storages on S3-compatible or Azure)"] subgraph cdefault ["Metadata cluster · default (cluster id) serves only its shard of volumes"] dsA["dataserv (meta) · replicated cluster serves its shard of volumes, cached"] gcA["gcserv in dataserv by default · or own pool, per metadata cluster"] end subgraph c2 ["Metadata cluster · cluster-2 independent volume-load partition"] dsB["dataserv (meta) · replicated cluster its own shard of volumes"] gcB["gcserv · per-metadata-cluster cleanup"] end regdbA["Region DB MySQL / PostgreSQL wire"] regvaultA["Region vault keys, verifiers, volume + object creds"] storA["Object storage S3 · GCS · B2 · MinIO · Azure · on-prem"] bsA["Block storage one of many per region"] end subgraph regb ["Region · us-east-1 (same shape)"] clustersB["Metadata clusters · 1..N dataserv (meta) · replicated per metadata cluster gcserv"] regdbB["Region DB"] regvaultB["Region vault"] storB["Object storage"] end hub -->|"register · resolve · heartbeat (control)"| rega hub -->|"register · resolve · heartbeat (control)"| regb client -->|"data: mountOS service connection"| cdefault cdefault --> regdbA cdefault --> regvaultA cdefault --> storA c2 --> regdbA c2 --> regvaultA c2 --> storA bsA -->|"persist and fetch parts"| storA clustersB --> regdbB clustersB --> regvaultB clustersB --> storB %% Legend: solid = data path (client to owning metadata cluster); muted = control path via HUB; dashed accent box = metadata cluster %% region-wide singletons (DB, vault, storage) stay unpartitioned; no data crosses a region boundary; a volume moves between metadata clusters via handover

Where a metadata cluster sits

mountOS nests a deployment from the top down. The global HUB, served by control nodes, sits above everything. It answers discovery requests. An account is the tenant: it owns its regions, users, and storages. Each region belongs to one account. It owns its own database and vault. The account's storages hold the file content. A storage is a region-scoped record that points at an S3-compatible store or an Azure store. A region can have one or many storages. Inside a region, one or more metadata clusters each run their own pool of cluster-scoped services. Each metadata cluster owns a slice of the region's volumes.

HUB (control nodes): the HUB runs as one logical instance per deployment. Each deployment replicates it for HA. It owns the admin database, which holds accounts, users, regions, and volumes. It authenticates every request. It resolves which metadata cluster serves a given volume. It does not belong to any account, region, or metadata 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 and its own vault. Its services need no DNS; the HUB's discovery hands clients their addresses directly. It has one or more account-owned storages that point at S3-compatible or Azure stores. A volume belongs to exactly one region. Its data never crosses a region boundary at serving time.
Metadata cluster: a volume-load partition inside a region. The cluster-scoped metadata nodes serve only the volumes that mountOS pins to the metadata cluster. The storage node is not scoped to a metadata cluster. All metadata clusters in a region share that region's single database and vault.

What a metadata cluster is for

A metadata cluster does three things, always within one region.

Distributes volume load. It binds a pool of cluster-scoped metadata nodes to the volumes that mountOS assigns to it. This lets a region spread its volumes across several independent service pools.
Keeps each pool to its own volumes. Each metadata cluster serves only the volumes assigned to it.
Has a lifecycle. A metadata cluster can be ready or not ready. It can be active or deactivated. One metadata cluster per region is the default. That metadata cluster receives new volumes.

Identifying a metadata cluster

mountOS identifies each region and each metadata cluster by a UUID. An in-region service boots with only its metadata 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. It has no fallback. The HUB refuses an empty metadata cluster id, an unknown metadata cluster, and a deactivated metadata cluster. A misconfigured service starts but does not register. It raises a critical topology alert. It retries until the topology is fixed. It does not join the wrong metadata cluster.

Metadata cluster lifecycle

A metadata cluster is a control-plane record, created through the HUB's admin API. Creating a region automatically creates its first metadata cluster; the region can take additional ones later.

Ready. A metadata cluster that is not ready blocks volume assignment. The first cluster-scoped service that registers into a metadata cluster flips it to ready. After that, mountOS can assign volumes to the metadata cluster.
Active. An operator can deactivate a metadata cluster. Deactivation blocks the metadata cluster's use but does not delete it. If a service points at a deactivated metadata cluster, it starts but refuses to register. It raises a critical topology alert. It retries until the topology is fixed.
Default. Exactly one metadata cluster per region is the default. A volume that is created without an explicit metadata cluster lands on that metadata cluster.

Volumes and routing

mountOS pins a volume to exactly one metadata cluster within one region. That assignment is what routes clients. Clients do not need to know their metadata cluster in advance. A client calls the HUB's discovery endpoint with its access key. The HUB looks up the volume's owning region and metadata cluster. The HUB returns that metadata cluster's metadata-node endpoints. The client then pins to the owning metadata cluster for the duration of the session.

Moving a volume between metadata clusters

An operator can move a volume to another metadata cluster in the same region. The move is not an instant cutover. The source metadata cluster continues to serve the volume during the handover window. After the handover, the destination metadata cluster takes ownership of the volume. The client re-resolves through the HUB. The client retries on the new metadata cluster. The move is transparent to the client.

What metadata clusters share, and what they do not

Concern	Scope
Regional database	One per region, shared by every metadata cluster in it
Region vault	One per region, shared by every metadata cluster in it
Storages	Account-owned, region-scoped records, one or many per region. A volume is created on exactly one, whatever metadata cluster serves it
metadata node	Per metadata cluster: each pool serves only its metadata cluster's volumes
Discovery scope	Per metadata cluster: a service resolves only the nodes in its own metadata cluster
Volume assignment	Per metadata cluster: a volume belongs to exactly one metadata cluster at a time

The database and vault are regional. A new metadata cluster does not need its own database or vault. A new metadata cluster adds another pool of services that takes a share of the region's volumes. This pool works in addition to the existing regional infrastructure. To set up a metadata cluster, see Deploy.