Tenant Admission #

The operator’s half of creating a tenant. The operator admits a name; the tenant then declares everything else itself, through the Deevnet API ( ADR-0015). The tenant’s half is Tenant Operations.

Admission is the only substrate act a new tenant needs. The operator never edits an inventory file to make a tenant, and the tenant never holds a Proxmox credential, a vault password or an index.

Before you start #

1. Admit the name #

From ansible-collection-deevnet.mgmt on the Builder:

make admit NAME=mabell                          # or bind the Wi-Fi key to one laptop:
make admit NAME=mabell MAC=AA-BB-CC-00-11-22

admitted mabell: expires 2026-09-26T…Z, Wi-Fi DVNTM-TD
handover details: /home/<you>/mabell-admission.txt (mode 0600)

The terminal shows nothing secret. ~/<name>-admission.txt holds everything the tenant is handed: the enrollment token and its expiry, the API endpoint, the DVNTM-TD Wi-Fi key, the Deevnet Root CA’s URL and fingerprint, and the tenant’s first three steps. It is written to be read and passed on by a person.

The Wi-Fi key is the tenant’s own DVNTM-TD key ( ADR-0029): a tenant needs that network to reach the API at all, so its first key comes with the admission. MAC= binds it to one laptop. When the tenant creates itself, the key becomes its own Wi-Fi key admission.

2. Hand over four things #

The tenant needs exactly these, and nothing else from the substrate. All four are in ~/<name>-admission.txt:

1. the enrollment token
2. the API endpoint, https://api.mobile.deevnet.net
3. the DVNTM-TD Wi-Fi key ( §3)
4. the Deevnet Root CA, at https://downloads.mobile.deevnet.net/deevnet-root-ca.pem, with its fingerprint

The token is bound to the name. Presenting it for a different name spends it and answers 401, so a mistyped name costs a new admission.

Delivery is by hand today. ADR-0012 §9 says the token is delivered age-encrypted to the tenant’s own key; that tooling is not built. Until it is, hand the token over on a channel you would trust with a password, and admit close to when the tenant will apply — an unspent token is a credential for 72 hours. Delete ~/<name>-admission.txt once it is handed over: after the first apply the Wi-Fi key in it is the tenant’s to keep, not yours.

3. Where the tenant applies from #

A tenant’s applies need OpenBao open too, so they run inside a work session. While it is sealed, every call with the tenant’s token answers 503, OpenBao is sealed or unreachable; tenant work waits until it is opened, and nothing changes; the tenant applies again once the session is open.

Every apply has to reach the API, and after the first one the state store too. Give the tenant the DVNTM-TD key, the one in the admission’s wifi, not a shared one: that segment reaches the API, the state store, the broker, the log store, Grafana and SSH on tenant workloads, and nothing else ( CHG-0022, CHG-0024). Guest is internet-only and IoT cannot reach the API. A trusted seat still works, but it reaches the management plane, so don’t offer it to a visitor. See Before You Start for how the tenant side reads this.

You have no standing access to a tenant’s workloads ( ADR-0028). They clone the fedora-tenant-* template, which carries no a_autoprov, and trust only the keys in the tenant’s ssh_keys. To help on one, the tenant adds your public key and replaces the workload.

Rotating a tenant’s Wi-Fi key #

A tenant’s DVNTM-TD password is handed over once: the API never returns a key’s password again, so a lost one is replaced, not recovered. Rotate the key to give it a new password — after a loss, a possible leak, or on a schedule:

make rotate-wifi-key NAME=<tenant>                 # the admission key
make rotate-wifi-key NAME=<tenant> KEY=<key>       # any other key

It shows the key’s trust class, SSID and MAC binding, asks for the tenant’s name, then deletes the key and creates it again under the same name and settings. The new password goes to ~/<tenant>-wifi-<key>.txt (mode 0600), to hand over like an admission. The old password stops working on every device that used it; each one forgets the network and joins again.

Only the admission key is the operator’s to rotate. It came with the admission and the tenant’s Terraform does not declare it. A key the tenant declares, such as its devices’ key, lives in the tenant’s state, and rotating it here would leave that state holding the old password: the tenant rotates its own with terraform apply -replace=<the key's resource>.

Reissuing a state secret #

A tenant that has lost the keys to its own state gets a new state secret from the operator. The keys live inside the state they unlock, and the site never hands back the stored secret, so a new one is the only way back in. OpenBao must be open, in a work session:

make reissue-state-secret NAME=<tenant>

It asks for the tenant’s name, then has the API mint a new secret and set it on the state store. The old secret stops working for everyone who holds it, CI included. The new one goes to ~/<tenant>-state-secret.txt (mode 0600), as the two lines of the tenant’s .backend.env, to hand over like an admission.

The tenant must not restore from its old state afterwards. That state still holds the old secret, and a restore sends back the secrets in state, which win. A restore from it would put the old secret back and lock the tenant out again.

What the substrate does on the first apply #

The index is the tenant’s number in all of it — subnet, VXLAN VNI, log account — so it is allocated once, against both the registry and the live fabric, and never by hand.

To confirm the fabric side, pvesh get /cluster/sdn/zones on the tenant hypervisor shows vrf_<tenant> with its own VNI.

Operator-only calls #

When it goes wrong #