CHG-0013: Tenant Wi-Fi PPSK Keys on Deevnet Infrastructure Platform

1. Recon

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

Phase 1: Recon #

Read-only, unauthenticated, no writes. Done 2026-09-18, before any code was written, because three of its answers changed what the automation had to do.

Run #

curl -sk "https://10.20.99.40:8043/v3/api-docs/00%20All" -o omada-spec.json

1,856 paths, 3,360 schemas, controller 6.3.0.45. No credentials are needed: the spec endpoint is unauthenticated, the same one omada-wireless.yml’s preflight already reads.

Verify #

The five questions below are answered, and each is written down here rather than inferred later.

2. Substrate

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

Phase 2: Create the profile and the SSID #

Needs a maintenance window. This is the only phase that touches a live radio.

Merged: ansible-collection-deevnet.net #26, ansible-inventory-deevnet #41.

What changed in inventory #

 iot:
 # ...
 wifi_ssid: "DVNTM-IOT"
 wifi_security: ppsk
 wifi_ppsk_profile: "DVNTM-IOT"

and deevnet_wifi_psk.iot was deleted. A segment that says nothing about wifi_security keeps a shared key, so the other three wireless segments needed no edit at all — which is what keeps this change away from DVNTM.

3. API

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

Phase 3: The API issues keys #

Merged: deevnet-provisioning-api #9 (v0.3.0), ansible-collection-deevnet.mgmt #29.

Blocked on the Owner creating the API’s own Open API client. Until then v0.3.0 deploys happily with Wi-Fi keys off — that is deliberate, and tested.

Run #

Owner, in the controller UI: Global View → Settings → Platform Integration → Open API. Create a second client, separate from Ansible’s.
Vault it as vault_omada_api_client_id / vault_omada_api_client_secret in group_vars/network_controllers.
In mobile/group_vars/deevnet_api/vars.yml, set deevnet_api_omada_url and add omada_client_id / omada_client_secret to deevnet_api_backends, read cross-group the way the router key already is.
Stage and deploy:

cd deevnet-provisioning-api && git tag v0.3.0 && make stage
cd ../ansible-collection-deevnet.mgmt && ansible-playbook playbooks/deevnet-api.yml

Verify #

curl -s https://api.mobile.deevnet.net/version # v0.3.0
# operator token, against a scratch tenant:
curl -sk -H "Authorization: Bearer $OP" -X POST \
 https://api.mobile.deevnet.net/v1/tenants/tdemo/wifi-keys \
 -d '{"name":"scratch","trust_class":"iot"}'

The response carries ssid: DVNTM-IOT, vlan: 30 and a psk.
The controller UI shows one key in the DVNTM-IOT profile, named tdemo-scratch, bound to VLAN 30.
DELETE removes it, and the profile is empty again.
Grep the API logs for that psk and find nothing.
Restart the API and issue another key, to exercise a fresh token.

Outcome — ran 2026-09-18 #

Deployed and issuing keys. GET /version returns v0.3.0 (commit c7afbe9), readyz reports the database ok, and the deploy was failed=0 with 14 changed tasks — including the KV secret rewrite that gave the API its Omada credential.

4. Tenant

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

Phase 4: A tenant issues its own key #

Merged: terraform-provider-deevnet #3.

No hardware needed. This phase is where the restore guarantee is proven, and it is proven by breaking it on purpose.

Run #

In the tenant’s own Terraform, for example /srv/eds/infra/deevnet-tenant-eds:

resource "deevnet_iot_wifi_key" "devices" {
 tenant = deevnet_tenant.this.name
 name = "devices"
 trust_class = "iot"
}

output "wifi" {
 value = {
 ssid = deevnet_iot_wifi_key.devices.ssid
 psk = deevnet_iot_wifi_key.devices.psk
 }
 sensitive = true
}

Build and install the provider, delete the stale lock, then apply:

5. A client joins

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

Phase 5: A client joins with a tenant’s key #

Needs someone at the site with a wireless client. Everything before this is remote.

What this phase proves is narrow and worth stating: that a tenant’s key authenticates, and that the key decides the VLAN. Any wireless client does that. It does not have to be the device the tenant will eventually run.

Run #

Get the credential from the tenant, not from the controller:

6. Close-out

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

Phase 6: Close-out #

Run #

Correct the pages this change makes wrong or newly right:
- architecture/substrate/networking.md — the Wireless section names no SSIDs and no security model. It should carry the four, and say that on DVNTM-IOT the key decides the VLAN.
- platforms/network/access-point/_index.md — “SSID Design” lists Management / IoT / Guest, which is not this site, and points at a standard that documents neither. Replace with the four real SSIDs and the ownership line: inventory owns the SSID and the profile, the API owns the keys inside it.
- platforms/network/network-controllers/_index.md — record the second Open API client and what it is for.
- runbook/recovery/console-recovery/wireless-ap.md §6–7 — drop the standalone-UI and make migration-omada-ssids assumptions; recovery is make wireless APPLY=1 ADOPT=1 then make wireless APPLY=1. The §7 check of DVNTM-IOT now actually works.
That recovery page also gets the sentence that matters most operationally: recovery does not re-issue tenant keys. They survive an AP rebuild in the profile, and if the profile itself is lost each tenant runs terraform apply and gets the same key back — so no device visit. ADR-0012 §5, made concrete.

Undo

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

CHG-0013: Undo #

Written before the change ran. Each phase is reversible on its own, and the order here is the reverse of the order they run in.

Phase	Reversal	Leaves behind
5. Device	Reflash the stand’s previous configuration	Nothing depends on the stand
4. Tenant	`terraform destroy -target=deevnet_iot_wifi_key.devices`, or remove the block and apply	The key is revoked at the controller
3. API	Redeploy `deevnet_api_version: v0.2.6`; delete any test key from the profile	Unsetting `deevnet_api_omada_url` alone stops key issuance without a rollback
2. Substrate	Controller UI: delete the SSID `DVNTM-IOT`, then the PPSK profile `DVNTM-IOT`. `git revert` the inventory commit, restoring `deevnet_wifi_psk.iot`, then `make vault`	The VLAN 30 network object may stay; it is harmless and every other segment has one
1. Recon	None — nothing was written

What cannot be undone #

A revoked key. Once a tenant’s key is deleted and a new one issued, every device flashed with the old one needs a physical visit. Reversing phases 3 and 4 in the order above avoids this: destroy the Terraform resource, which revokes one key deliberately, rather than rolling the API back and leaving keys stranded in a profile nothing manages.