Tenant Model on Deevnet IoTaaS

ADR-0034: Tenants Deliver Their Own Code

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0034: Tenants Deliver Their Own Code, and Deliver It Again #


Status	Accepted (2026-10-05): already how the platform works. CHG-0028 gave tenants their own login on their workloads, and `eds` runs its services this way (since 2026-09-28)
Date	2026-10-05
Scope	How a tenant’s application code and settings reach its workloads, and how they come back after a workload is lost. Not how the workload itself is built ( ADR-0015), and not how a tenant logs in ( ADR-0028).
Supersedes	ADR-0017: How Tenant Code Reaches a Tenant Workload, whole
Related	ADR-0010: Tenants Consume Platform Services, ADR-0018: Operator Access to Tenant Workloads, ADR-0021: Tenant Secrets (depended on ADR-0017; to be revisited), ADR-0033: Code Is the State

Context #

ADR-0017 planned an unattended pull. A tenant would declare its workload’s configuration to the API in a Deevnet schema, and an agent in the workload would fetch it at first boot through an SMBIOS pointer. It forbade any push. None of it was built.

ADR-0033: Code Is the State

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0033: Code Is the State, for the Substrate and for Every Tenant #


Status	Proposed. Accepted when the change that moves device secrets into tenant code is built, and a tenant has been rebuilt from its repository with no restore
Date	2026-10-05
Revised	2026-10-06: what it said about tenant indexes corrected to match the code ( 2026-10 review, T3)
Scope	Where the authoritative copy of everything the site runs lives, and how the site and its tenants recover with no backup on the path. Covers tenant state, device secrets, the Deevnet API’s database and audit log, and tenant buckets.
Supersedes	ADR-0014: Tenant State Durability, whole
Amends	ADR-0012: IoT Platform API §4 (the authoritative copy of a device secret), §5 (the restore source) and its audit-log paragraph; ADR-0015: Tenant Onboarding Through the API (the API’s database is a working copy of the registry); ADR-0026: Object Storage §3 and §4 (no replica)
In conflict with	ADR-0016: Substrate Secrets in OpenBao (OpenBao’s data is kept data) and ADR-0025 §7 (Keycloak’s is); both to be revisited, see Consequences
Related	ADR-0007: Terraform State Custody §5, ADR-0010: Tenants Consume Platform Services §4, ADR-0021: Tenant Secrets, ADR-0025: Identity Directory §7, ADR-0031: Deevnet PKI §6

Context #

The site was designed so that code rebuilds everything. The substrate is rebuilt from inventory and its vault. A tenant is rebuilt from its own repository. ADR-0007 §5 made it a rule for tenants: “no tenant declares a resource whose value cannot be re-derived from code”.

ADR-0028: Tenant Workload Login

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0028: A Tenant Logs In to Its Own Workloads With Its Own Key #


Status	Accepted (2026-09-27): built and proven by CHG-0028
Date	2026-09-27
Scope	How a tenant gets a shell on a workload it owns: which account, which key, which template, and from where. Not how code arrives unattended (ADR-0017), and not people’s identities (ADR-0025).
Answers	ADR-0018: Operator Access to Tenants, open question 3
Related	ADR-0015: Tenants Are Built Through the Deevnet API §12, ADR-0017: How Tenant Code Reaches a Tenant Workload, ADR-0025: Identity Directory §5, CHG-0028

Context #

A tenant can build a workload but cannot log in to it.

ADR-0021: Tenant Secrets

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0021: Tenants Keep Runtime Secrets in Their Own OpenBao Namespace #


Status	Proposed
Parked	2026-10-06: tenants keep their secrets as code for now: encrypted in their own repositories, merged into the settings they push ( ADR-0034). This record stays Proposed as an optional service for a tenant that needs rotation without a redeploy, per-workload revocation or a read audit. Its delivery through ADR-0017’s channel becomes the tenant pushing each workload’s AppRole credential ( 2026-10 review, S1)
Date	2026-09-21
Scope	Where a tenant’s own runtime secrets live, such as a third-party API key its backend service calls with, how they reach the workload that needs them, and who holds the authoritative copy. Not device credentials, and not how the workload itself is filled with code.
Extends	ADR-0016: Substrate Secrets in OpenBao, whose §8 left “tenant namespaces” out and said they need their own record. This is that record.
Related	ADR-0010: Tenants Consume Platform Services §4, ADR-0012: IoT Platform Services Through a Deevnet API and Terraform Provider §4, §8, §9, ADR-0014: Tenant State Durability, ADR-0015: Tenants Are Built Through the Deevnet API, ADR-0017: How Tenant Code Reaches a Tenant Workload, ADR-0020: Direct Device Access to Tenant Services

Context #

A tenant has secrets of its own, and nowhere to put them #

A tenant’s backend service calls out: a weather API, a notification service, a payment provider. Each call carries a key the tenant got from that provider. The substrate did not issue it and cannot re-derive it. The service needs it at runtime, on a workload the substrate built.

ADR-0017: How Tenant Code Reaches a Tenant Workload

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0017: How Tenant Code Reaches a Tenant Workload #


Status	Superseded by ADR-0034: Tenants Deliver Their Own Code: the tenant pushes its own code over SSH, and pushes again after a workload is lost; unattended delivery is out of scope. Never accepted
Date	2026-09-18
Revised	2026-09-18, twice, before review. First written as a single choice between delivery mechanisms, with tenant-authored cloud-init user-data recommended; that draft argued the wrong layer. Rewritten to separate the tenant-facing contract (§1, settled) from the substrate-side mechanism (§2, open). Then revised again once both halves of the leading mechanism were tested rather than assumed, adding the measured SMBIOS limit and §3, the fetch rule that keeps ADR-0012 provisioning-only.
Scope	How a tenant’s own application code and configuration arrive on a tenant workload, and how they are kept current — not what the code is, and not how the workload itself is built
Extends	ADR-0010: Tenants Consume Platform Services, which says tenants own their code but does not say how it is delivered; ADR-0015: Tenants Are Built Through the Deevnet API, which builds the empty workload this decision fills
Related	ADR-0001: Tenant Network Fabric, ADR-0003: Tenant Egress on a Single-Member Fabric, ADR-0011: Edge Devices Are Application-Owned, ADR-0012: IoT Platform Services Through a Deevnet API and Terraform Provider, ADR-0016: Substrate Secrets in OpenBao, ADR-0018: Operator Access to Tenant Workloads

Context #

The substrate can build a workload but cannot fill one #

ADR-0015 made tenant building complete: a tenant declares deevnet_workload and gets a running Fedora VM with an address, a name, DNS and egress. What arrives is an empty machine. Nothing in the substrate puts an application on it, and nothing says how a tenant should.

ADR-0015: Tenants Are Built Through the Deevnet API

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0015: Tenants Are Built Through the Deevnet API #


Status	Accepted
Amended by	ADR-0033: Code Is the State (Proposed): the API’s database is a working copy of the registry; each tenant’s repository names the tenant and its index
Accepted	2026-09-19, recording what CHG-0010 settled on 2026-09-17: the API was deployed and both live tenants were rebuilt entirely through it. The record sat at `Proposed` after it had already been built and proven, which the status was not saying.
Date	2026-09-17
Revised	2026-09-17, before review. First written as onboarding only; widened so that everything that builds a tenant (its network, workloads and DNS records) is behind the API and tenants hold no substrate credential (§11–§14). Admission by enrollment token (§10). Secrets handling moved to ADR-0016.
Scope	Who allocates a tenant’s index, who builds a tenant’s network, workloads and names, what a tenant holds, and where the record of tenants lives
Extends	ADR-0012: IoT Platform Services Through a Deevnet API and Terraform Provider, whose API and provider become the way every tenant is created, not only the way it registers devices
Supersedes, in part	ADR-0002: Tenant Fabric Numbering, where it says allocation is recorded in `TENANTS.md` (the numbering itself stands); ADR-0006: Tenant Code Boundary §1 (the module consumed by tag), §2 (the attachment rendered into the repository) and §3 (the reference implementation that cannot be applied). A tenant still lives in its own repository.
Related	ADR-0003: Tenant Egress on a Single-Member Fabric, ADR-0004: Tenant DNS Publication, ADR-0005: Tenant Zone Apex Ownership, ADR-0007: Terraform State Custody, ADR-0010: Tenants Consume Platform Services, ADR-0014: Tenant State Durability, ADR-0016: Substrate Secrets in OpenBao

Context #

Onboarding today is a substrate commit and five automation runs #

A tenant is created in two halves. The substrate half runs once:

ADR-0014: Tenant State Durability

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0014: Tenant State Is Kept Data, Copied Away From What It Restores #


Status	Superseded by ADR-0033: Code Is the State: tenant state is re-derivable again, so no copy is kept and no restore is on the recovery path. Never accepted
Date	2026-09-16
Scope	How the tenant state store’s contents survive losing the host, disk or hypervisor they live on, and how that copy is kept apart from the platform API’s database, which the state restores
Extends	ADR-0007: Terraform State Custody, which offered the store and recorded its durability as “the weakest part of the decision”; ADR-0013: Management-Hypervisor Services Run as Containers on Domain VMs, whose §1 and §6 put the store and the API’s database in one VM
Extended by	ADR-0026: Object Storage — the store is defined by a contract, runs pgsty/silo, and also offers tenant buckets (Proposed)
Related	ADR-0010: Tenants Consume Platform Services §4, ADR-0012: IoT Platform Services Through a Deevnet API and Terraform Provider §4 and §5, Substrate Storage, Limits

Context #

ADR-0007 sized state loss as a rebuild #

When the store was offered, losing state was cheap, and ADR-0007 said exactly how cheap:

ADR-0012: IoT Platform Services Through a Deevnet API and Terraform Provider

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0012: IoT Platform Services Through a Deevnet API and Terraform Provider #


Status	Accepted
Amended by	ADR-0033: Code Is the State (Proposed): the authoritative copy of a device secret is the tenant’s code, not its state (§4); the restore path reads it from there (§5); the audit log is no longer the record of change, git is. ADR-0035: A Fixed Address for a Tenant’s Device: a device’s registered MAC is what a fixed address is reserved for, and the API reserves one when the tenant asks (§3, open question 3). ADR-0038: Tenants Update Their Own Devices: “firmware release hosting” and “OTA” are not later layers of the platform (§3); a tenant updates its own devices. “Jobs” stays
Accepted	2026-09-18, at the close of CHG-0013 — when the Wi-Fi half had been built, deployed and proven on the AP, not when it was written. The broker half (§8) and the device registry (§3) are decided but not built.
Date	2026-09-14
Reviewed	2026-09-14. Four of the original open questions were decided in review: the broker (§8), secrets after a rebuild (§4, §5), provider distribution (§7) and credential delivery (§9). The sources are quoted in each section. Revised the same day: the API is provisioning-only, and the broker authenticates from its own auth database (§8). Open questions 2, 5 and 6 were then answered: where the API, its database, the broker’s auth database and the Omada controller run (§7, ADR-0013). Revised 2026-09-16: tenant workloads get broker accounts too (§3), and topic confinement is decided (§10, Open question 4). Revised 2026-09-18 by CHG-0013, which built the Wi-Fi half: a key is per tenant per trust class rather than per device (§3), v1 ships on `DVNTM-IOT` only (§3), the drift report names profiles rather than counting keys (§6), and `DVNTM-IOT` turned out to be a creation rather than a migration (Consequences).
Scope	How a tenant reaches an IoT platform service whose own interface can’t confine it to its scope, and what the substrate builds so it can
Extends	ADR-0010: Tenants Consume Platform Services §1 and §3, which require a scoped service but don’t say how one is built when the backing software can’t scope itself
Answers, in part	ADR-0011: Edge Devices Are Application-Owned and Platform-Attached open questions 1 (scoped registration) and 3 (Wi-Fi keys — answered per tenant per trust class, not per device; §3)
Related	ADR-0004: Tenant DNS Publication, ADR-0006: Tenant Code Boundary, ADR-0007: Terraform State Custody, ADR-0009: Network Device Configuration Is Inventory-Owned and Controller-Applied, ADR-0013: Management-Hypervisor Services Run as Containers on Domain VMs, ADR-0014: Tenant State Durability (§4 and §5 depend on it)

Context #

The rule has no mechanism for IoT #

ADR-0010 set the test for a platform service: does this recurring tenant action need a substrate commit? For IoT, two actions fail it today:

ADR-0010: Tenants Consume Platform Services

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0010: Tenants Consume Platform Services; They Are Not Woven Into the Substrate #


Status	Accepted
Accepted	2026-09-19. The principle is the test every later record applies, and two of the three services that failed it have since been remedied. It sat at `Proposed` while ADR-0012, which extends it, was already `Accepted` — an inversion both records had noticed and neither had fixed.
Date	2026-09-13
Scope	What makes a substrate-run service safe for a tenant to depend on, and where issuing a tenant something ends and becoming part of it begins
Extends	ADR-0004: Tenant DNS Publication §5, which drew the onboarding-versus-recurring line for DNS only
Extended by	ADR-0012: IoT Platform Services Through a Deevnet API and Terraform Provider — how §3 is met when the backing service can’t confine a tenant itself. ADR-0015: Tenants Are Built Through the Deevnet API — the same principle applied to building a tenant at all, not only to the services it consumes
Related	ADR-0006: Tenant Code Boundary, ADR-0007: Terraform State Custody, ADR-0011: Edge Devices Are Application-Owned and Platform-Attached

Context #

Three records have drawn the same line, each for one thing, and none of them says it is a rule:

ADR-0007: Terraform State Custody

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0007: Terraform State Custody #


Status	Accepted
Date	2026-09-03
Scope	Where Terraform state lives, who may read it, and what protects it
Depends on	ADR-0006: Tenant Code Boundary
Extended by	ADR-0014: Tenant State Durability — how the store’s contents survive losing their host, once state holds device secrets (Proposed); ADR-0026: Object Storage — the store is defined by a contract, runs pgsty/silo, and also offers tenant buckets (Proposed)

Context #

State custody was never decided. architecture/tenant/building.md offered three bullets —

ADR-0006: Tenant Code Boundary

Mon, 01 Jan 0001 00:00:00 +0000

ADR-0006: Tenant Code Boundary #


Status	Accepted
Date	2026-09-03
Scope	Where a tenant’s code lives, and what it needs from the substrate to stand alone
Depends on	ADR-0001: Tenant Network Fabric, ADR-0002: Tenant Fabric Numbering
Extends	ADR-0004: Tenant DNS Publication §5

Context #

ADR-0004 §5 drew a line that has held up well: onboarding may touch substrate; the recurring lifecycle may not. Adding a record, rebuilding, destroying — those are terraform apply and nothing else.