Global topology

mountOS uses a hierarchical structure. One global HUB, served by control nodes, manages any number of independent regions. Each region divides into one or more metadata clusters. Each metadata cluster runs the services that serve data. Clients contact the HUB once for discovery. Then clients connect directly to the owning metadata cluster and stay connected for the rest of the session.

The HUB

The control node is the single global entry point for the whole deployment. It is multi-tenant. It authenticates every request and serves the admin APIs behind the Admin SDKs. It holds the global account, user, region, volume, and access-key records. It also answers discovery requests (which metadata cluster owns this volume?). Every account belongs to this one HUB. Clients talk to the HUB for discovery and session establishment. Then clients route directly to the metadata cluster that owns their volume.

The HUB maintains its own admin database. This database supports MySQL and PostgreSQL wire protocols. The HUB also maintains its own vault. The vault stores the HUB's signing key, the admin verification key, and the authoritative service-verifier set. The control node uses the admin verification key to validate Admin SDK signatures. Every mountOS service uses the service-verifier set to authenticate other services.

Every mountOS service signs its requests to other services with a JWT. The receiving service verifies each JWT against these trusted keys. mountOS supports HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, and Azure Key Vault as vault backends. See Vault and handshake for the two-vault topology, expected fields, and per-provider configuration.

Accounts, regions, and metadata clusters

An account is the tenant. Each account owns its regions, its users, and its storage backends, all under the one HUB. A region belongs to exactly one account. A region is self-contained. A region owns its own database and its own vault. A region's volumes write data through the account's storages. A storage is a region-scoped record that points at an S3-compatible store or an Azure store. An account can have one or many storages per region. A volume belongs to exactly one region. The volume's data never crosses a region boundary while the system serves requests.

A region contains one or more metadata clusters. A metadata cluster is a volume-load pool. An operator sets REGION_CLUSTER_ID on each node to select its metadata cluster. Each metadata cluster serves only its own shard of volumes, spreading a region's volumes across several independent service pools. Every metadata cluster in a region shares that region's single database and single vault. Each region starts with one default metadata cluster.

Metadata nodes are cluster-scoped. Each service handles only its metadata cluster's volumes. An operator can move a volume between metadata clusters without crossing the region boundary. The storage node is the exception: it is not scoped to a metadata cluster.

Services in a metadata cluster

• metadata node (dataserv, gcserv): the metadata backbone. It holds the directory tree, forks, versions, and ACLs. It also serves the binary metadata protocol to clients. One node serves all inodes for each fork. It caches a hot working set in memory, and the region database backs this cache. The same node collects orphaned data, prunes forks past the retention floor, and clears secrets of deactivated volumes after their grace period.
• storage node (blockserv): optional block storage for low-latency access. It holds file content on local block devices and syncs it to object storage, the durable source of truth. Its public API is the block protocol, not S3. Clients discover a volume's storage nodes through the control node, so storage nodes need no DNS. The client data plane listens on BLOCK_PORT.

The mountos client exposes S3 and WebHDFS as protocol surfaces. The control node authenticates the client for exactly one volume. Both surfaces bind to that volume. mountOS needs no multi-tenant gateway fleet to deploy. See Clients.

The region database holds the durable copy of the tree, forks, blocks, and session state. This database supports MySQL and PostgreSQL wire protocols. S3-compatible stores and Azure stores hold the file content. The account's storages point at these stores. mountOS supports AWS S3, Google Cloud Storage, Backblaze B2, MinIO, Azure Blob Storage, and an on-prem tier as store types. An account can have one or many stores per region. Storage nodes hold parts on local block devices. That same object storage backs those devices.

Protocols on the wire

Discovery resolves a volume to its owning metadata cluster. After discovery, metadata nodes are cluster-scoped. Therefore a session talks only to the metadata cluster that owns its volume.