Fediversity

Feature Specification: Component netbox

Created: 2026-10-07

Status: Implemented

Input: Reconstructed from the code of core/components/hosting-provider/netbox/ and the self-hosted provider of core/resources/netbox/ at 093e68b6f, pull requests #1400, #1482, #1490, #1542, #1597, #1822, #1852 and #1996.

User Scenarios & Testing (mandatory)

User Story 1 - Run an IPAM instance for the deployment (Priority: P1)

A hosting provider without its own NetBox runs it on a node of the hosting-provider group, which provides netbox. The deployment programs allocate the node addresses from it through the netbox resource. A deployment with an external NetBox does not deploy this node, and the overview shows no tile for it.

Why this priority: without IPAM, the nodes keep a placeholder address and the zone cannot be published.

Independent Test: a VM test runs the instance, waits for the token unit, and runs the NetBox effects of the deployment programs against it.

Acceptance Scenarios:

  1. Given a running instance, When the effects store a range and ask for an address, Then the instance gives the first free address.

User Story 2 - Give the operator deploy an API token (Priority: P1)

A token unit mints a write-enabled v2 token for a dedicated service user. With the OpenBao vars backend, it publishes the token to the KV store, where the deploy reads it. NetBox keeps only a digest, so the KV store holds the only full copy. On each run the unit keeps the stored token while it authenticates, and else mints a new one.

Why this priority: the self-hosted provider gives no token file, so the KV token is the only credential of the incus graph for the instance.

Independent Test: a VM test with the OpenBao vars backend checks that the token authenticates as the service user, a wrong secret part is refused, a second run keeps the token, and a run after the token is removed publishes a new one. The VM test also does the requests of a deploy with the token, and checks that NetBox refuses a write to an object type that a deploy does not use. A unit test checks that only the OpenBao vars backend writes the KV store.

Acceptance Scenarios:

  1. Given no OpenBao vars backend, When the unit runs, Then it mints the token and does not contact OpenBao.
  2. Given NetBox fails its first start, When it recovers, Then the token unit retries and mints the token.

User Story 3 - Log in, send mail and report telemetry (Priority: P2)

An administrator logs in with single sign-on. NetBox sends mail through the relay of the deployment and sends traces to the collector, through the oidc, smtp and otel resources.

Why this priority: without them, an administrator needs a local password, and failures are not visible.

Independent Test: a unit test checks the configuration from the resource results. A VM test with stand-in results checks the TLS connection to the database, a replaced database password, the secrets from the KV store, the SSO redirect, the mail from the web and worker processes, and the traces. A second VM test completes the login of a user through the authelia and lldap of the deployment, and checks the session that NetBox gives.

Acceptance Scenarios:

  1. Given an HTTPS issuer and a deployment CA, When NetBox starts, Then it starts after the node trusts the CA and uses it for the issuer.

Edge Cases

  • The management command outside a service has no service credentials, so the configuration skips the OIDC secret and the SMTP password.
  • NetBox reads the database password only at start, so a new password restarts the web and worker processes.
  • The upstream module declares a housekeeping timer without a service, so the component turns it off.
  • The telemetry wrapper finds the patched package in the start commands of the upstream module. A change of these commands breaks the evaluation.

Requirements (mandatory)

Functional Requirements

  • FR-001: The component MUST serve a browser UI on its own subdomain with a browser-trusted certificate (see ssl), with static files served by the web server, and request a SPIFFE identity (see spiffe).
  • FR-002: The component MUST declare that it provides netbox. With an external NetBox, the roster MUST drop that node.
  • FR-003: The database request MUST contain only data, with a password that only NetBox reads. The node MUST configure its client from the result alone, configure nothing without it, and MUST NOT create a local database (see postgresql).
  • FR-004: The OIDC client MUST redirect to the own name and send its secret in the request body (see oidc). The SMTP sender MUST use the own name and TLS (see smtp). Both secrets MUST load as service credentials.
  • FR-005: A process that gets an empty secret MUST fail and retry without a limit.
  • FR-006: The web and worker processes MUST be instrumented, each with its own service name (see otel).
  • FR-007: The node MUST generate the secret key and the token pepper (see generateFiles). NetBox MUST start after they render, on the port that the self-hosted provider reads.
  • FR-008: The token unit MUST retry at a short interval without a limit, and MUST want NetBox without requiring it.
  • FR-009: The token unit MUST reuse one service user, keep a stored token that is an active v2 token of the user, and else delete the tokens of the user and mint one.
  • FR-010: The token unit MUST read and write the KV store only with the OpenBao vars backend, and write only on a change.
  • FR-011: The component MUST stream a backup of its database as the NetBox user to a bucket of garage.
  • FR-012: The token unit MUST give the service user one object permission, with the actions view, add, change and delete on the object types that the seed and the deploy graphs use, and on no other object type.

Key Entities

  • Service user: owns the API token of the operator deploy.
  • API token: the write-enabled v2 token in the KV store.
  • Test bootstrap: test driver helpers, not part of the component, that make a superuser and a v1 token and look up addresses.

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: The VM test of the service passes, and the incus app test passes with this node as IPAM.
  • SC-002: The unit tests of the setups for NetBox routing, pinning and the overview pass.
  • SC-003: The unit and VM tests of the consumers pass.

Assumptions

  • The self-hosted provider reaches the instance over plain HTTP on its port, so the bootstrap needs no in-cluster TLS trust.
  • The incus graph reads the KV token only from the second apply on, because the vault provider dials an address that the previous apply published.
  • The catalog metadata comes from the generic NetBox package, and the node runs a pinned release.

Known Deviations

None.