Deevnet Software on Deevnet IoTaaS

Deevnet API

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

Deevnet API #

Fills the provisioning API role at the substrate–tenant boundary: the one interface a tenant uses, which builds on the substrate what the tenant declares ( ADR-0012, ADR-0015). It is provisioning-only: nothing at runtime depends on it being up.


Repository	`deevnet-provisioning-api`, Go ( version)
Runs on	`dv02prv001v01`, 10.20.25.20, as two podman containers under systemd: `deevnet-api` (on the host’s loopback address; tenants reach it at `https://api.mobile.deevnet.net` through the host’s service proxy) and `deevnet-api-db` (PostgreSQL, on a private podman network, no published port)
Deployed by	`deevnet.mgmt` role `deevnet_api`: `ansible-playbook playbooks/site.yml --limit deevnet_api`. The image is built and staged on the Builder (`make stage`) and pushed to the host, never pulled. The role ends by checking `/readyz` and that `/version` is the pinned version
Contract	`api/openapi.yaml` in the repository (OpenAPI 3.1), published as the API reference
Documentation	deevnet.github.io/deevnet-provisioning-api, with release notes for every version

What it exposes #

The API has its own documentation site, Deevnet API. Its reference lists every route, request and response, and is rendered from the OpenAPI specification in the repository, which a test holds to the code.

Terraform Provider

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

Terraform Provider #

deevnet/deevnet: how a tenant declares itself to the Deevnet API. It is the tenant side of the substrate–tenant boundary.


Repository	`terraform-provider-deevnet`, Go, terraform-plugin-framework ( version)
Runs on	Tenant laptops and the Builder. It is not in the public registry
Distributed by	`make release-build`: zips for macOS and Linux on amd64 and arm64, with `SHA256SUMS`, `install-provider.sh` and `tenant-check.sh`. `make stage` puts them on tenant downloads
Configuration	`DEEVNET_API_ENDPOINT`, `DEEVNET_API_TOKEN`, `DEEVNET_API_CACERT`
Documentation	deevnet.github.io/terraform-provider-deevnet, with release notes for every version

Why Terraform for tenants #

The substrate is configured by procedural automation; tenants use Terraform. A tenant is created and destroyed often, so its tooling has to track what it owns, plan a change before making it, and destroy cleanly. Terraform does all three, and it is what a tenant developer is likely to know already. The substrate is configured rather than created, and gains nothing from state it would then have to guard.

Log Bridge

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

Log Bridge #

Carries device log lines from the MQTT broker into each tenant’s device-log partition, (index, 2), in the tenant log store ( ADR-0027 §4, CHG-0021). A device publishes; it never talks to the log store.


Repository	`deevnet-log-bridge`, Go ( version)
Runs on	`dv02msg001v01`, beside the broker, as the `deevnet-log-bridge` container; `deevnet.mgmt` role `log_bridge`. Also on the Pi backend image
Reads	MQTT `+/log/#` (`<tenant>/log/<device>`), QoS 1, persistent session, as the subscribe-only account `substrate-log-bridge`
Writes	vmauth on the log store, with the tenant named in `X-Deevnet-Tenant`, under one store token
Health	`/healthz` on `127.0.0.1:9099`

It keeps no state. Its queue holds 10,000 lines and drops the oldest when full, logging the loss. Failed batches are retried with backoff; batches the store refuses are not. It is in no device’s path: if it stops, devices keep publishing, and their lines queue in its persistent broker session up to the broker’s limits.

Tenant Egress Agent

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

Tenant Egress Agent #

Keeps a default route inside every tenant VRF on the fabric exit node, so each tenant’s internet traffic leaves through the perimeter ( ADR-0015 §7). Proxmox does not model that route, and the alternative was to give the API root on a hypervisor. Instead the node pulls the tenant list and renders the route itself.


Source	`ansible-collection-deevnet.net`, role `tenant_egress_agent`: a Bash script with embedded Python
Runs on	`dv02hyp002p02`: `/usr/local/sbin/deevnet-egress-agent`, run by `deevnet-egress-agent.timer` two minutes after boot and every five minutes after that
Deployed by	`ansible-playbook playbooks/tenant-egress-agent.yml`
Reads	`GET /v1/fabric/egress` from the API, with a token that can read that route and nothing else
Writes	`/etc/frr/frr.conf.local`. Only when it changes: `pvesh set /cluster/sdn` and a reload of FRR

A failed fetch leaves the file as it is, so an API outage withdraws no route. A deleted tenant loses its route on the next run.

deevnet-kit

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

deevnet-kit #

The Deevnet API’s stand-in on a Raspberry Pi. On the take-home Pi backend image it does, for one tenant and on the Pi itself, what the API does for a tenant on the site: broker accounts, log users, the card’s own CA and certificates, and a Grafana organization. It is built from the API’s own packages, so the same rules apply in both places.


Source	`deevnet-provisioning-api`, `cmd/deevnet-kit`; it shares the API’s tag
Built by	`make build-pi` and `make stage-pi` in the API repository (linux/arm64), baked into the image by `make pi-backend` in `deevnet-image-factory`
Runs as	A CLI and three systemd units on the Pi: first boot, dashboards, and a self-test on every boot
Commands	`init`, `status`, `env`, `export`, `account add\|list\|rm`, `regen-certs`, `render`, `dashboards`, `selftest`
State	`/etc/deevnet-kit/` (the tenant and its tokens, accounts, TLS, Grafana settings); input from `/boot/firmware/deevnet-kit.txt`

It is not part of the deployed API. How a tenant uses the image is Tenant to Pi Image.

Image Factories

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

Image Factories #

Two repositories that build what the site installs from. Both run on the Builder, and stage their output on the artifact server.

`deevnet-image-factory`: OS images #

Packer and Ansible builds of:

Image	Target
Fedora VM templates	Built straight onto each hypervisor: `make proxmox-fedora-pve1`, `make proxmox-fedora-pve2`
Raspberry Pi images	`make pi-sdr`, `make pi-pidp11`, and `make pi-backend` (the take-home tenant backend, with deevnet-kit)
Proxmox VE install ISO and PXE artifacts	`make proxmox-pve-iso-ext4` and related targets. Unfinished: neither hypervisor has been installed from it ( Builder roadmap)

Its scripts/pve-creds fetches a hypervisor’s Proxmox token per run, from OpenBao or the inventory vault, and never writes it to disk; the tenant fabric’s Terraform uses it too ( Build-Time Secrets).

Deevnet Software on Deevnet IoTaaS

Deevnet API

Deevnet API #

What it exposes #

Terraform Provider

Terraform Provider #

Why Terraform for tenants #

Log Bridge

Log Bridge #

Tenant Egress Agent

Tenant Egress Agent #

deevnet-kit

deevnet-kit #

Image Factories

Image Factories #

deevnet-image-factory: OS images #

`deevnet-image-factory`: OS images #