Fediversity

Feature Specification: Resource netbox

Created: 2026-10-07

Status: Implemented

Input: Reconstructed from the code of core/resources/netbox/ and its routing in core/setups/ at 093e68b6f, pull request #1234.

User Scenarios & Testing (mandatory)

The netbox resource gives a node the coordinates of the NetBox IPAM of its deployment: the server URL, a path to the API token, and the cluster, tenant and pool to allocate from. OpenTofu on the deployer allocates the addresses, not this resource. Like dns, it is a coordinate resource. The shared rules are in the resource family spec.

User Story 1 - Find the NetBox of the deployment (Priority: P1)

A deployment without an external IPAM stands up its own netbox node. A hosting provider that already runs NetBox gives the setup its URL, and the deployment then has no netbox node. The deployment must allocate from exactly one IPAM, the one that the hosting provider uses.

Independent Test: a unit test of the NetBox routing.

Acceptance Scenarios:

  1. Given a self-hosted route, When the result renders, Then the URL points at the netbox node, or is empty when the node has no host yet, and the result has no token path.
  2. Given an external route, When the result renders, Then the URL, the token path and each setting of the external provider come from that provider, and the roster has no netbox node.

User Story 2 - Name the address pool, or fail at eval (Priority: P2)

An allocation without a pool picks addresses from the wrong range. The operator names the pool as a selector. Coordinates without a pool fail the evaluation. No coordinates at all are not an error.

Independent Test: a unit test of the NetBox routing.

Acceptance Scenarios:

  1. Given coordinates without a pool, When they evaluate, Then the evaluation fails and names both places that can set the pool.

User Story 3 - Keep the API token out of the store (Priority: P3)

The token is a credential. The deployer reads it at apply time from a path that the secret environment of the incus hosts graph carries.

Independent Test: a unit test of the NetBox routing.

Acceptance Scenarios:

  1. Given a token path, When the secret environment renders, Then it carries that path and not the value.

Edge Cases

  • An external provider without a URL is inert.
  • A selector kind is free: a CIDR, an id, or a NetBox prefix filter. A range selector without a kind means the whole prefix.

Requirements (mandatory)

Functional Requirements

  • FR-001: The request MUST hold the cluster, the tenant, the prefix selector, the range selector and whether to allocate IPv4. The result MUST hold these, the server URL and the API token path.
  • FR-002: The policy MUST default to the cluster incus, no tenant, the prefix with the tag fediversity, the whole prefix and no IPv4, and MUST put these into the request.
  • FR-003: The deploy MUST NOT create NetBox infrastructure. The cluster and the pool MUST already exist.
  • FR-004: The self-hosted provider MUST answer with a plain HTTP URL of the host and port, or an empty URL without a host, and no token path. Its port MUST come from the same place as the port that the netbox node binds.
  • FR-005: The external provider MUST pass its URL and token path through, and MUST replace each request field except the IPv4 choice with its own value when it has one.
  • FR-006: The setup MUST treat NetBox as external only when it receives an external service with a URL.
  • FR-007: The setup MUST fail evaluation for coordinates without a pool.
  • FR-008: The setup MUST request netbox on each node with its coordinates, where present, and the default routing row, and MUST add the consumer side to each node.
  • FR-009: The request MUST hold only data. The consumer side MUST state the want, so the node gets the result under its consumer name. A module that reads the result MUST import the contract.

Key Entities

  • Selector: a kind and a value that pick a prefix or a range.
  • Self-hosted provider: the route to the netbox node.
  • External provider: the route to a third-party NetBox, with its URL, token path and optional cluster, tenant and selectors.
  • Consumer windmill: builds the operator configuration from the result.

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: The unit tests of the NetBox routing, the operator configuration, the coordinate consumer and plain-data requests pass.

Assumptions

  • The NetBox cluster, tenant and prefix exist before a deploy.
  • The external API token is a file on the deployer.

Known Deviations

  • The self-hosted token lives in OpenBao KV, which the incus hosts graph can read only from the second apply. The first apply of a cold deployment cannot reach the self-hosted NetBox. The external route has no such asymmetry.