Shared Tenant Services #

Purpose #

Shared tenant services are the services the substrate runs for tenants, so that each tenant doesn’t have to run its own. The substrate owns the service; the tenant owns what it puts in.

Some of them can’t exist inside a tenant at all. A tenant accepts no inbound connection from a device, from another tenant, or from outside the substrate, so a device on the IoT segment couldn’t reach a broker running inside one. And a tenant zone needs a parent that only the substrate holds.

The one exception is the operator: the substrate’s management and trusted networks can reach tenant workloads, so that an operator who owns every tenant can build and debug them ( ADR-0018). That path is for operating a workload, not for delivering what runs on it, and it changes nothing above — a device still has no route to a tenant.

1. Where They Run #

Shared tenant services are the tenant-facing half of the substrate’s control plane, grouped into domains the same way as the substrate’s own services. They never share a host with those services:

• Tenants must not reach the management segment, where the substrate’s own services sit. A service tenants use therefore can’t sit there, even though the substrate owns it.
• The two have different change cadences. Substrate services change often; tenant-facing ones should be boring. Keeping them on separate hosts means a restart among the substrate’s services can’t take tenant name resolution with it ( ADR-0004).

The segmentation standard says tenant networks must not reach the management segment directly, and neither may the IoT backend segment.

Where one shared tenant service has to write to another on a different segment, a narrow rule allows that one host to reach that one port, and nothing else. An example is the platform API writing a device’s broker account.

2. What a Tenant Can Consume #

The services themselves — what each domain holds, which segment it sits on, and why — are described in Control Plane. What a tenant gets from each is in the contract. Every one of them is declared through the provisioning API, and the resources a tenant writes for each are in the Terraform provider.

Two things a tenant does not get, and should not expect:

• A path from a device into its network. A device the tenant owns reaches it through a service on IoT Backend that both sides dial out to, never by joining the tenant’s overlay. See Edge Devices → Access.
• A substrate credential of any kind. Everything above is reached with the tenant’s own token, issued by the API, or with a key scoped to exactly one zone or one prefix.

3. How Tenants Consume Them #

The rule that governs every shared tenant service ( ADR-0010, Proposed):

A tenant may depend on the substrate; the substrate must not come to contain the tenant.

What makes a substrate-run service safe for tenants to depend on:

1. The substrate runs it, as substrate code applied by substrate automation.
2. A tenant is bound to it once, at onboarding, when the substrate issues a credential, a namespace or both.
3. The tenant then uses it through the service’s own interface. No recurring tenant action needs a change to the substrate.
4. The service confines each tenant to its own scope. Where the backing software can’t do that, the service isn’t offered as self-service until something in front of it can.
5. Whatever a tenant puts into it can be rebuilt from the tenant’s own code. The substrate may host that content, but it never holds the only copy.

The test for any proposed service:

Does this recurring tenant action need a substrate commit? Onboarding may. Nothing that recurs may.

3.1 Onboarding versus lifecycle #

Binding a tenant to a shared service is a substrate act, done once. Everything after that is the tenant’s own act, through the service’s interface.

4. The Server Is Substrate; the Content Is Tenant #

Shared tenant services are provisioned by substrate automation, run from the builder. Tenant infrastructure tooling never provisions them, even though they exist only to serve tenants.

This prevents a bootstrap cycle. The state store tenants keep their state in is built by automation that keeps no state in it. If the store were built by the tooling that uses it, the store’s own state would have nowhere to live ( ADR-0007).

5. Tenant Content Is the Tenant’s to Restore #

• What a tenant writes into a shared service can be rebuilt from the tenant’s own code. Records come from the tenant’s infrastructure code, and so do device registrations.
• A service’s database is hosted tenant state, not the source of truth. If a substrate rebuild loses it, each tenant re-applies its own code to restore it.
• A substrate rebuild never costs a device visit. Secrets a device already holds are restored from the tenant’s state, not regenerated ( ADR-0012 §5). That makes tenant state data worth keeping, and how the store keeps it is ADR-0014 (Proposed).
• A tenant may decline a service wherever declining is possible, as it can for the state store. The service documents what declining costs.

6. Isolation Model #

Isolation here means no tenant code runs in these services. A service still serves tenants, but no tenant can execute in it or write outside its own scope.

Tenant DNS and the state store sit in different domains because they fail differently. If tenant DNS is down, tenant names stop resolving. If the state store is down, no tenant can change anything.

7. Invariants #

Shared tenant services are considered correct when:

• they never share a host with the substrate’s own services
• no tenant can reach the management segment to use one
• no recurring tenant action needs a substrate commit
• tenant content held in a shared service is never the only copy
• no tenant code runs in them

If rebuilding the substrate loses something a tenant can’t restore from its own code, the architecture is incorrect.