Deevnet Terraform Provider

Install

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

Install the provider #

The provider is not in the public Terraform Registry. It goes into Terraform’s implicit local mirror, and terraform init finds it there:

~/.terraform.d/plugins/registry.terraform.io/deevnet/deevnet/<version>/<os>_<arch>/

The source address is deevnet/deevnet all the same, so a tenant’s required_providers block reads as it would for a registry provider.

At a Deevnet site #

On the tenant developer network, the site’s download server is the fastest route. It also installs the grafana provider, for dashboards as code.

Provider

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

deevnet Provider #

Builds tenants through the Deevnet API: their network, workloads and published names.

A tenant holds one credential, its Deevnet token, and no substrate credential. The Install guide puts the provider where terraform init finds it.

Example Usage #

terraform {
 required_providers {
 deevnet = {
 source = "deevnet/deevnet"
 version = "~> 0.6"
 }
 }
}

# Every argument falls back to an environment variable, so the block is
# usually empty and nothing about the site is written into the code.
provider "deevnet" {
 # endpoint = DEEVNET_API_ENDPOINT
 # token = DEEVNET_API_TOKEN
 # ca_certificate = DEEVNET_API_CACERT
}

Schema #

Optional #

ca_certificate (String) Path to the site CA certificate the API’s TLS certificate comes from. Defaults to DEEVNET_API_CACERT; empty uses the system trust store.
endpoint (String) The API’s base URL, e.g. https://api.mobile.deevnet.net. Defaults to DEEVNET_API_ENDPOINT.
token (String, Sensitive) The bearer token: the tenant’s own token, or the single-use enrollment token it was admitted with. Defaults to DEEVNET_API_TOKEN.

What a Tenant Holds

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

What a tenant holds #

A tenant holds one credential: its Deevnet token. Nothing else about the substrate reaches the tenant: no hypervisor credential, no vault access.

Enrollment #

The first apply trades a single-use enrollment token for the tenant’s own token. The substrate admits a tenant name and issues the enrollment token, delivered encrypted into the tenant’s repository. The first terraform apply spends it and receives the tenant’s own token, which every later call uses ( ADR-0015).

Restore Instead of Recreate

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

Restore instead of recreate #

When the API no longer holds an object, the provider restores it from state instead of creating a new one. The usual advice for a remote object that is gone is to drop it from state and let the next plan create another. For the resources that carry secrets or addressing that would be a loss: a new tenant would mean new keys, and a new workload would mean a new address.

Release Notes

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

Release Notes #

Every release of the deevnet/deevnet provider, newest first. Versions are MAJOR.MINOR.PATCH; until 1.0 a minor release may change behavior, and the notes say so under Upgrading.

A resource needs an API that serves it. Each release names the Deevnet API version its new resources and attributes need.

0.7.0 (2026-10-11) #

Needs API v0.11.0 for deevnet_certificate.

Added #

deevnet_certificate: a server certificate for one of the tenant’s own services, for a name in the tenant’s own zone, signed by the site’s Tenant Service CA (ADR-0037). You make the key, with the tls provider, and it never goes to the API; this resource takes a signing request. It chains to the Deevnet Root CA. Once fewer than sixty days remain, a plan shows the resource changing and the apply renews it.
A documentation site, https://deevnet.github.io/terraform-provider-deevnet/. The resource reference is generated from the schemas, and CI fails when it is stale.
A description on every attribute. The tenant argument had none on five resources.
An example for the provider block and for each resource, under examples/.

Upgrading #

A certificate expires after a year and nothing renews it but an apply. A tenant that holds one should plan at least every ten months; the plan shows the renewal when it is due.
deevnet_certificate needs the hashicorp/tls provider beside this one, for the key and the signing request.

0.6.0 (2026-10-06) #

Needs API v0.10.0 for deevnet_iot_address.

deevnet_certificate

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

deevnet_certificate (Resource) #

A server certificate for one of the tenant’s own services, for a name in the tenant’s own zone, signed by the site’s Tenant Service CA. It chains to the Deevnet Root CA, which every client on a site already trusts.

You make the key and keep it. This resource takes a signing request, not a key: make both with the tls provider (tls_private_key, tls_cert_request). The key stays in your state and on your workload, and never goes to the API.

deevnet_dns_record

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

deevnet_dns_record (Resource) #

A name in the tenant’s zone, with its PTR.

Example Usage #

# A second name for a workload, with its PTR.
resource "deevnet_dns_record" "api" {
 tenant = deevnet_tenant.this.name
 name = "api"
 address = deevnet_workload.web.address
}

Schema #

Required #

address (String) An address in the tenant’s own subnet.
name (String) A DNS label under the tenant’s zone.
tenant (String) The tenant this record belongs to: the name of a deevnet_tenant.

Read-Only #

fqdn (String) The published name.
present (Boolean) Whether the API still holds this name.

deevnet_iot_address

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

deevnet_iot_address (Resource) #

A fixed address for a registered device on its trust class’s network.

The device gets the same address every time it joins, and the API publishes <device>.<tenant zone> for it. The device must be a deevnet_iot_device with a mac: the address is reserved for that MAC.

The network is shared by every tenant, so the API picks the address: the lowest free one in the range set aside for tenants. This state remembers it, and a rebuilt API is asked for the same one again.

deevnet_iot_broker_account

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

deevnet_iot_broker_account (Resource) #

An MQTT account on the platform broker, for one of the tenant’s devices or workloads.

Configure the client with username and password.

Replacing this resource issues a new password, and anything already holding the old one stops connecting. A rebuilt API does not do that: it restores the account from this state. Use -replace only when you mean to revoke.

Example Usage #

resource "deevnet_iot_broker_account" "stand" {
 tenant = deevnet_tenant.this.name
 name = "stand-1"
 device = deevnet_iot_device.stand.name

 # Relative to the tenant. The API writes the "tdemo/" prefix itself, which is
 # what confines a tenant to its own topics.
 publish = ["lightstand/+/telemetry"]
 subscribe = ["lightstand/+/command"]
}

output "broker" {
 value = {
 username = deevnet_iot_broker_account.stand.username
 password = deevnet_iot_broker_account.stand.password
 # What the broker actually enforces, prefix and all.
 publish = deevnet_iot_broker_account.stand.granted_publish
 }
 sensitive = true
}

Schema #

Required #

name (String) A label for the account, unique within the tenant.
tenant (String) The tenant this broker account belongs to: the name of a deevnet_tenant.

Optional #

device (String) A device in the tenant’s registry, in trust class iot. Omit for an account a tenant workload uses. iot_vendor is refused: the standard forbids those devices reaching the broker at all, so the account could never be used.
publish (List of String) Topic patterns this account may publish to, relative to the tenant: write lightstand/+/scene, not eds/lightstand/+/scene. The API writes the prefix, which is what confines a tenant to its own topics.

May be omitted for an account that only subscribes. Omitting both is an error: the account could do nothing.

deevnet_iot_device

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

deevnet_iot_device (Resource) #

A device in the tenant’s registry.

The entry is the device’s identity: an application-owned device takes no substrate host record and is named in its owner’s own zone. It leases from its trust class’s pool unless a deevnet_iot_address reserves it a fixed address.

Registering a device grants it nothing. It is identity, not authorization. Flash devices with a deevnet_iot_wifi_key to put them on the air; that key is per tenant, and does not reference this resource.

deevnet_iot_wifi_key

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

deevnet_iot_wifi_key (Resource) #

A Wi-Fi key for the tenant’s IoT devices, bound to its trust class’s VLAN.

Flash devices with ssid and psk. One key serves every device the tenant flashes with it.

Replacing this resource issues a new key, and every device already flashed with the old one stops associating until it is reflashed. A rebuilt API does not do that: it restores the key from this state. Use -replace only when you mean to revoke.

deevnet_tenant

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

deevnet_tenant (Resource) #

A tenant: its index and numbering, its DNS zone and key, its state-store credential, and its own API token. Everything but the name is issued by the API.

Example Usage #

resource "deevnet_tenant" "this" {
 name = "tdemo"
}

output "subnet" {
 value = deevnet_tenant.this.subnet
}

# What the API issued this tenant. This state is the authoritative copy.
output "state_credentials" {
 value = {
 endpoint = deevnet_tenant.this.state_endpoint
 bucket = deevnet_tenant.this.state_bucket
 key_prefix = deevnet_tenant.this.state_key_prefix
 access_key = deevnet_tenant.this.state_access_key
 secret_key = deevnet_tenant.this.state_secret_key
 }
 sensitive = true
}

Schema #

Required #

name (String) 1-8 lowercase alphanumerics, starting with a letter: the SDN zone id, a DNS label and a state-store user.

Read-Only #

api_token (String, Sensitive) The tenant’s own API token, for every later call it makes.
controller_id (String) EVPN controller the tenant’s zone attaches to.
dashboard_org_id (Number) The tenant’s own Grafana organization. The grafana provider ignores its provider-level org_id under basic auth, so set this as org_id on each grafana_folder and grafana_dashboard.
dashboard_password (String, Sensitive) The Grafana login’s password. Issued by the API, which keeps it sealed, so a reconcile can hand it back. The organization’s three log data sources have fixed UIDs - deevnet-logs-workloads, deevnet-logs-platform, deevnet-logs-devices - the same on every site and on the take-home Pi.
dashboard_url (String) The tenant’s Grafana, empty at a site with none (ADR-0024). Feed it to the grafana provider as GRAFANA_URL.
dashboard_username (String) The tenant’s Grafana login: an Editor in its own organization and a member of no other.
dns_reverse_zone (String) The tenant’s reverse DNS zone.
dns_update_server (String) Where RFC 2136 updates go, if the tenant publishes names itself.
dns_zone (String) The tenant’s forward DNS zone.
gateway (String) The anycast gateway address workloads use on the overlay subnet.
index (Number) The tenant index every identifier derives from (ADR-0002).
log_account_id (Number) The tenant’s partition family: project 0 is what its workloads ship, 1 what the substrate publishes about it, 2 its devices’ logs from MQTT.
log_endpoint (String) The log store this tenant ships to, empty at a site with none (ADR-0027).
log_ingest_token (String, Sensitive) Writes this tenant’s own log partition. Issued by the API, which keeps it sealed - unlike the API token, so a reconcile can hand it back.
log_read_token (String, Sensitive) Reads this tenant’s three log partitions, and no other tenant’s.
log_select_header (String) The header a reader sends to choose a partition, for example X-Deevnet-Partition: 2-1. Without it a read returns project 0. It selects only among this tenant’s partitions: the proxy sets the store’s own headers itself.
node (String) Hypervisor the tenant’s workloads land on.
present (Boolean) Whether the API still holds this tenant. False after the API’s registry is lost, which makes the next apply restore it from this state rather than create a new one.
secrets_stored (Boolean) Whether the API can still read the secrets it holds for this tenant. False after its Transit key is rebuilt or rotated past them, which makes the next apply send this state’s copies again - they are the authoritative ones.
state_access_key (String) State store access key.
state_bucket (String) The state store bucket this tenant writes to.
state_endpoint (String) S3 endpoint of the state store (ADR-0007).
state_key_prefix (String) The prefix this tenant may write.
state_secret_key (String, Sensitive) State store secret key. This state is its authoritative copy (ADR-0015 §4).
status (String) provisioning or ready.
subnet (String) The tenant’s overlay subnet, in CIDR form.
tsig_algorithm (String) Algorithm of the TSIG key.
tsig_key_name (String) Name of the TSIG key that may update the tenant’s zones.
tsig_secret (String, Sensitive) TSIG secret. This state is its authoritative copy (ADR-0015 §4).
vnet_vni_base (Number) First VXLAN id of the tenant’s VNets, derived from the index.
vrf_vni (Number) VXLAN id of the tenant’s VRF, derived from the index.

deevnet_workload

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

deevnet_workload (Resource) #

A VM in the tenant’s network. Its name is published in the tenant’s zone.

Example Usage #

resource "deevnet_workload" "web" {
 tenant = deevnet_tenant.this.name
 name = "web"
 cores = 2
 memory_mb = 2048

 # The public half; the private key never leaves you.
 ssh_keys = [file("~/.ssh/id_ed25519.pub")]
}

output "login" {
 value = "ssh ${deevnet_workload.web.login_user}@${deevnet_workload.web.fqdn}"
}

Schema #

Required #

name (String) A DNS label under the tenant’s zone, 1-20 lowercase alphanumerics or dashes.
tenant (String) The tenant this workload belongs to.

Optional #

cores (Number) Virtual CPU cores. Defaults to 2.
disk_gb (Number) Grows the template’s disk. It is never shrunk.
memory_mb (Number) Memory in MiB. Defaults to 2048.
ssh_keys (List of String) Public keys that may log in as login_user. Only the public half: the private key stays on your machine. Written when the workload is built; to change them, replace the workload (terraform apply -replace=...).

Read-Only #

address (String) Address in the tenant’s subnet.
fqdn (String) The name published for it.
login_user (String) The account ssh_keys land on: ssh <login_user>@<fqdn>.
mac (String) MAC, derived from the VMID.
ordinal (Number) The workload’s number within its tenant; the VMID and address derive from it.
present (Boolean) Whether the API still holds this workload.
status (String) provisioning or ready.
vmid (Number) Proxmox VMID.