Builder #

Purpose #

The builder is responsible for provisioning and configuring all substrate infrastructure.

Every Deevnet site needs a way to be created from scratch:

How do you provision infrastructure when no infrastructure exists yet?

The builder answers this by providing:

• A self-contained provisioning role
• All artifacts needed for deployment
• Automation to configure every substrate component
• Authority transition from bootstrap to production

Design Principles #

Self-Contained — The builder carries everything needed to stand up a substrate: IaC/CaC definitions, OS images, network boot infrastructure, and Git repositories.

Portable — A single builder can provision any site. The same builder serves any site — no site-specific hardware required.

Air-Gapped Capable — Once artifacts are staged, the builder can provision without upstream internet. No external dependencies during build.

Disposable Authority — The builder holds temporary DNS/DHCP/gateway authority during bootstrap, then hands off to the Core Router. It can become a regular admin host in production.

Replaceable Provisioner — The provisioner is a role, not a pet. Any suitable host can assume it via code — rebuilding or replacing the provisioner is expected. Switching provisioners requires only DNS changes, not consumer changes.

Network Position #

The builder is dual-homed, with one foot outside the site and one inside it:

• Upstream, it joins whatever external network is available (home, hotel, office), for staging artifacts and reaching the internet. Nothing inside the site depends on this link.
• Downstream, it sits on the management segment. During bootstrap it is the gateway for the site; in production it is an ordinary management host at a reserved address, behind the core router like everything else.

The builder moving between those two positions on the downstream side is the authority transition.

Air-Gap Scope #

Air-gapping applies to the substrate — the hosts that define the site: routers, hypervisors, the builder itself, and the management and control plane VMs. Everything they install comes from the builder’s artifact server, pre-staged and validated before use, with no upstream dependency during a build.

Out of scope:

• Tenant workloads — they may reach upstream repositories and registries, as their tenant’s policy allows
• Pi lab hosts and edge devices — a different OS and a different lifecycle, owned by the project using them

Mirroring every OS a tenant or device might run would be an unsustainable maintenance burden. The substrate is the trusted foundation, so the air-gap effort goes there.

How It Works #

The builder hosts all Infrastructure as Code and Configuration as Code used to set up the substrate. The build process follows a deliberate sequence:

1. Network boot — Bare-metal and virtual hosts PXE boot from the builder, pulling OS images and kickstart configurations from its local artifact server
2. OS installation — Hosts install from builder-hosted images and register against builder-hosted DHCP reservations, receiving deterministic IPs and hostnames
3. Configuration — The builder runs automation (from its local Git mirrors) against the newly installed hosts, applying CaC to configure networking, services, and security policy
4. Validation — Each host is verified against its expected state before proceeding to the next

The builder drives this entire sequence from its own local resources — no external dependencies are required once artifacts are staged.

Order matters within it: a host can only fetch artifacts once it can resolve the artifact server’s name, and it only learns where to boot from once DHCP answers it. DNS and DHCP come first, then boot files, then artifacts.

Bootstrap Services #

During initial build, the builder is the network — no other infrastructure exists yet. It runs its own DNS, DHCP, and gateway services so that newly provisioned hosts can resolve names, obtain addresses, and reach the builder’s artifact server without depending on anything it hasn’t built yet.

This means the builder must carry a complete, self-contained copy of every resource needed to stand up the substrate:

• DNS zone data — All substrate host records, service CNAMEs, and reverse entries for the target site, served authoritatively by the builder until the Core Router takes over
• DHCP configuration — Static reservations for every known host MAC, plus dynamic pools for initial PXE boot or OS image installation
• Git repositories — A local mirror of every repository in the deevnet GitHub organization (IaC, CaC, inventory, playbooks), so automation runs entirely against local clones
• OS and package artifacts — Installation images, kickstart configs, and package mirrors staged locally

Authority Transition #

Once the Core Router is provisioned and validated, DNS/DHCP authority transfers to it and the builder’s bootstrap services are deactivated. The builder retains TFTP, artifact hosting, and automation controller duties in production.

The builder participates in explicit authority transitions:

The transition is explicit and deliberate—never automatic.

Records are defined in both the builder’s configuration and the Core Router’s, but only one authority is active at a time. The builder’s DNS/DHCP is disabled in production, and the Core Router does not exist (or is being rebuilt) during bootstrap. This is intentional duplication with exclusive activation, not conflicting truth.

Multi-Homing Without Identity Confusion #

A builder node may be reachable from multiple sites.

Instead of ambiguous multi-A records, the builder is published once per site zone, each name resolving to the address the builder has at that site:

dv00bld001p01.home.deevnet.net    ->  10.10.99.95
dv00bld001p01.mobile.deevnet.net  ->  10.20.99.95

The builder keeps one short name everywhere; the zone says which site’s address you get. Each fully qualified name has exactly one address ( ADR-0008).

This preserves:

• truthful routing
• clear firewall policy
• explicit blast-radius boundaries