Tenant Architecture #

A tenant is a logical workload namespace representing an application or service domain, defined entirely as code — its network, its workloads, and its DNS — so it can be rebuilt from scratch against the substrate.

What is a Tenant? #

Tenants are the workload layer that runs within sites, on top of substrate infrastructure. A tenant is the accountable owner of what an application has on the site: its workloads, its edge devices, or both. Every edge device belongs to a tenant, and a tenant may have devices and no workloads ( ADR-0032):

graph TB
    subgraph tenants["Tenants (Workloads)"]
        T["eds · tdemo"]
    end
    subgraph substrate["Substrate Infrastructure"]
        S["Network · Compute · Management Plane · Control Plane"]
    end
    tenants -->|deployed on| substrate

The tenants that exist today are eds — the LP jacket stand application, whose workload drives an RGB strip from album cover art — and tdemo, the reference tenant a new tenant is copied from.

Key Properties #

Tenants Live Within Sites #

Tenants:

Run within sites, not defining them
May be deployed to one or more sites
Are isolated from other tenants
Share substrate infrastructure (network, compute, and both planes)

What Tenants Run #

Tenant work is application development, experiments and sandboxes, and short-lived or rebuildable workloads — anything that tolerates churn. It runs in one of two places the substrate offers:

VMs on the tenant hypervisor, declared by the tenant and built by the substrate on its behalf
A borrowed Pi lab host, when the project needs real hardware rather than a VM ( Compute → The Pi lab)

Tenant Networks Are Virtual Overlays #

A tenant’s network is a virtual overlay owned by the tenant compute domain (the tenant fabric), not a physical VLAN on the core router. The tenant owns its own Layer 3 — subnet, gateway, routing, and isolation — while the core router acts only as the perimeter (NAT, internet egress, and tenant↔management policy on a transit boundary). Creating a tenant creates a virtual network; it requires no change to physical switching. This is the model established by ADR-0001; see Networking for the full model.

Code Is the Source of Truth #

Every tenant supplies the IaC and CaC needed to rebuild itself from scratch against the substrate, and it supplies them from its own repository — deevnet-tenant-<name>, not a directory inside a substrate repo ( ADR-0006). Nothing about a tenant is precious hand-clicked state: its workloads and the names in front of them are declared in the tenant’s own code, and the network they land on is built for it by the control plane from that same declaration. Rebuilding a tenant reconstitutes it whole — network, workloads, and records — which is what keeps the substrate stateless and the tenant portable.

Intent Over Identity #

Tenants express intent (what’s running), not identity (what the host is):

A host has stable identity (hostname, MAC, IP)
A tenant workload can move between hosts
Services are addressed by DNS, not by host

DNS Naming Pattern #

A tenant service has one name for its whole life, with no site in it ( ADR-0040):

service.tenant.deevnet.net

Example: console.eds.deevnet.net

console — the service
eds — the tenant
deevnet.net — the domain

Each site it runs on, or is headed for, adds a site name beside it: console.eds.mobile.deevnet.net. Both are in the service’s certificate, so a move to a site already named changes nothing a client trusts.

Site-less names resolve only where a tenant runs in production. The Mobile Factory builds tenants and answers a tenant only under its site zone, <tenant>.mobile.deevnet.net; a tenant is reached and tried there by its site names, and takes its site-less names to the site it is deployed to.

Some names are not a tenant’s to take. A tenant may not be named after a site, a site code, a retired zone, a global alias or a site broker (home, mobile, mgmt, dvnt, dvntm, mqtt, artifacts, …), and device is reserved for its devices’ names. The provisioning API refuses them.

Tenant vs Site #

Aspect	Site	Tenant
Purpose	Infrastructure boundary	Workload namespace
Contains	Network, compute, management and control planes	Applications, services
Lifetime	Long-lived, stable	May be created/destroyed frequently
Provisioning	Procedural configuration, from inventory	Declarative, through the provisioning API
Example	`mobile`	`eds`, `tdemo`

Multi-Site Tenants #

A tenant is built at the Mobile Factory and may be deployed to another site. Its service names stay the same; the site it runs on adds a site name, and that site answers its site-less names ( ADR-0040 §1, §2). At another site a tenant runs on a Deevnet Pi, which is its devices’ broker ( ADR-0039 §8).

Only mobile is built today; home is a reserved zone ( Limits).

The Tenant Contract #

A tenant is defined by the contract it satisfies with the substrate: the tenant declares what is genuinely its own, and the substrate builds the rest. A tenant holds no substrate credential, and nothing recurring needs a substrate commit. The contract itself, with how far each promise is enforced today, is Substrate and Tenant.

Child Documents #

Networking — Tenant network isolation via the overlay fabric
Shared Tenant Services — Substrate-run services tenants consume, and the rules for consuming them
Management — Tenant lifecycle and observability
Substrate and Tenant — The boundary between the two, and what crosses it