provision
- GET /provision/batches
List provision batches
Returns every provision batch, newest first, with its nodes and state counts; failure messages are replaced by their failure class.
- Status Codes:
200 OK – total and batches
500 Internal Server Error – Database error
- POST /provision/batches
Create a provision batch
Creates a pending batch for a template and a list of revealed nodes; refuses unknown nodes and nodes already in an active batch.
- Status Codes:
201 Created – batch_id and state
400 Bad Request – Invalid body, missing field or unrevealed nodes
404 Not Found – Template not found
409 Conflict – A node is already in an active batch
500 Internal Server Error – Database error
- GET /provision/batches/{id}
Get a provision batch
Returns one provision batch with its nodes and state counts; failure messages are replaced by their failure class.
- Parameters:
id (string) – Batch ID
- Status Codes:
200 OK – batch_id, template_id, state, nodes and stats
404 Not Found – Batch not found
- POST /provision/batches/{id}/start
Start a provision batch
Queues a pending batch’s nodes for provisioning after checking the maintenance lock, the provision config, cluster readiness and per-node MTU; an already running batch returns 200.
- Parameters:
id (string) – Batch ID
- Status Codes:
200 OK – batch_id and state
400 Bad Request – Provision config incomplete
404 Not Found – Batch not found
409 Conflict – Maintenance in progress, or batch canceled or done
422 Unprocessable Entity – Cluster readiness or MTU checks blocking
500 Internal Server Error – Config or database error
- GET /provision/config
Get the provision config
Returns the provision config with the network fabric (management and storage scoped to the node’s pod when bmc_ip is given), management node CPU and memory usage and the guest bridges.
- Query Parameters:
bmc_ip (string) – Scope management and storage fabric to this node’s pod
- Status Codes:
200 OK – OK
500 Internal Server Error – Database error
- Response JSON Object:
admin_pw (string)
admin_user (string)
errors[] (string)
golden_sha (string)
golden_url (string)
guest_bridges[].bridge (string)
guest_bridges[].is_bootstrap (boolean)
guest_bridges[].kind (string) – bootstrap | dedicated | overlay
guest_bridges[].networks[].account (string)
guest_bridges[].networks[].autopopulate_group (string)
guest_bridges[].networks[].domain (string)
guest_bridges[].networks[].encap (string) – vlan | vxlan | untagged
guest_bridges[].networks[].gateway (string)
guest_bridges[].networks[].id (string)
guest_bridges[].networks[].is_tenant_owned (boolean)
guest_bridges[].networks[].name (string)
guest_bridges[].networks[].net_state (string) – implemented | setup | allocated | shutdown
guest_bridges[].networks[].selectable (boolean)
guest_bridges[].networks[].subnet (string)
guest_bridges[].networks[].test_result (string) – not_run — filled by validate-live, never by /config
guest_bridges[].networks[].test_status (string)
guest_bridges[].networks[].testable (boolean)
guest_bridges[].networks[].type (string) – Shared | Isolated | L2
guest_bridges[].networks[].unselectable_reason (string)
guest_bridges[].networks[].valid (boolean)
guest_bridges[].networks[].validation_errors[] (string)
guest_bridges[].networks[].vlan (string)
guest_bridges[].networks[].vlan_status (string) – active | deprecated | reserved | unknown
guest_bridges[].networks[].vni (string)
guest_bridges[].networks[].vpc_id (string)
guest_bridges[].networks[].vpc_name (string)
guest_bridges[].networks[].vr_running (boolean) – null unless Isolated
guest_bridges[].placement (any) – nil for overlay
guest_bridges[].pn_id (string)
guest_bridges[].renderable (boolean)
guest_bridges[].unrenderable_reason (string)
max_concurrent_provisions (integer)
mgmt_cpu_threshold_pct (integer)
mgmt_cpu_usage_pct (integer) – MgmtCPUUsagePct / MgmtMemUsagePct are the control node’s CURRENT live usage (0..100), sampled per request, so the UI can show usage against the admission thresholds (mgmt_cpu_threshold_pct / mgmt_mem_threshold_pct). Null when the /proc read fails.
mgmt_mem_threshold_pct (integer)
mgmt_mem_usage_pct (integer)
network.dns (string)
network.gateway (string)
network.prefix (integer) – NO Mode HERE. net_mode was a FLEET SINGLETON — one row deciding allocate-vs-recall for every node core seeds — so a part-static, part-leased estate could not be expressed: core took one branch for all of them while each node’s golden took its own from its own hwprofile. Deleted by WO-N19, not demoted to a fallback: a fallback would have preserved a silent default on the exact path that work order removes one from, and would have been dead code from the day it shipped (greenfield — no pod predates the pod tag). The posture now belongs to the POD, on its management prefix, resolved per node at seed time (bmo/provision/seed.go resolveNodePosture). A pod is one L2 segment, so that is the scope the fact actually has. Do not reintroduce a fleet-wide or per-node posture here.
network_fabric.guest.gateway (string)
network_fabric.guest.source (string) – WHERE THIS ANSWER CAME FROM. Three different records can supply a plane and they are indistinguishable on the wire without this: a CONTROL NODE’s planes are addresses the operator typed at Add Host, an AGENT’s management/storage come from its pod, and public/guest are zone-wide. It exists for the failure case, not the happy one. When a network test fails, “gateway 172.17.255.253 did not answer” reads identically whether the operator mistyped that gateway or a switch port is dead - and those have opposite repairs. Naming the source sends them to their own input first when the value was theirs. SourceNote is the sentence the UI renders VERBATIM; Source is the machine value so the UI can style or filter without matching on prose. Both empty on a backend that predates this, which the UI must treat as “say nothing” rather than “unknown”.
network_fabric.guest.source_note (string) – operator-facing, rendered as-is
network_fabric.guest.subnet (string)
network_fabric.guest.tagged (boolean) – Tagged reports whether the CLUSTER runs this plane on a VLAN trunk. Deliberately NOT omitempty: an omitted false is indistinguishable from “the backend did not say”, and the UI must be able to pre-select Untagged rather than guess. The NetBox fabric projection (networkFabricFromNetBox) leaves it FALSE since 2026-09-29: tagging is per node by ruling, decided by the joiner’s own installer inputs, so the backend only ships the role’s VLAN id and no longer reads the founding node’s hwprofile.env <ROLE>_VLAN presence as the cluster’s answer. It is a first-class fact, not an inference from VLAN being non-empty. karios-bootstrap modelled it that way — NICAssignment{Untagged string, Tagged []TaggedNetwork} carried through to NICMapping.Tagged, set by WHICH branch produced the mapping, never derived from a VLAN value (utils/bridgeconfig.go). Deriving one from the other is what leaves an untagged plane with nowhere to record the user’s declared id.
network_fabric.guest.vlan (string)
network_fabric.mgmt.gateway (string)
network_fabric.mgmt.source (string) – WHERE THIS ANSWER CAME FROM. Three different records can supply a plane and they are indistinguishable on the wire without this: a CONTROL NODE’s planes are addresses the operator typed at Add Host, an AGENT’s management/storage come from its pod, and public/guest are zone-wide. It exists for the failure case, not the happy one. When a network test fails, “gateway 172.17.255.253 did not answer” reads identically whether the operator mistyped that gateway or a switch port is dead - and those have opposite repairs. Naming the source sends them to their own input first when the value was theirs. SourceNote is the sentence the UI renders VERBATIM; Source is the machine value so the UI can style or filter without matching on prose. Both empty on a backend that predates this, which the UI must treat as “say nothing” rather than “unknown”.
network_fabric.mgmt.source_note (string) – operator-facing, rendered as-is
network_fabric.mgmt.subnet (string)
network_fabric.mgmt.tagged (boolean) – Tagged reports whether the CLUSTER runs this plane on a VLAN trunk. Deliberately NOT omitempty: an omitted false is indistinguishable from “the backend did not say”, and the UI must be able to pre-select Untagged rather than guess. The NetBox fabric projection (networkFabricFromNetBox) leaves it FALSE since 2026-09-29: tagging is per node by ruling, decided by the joiner’s own installer inputs, so the backend only ships the role’s VLAN id and no longer reads the founding node’s hwprofile.env <ROLE>_VLAN presence as the cluster’s answer. It is a first-class fact, not an inference from VLAN being non-empty. karios-bootstrap modelled it that way — NICAssignment{Untagged string, Tagged []TaggedNetwork} carried through to NICMapping.Tagged, set by WHICH branch produced the mapping, never derived from a VLAN value (utils/bridgeconfig.go). Deriving one from the other is what leaves an untagged plane with nowhere to record the user’s declared id.
network_fabric.mgmt.vlan (string)
network_fabric.public.gateway (string)
network_fabric.public.source (string) – WHERE THIS ANSWER CAME FROM. Three different records can supply a plane and they are indistinguishable on the wire without this: a CONTROL NODE’s planes are addresses the operator typed at Add Host, an AGENT’s management/storage come from its pod, and public/guest are zone-wide. It exists for the failure case, not the happy one. When a network test fails, “gateway 172.17.255.253 did not answer” reads identically whether the operator mistyped that gateway or a switch port is dead - and those have opposite repairs. Naming the source sends them to their own input first when the value was theirs. SourceNote is the sentence the UI renders VERBATIM; Source is the machine value so the UI can style or filter without matching on prose. Both empty on a backend that predates this, which the UI must treat as “say nothing” rather than “unknown”.
network_fabric.public.source_note (string) – operator-facing, rendered as-is
network_fabric.public.subnet (string)
network_fabric.public.tagged (boolean) – Tagged reports whether the CLUSTER runs this plane on a VLAN trunk. Deliberately NOT omitempty: an omitted false is indistinguishable from “the backend did not say”, and the UI must be able to pre-select Untagged rather than guess. The NetBox fabric projection (networkFabricFromNetBox) leaves it FALSE since 2026-09-29: tagging is per node by ruling, decided by the joiner’s own installer inputs, so the backend only ships the role’s VLAN id and no longer reads the founding node’s hwprofile.env <ROLE>_VLAN presence as the cluster’s answer. It is a first-class fact, not an inference from VLAN being non-empty. karios-bootstrap modelled it that way — NICAssignment{Untagged string, Tagged []TaggedNetwork} carried through to NICMapping.Tagged, set by WHICH branch produced the mapping, never derived from a VLAN value (utils/bridgeconfig.go). Deriving one from the other is what leaves an untagged plane with nowhere to record the user’s declared id.
network_fabric.public.vlan (string)
network_fabric.storage.gateway (string)
network_fabric.storage.source (string) – WHERE THIS ANSWER CAME FROM. Three different records can supply a plane and they are indistinguishable on the wire without this: a CONTROL NODE’s planes are addresses the operator typed at Add Host, an AGENT’s management/storage come from its pod, and public/guest are zone-wide. It exists for the failure case, not the happy one. When a network test fails, “gateway 172.17.255.253 did not answer” reads identically whether the operator mistyped that gateway or a switch port is dead - and those have opposite repairs. Naming the source sends them to their own input first when the value was theirs. SourceNote is the sentence the UI renders VERBATIM; Source is the machine value so the UI can style or filter without matching on prose. Both empty on a backend that predates this, which the UI must treat as “say nothing” rather than “unknown”.
network_fabric.storage.source_note (string) – operator-facing, rendered as-is
network_fabric.storage.subnet (string)
network_fabric.storage.tagged (boolean) – Tagged reports whether the CLUSTER runs this plane on a VLAN trunk. Deliberately NOT omitempty: an omitted false is indistinguishable from “the backend did not say”, and the UI must be able to pre-select Untagged rather than guess. The NetBox fabric projection (networkFabricFromNetBox) leaves it FALSE since 2026-09-29: tagging is per node by ruling, decided by the joiner’s own installer inputs, so the backend only ships the role’s VLAN id and no longer reads the founding node’s hwprofile.env <ROLE>_VLAN presence as the cluster’s answer. It is a first-class fact, not an inference from VLAN being non-empty. karios-bootstrap modelled it that way — NICAssignment{Untagged string, Tagged []TaggedNetwork} carried through to NICMapping.Tagged, set by WHICH branch produced the mapping, never derived from a VLAN value (utils/bridgeconfig.go). Deriving one from the other is what leaves an untagged plane with nowhere to record the user’s declared id.
network_fabric.storage.vlan (string)
queue_overflow (string)
source_status.cloudstack (string) – ok | degraded | down
source_status.netbox (string) – ok | degraded | down
updated_at (string)
warnings[] (string)
- PUT /provision/config
Update the provision config
Validates and saves the provision config: concurrency, management CPU and memory thresholds, queue overflow policy, golden image, network defaults and admin credentials.
- Request JSON Object:
admin_pw (string)
admin_user (string)
golden_sha (string)
golden_url (string)
max_concurrent_provisions (integer)
mgmt_cpu_threshold_pct (integer)
mgmt_mem_threshold_pct (integer)
network.dns (string)
network.gateway (string)
network.prefix (integer) – NO Mode HERE. net_mode was a FLEET SINGLETON — one row deciding allocate-vs-recall for every node core seeds — so a part-static, part-leased estate could not be expressed: core took one branch for all of them while each node’s golden took its own from its own hwprofile. Deleted by WO-N19, not demoted to a fallback: a fallback would have preserved a silent default on the exact path that work order removes one from, and would have been dead code from the day it shipped (greenfield — no pod predates the pod tag). The posture now belongs to the POD, on its management prefix, resolved per node at seed time (bmo/provision/seed.go resolveNodePosture). A pod is one L2 segment, so that is the scope the fact actually has. Do not reintroduce a fleet-wide or per-node posture here.
queue_overflow (string)
updated_at (string)
- Status Codes:
200 OK – OK
400 Bad Request – Invalid body or value
500 Internal Server Error – Database error
- Response JSON Object:
admin_pw (string)
admin_user (string)
golden_sha (string)
golden_url (string)
max_concurrent_provisions (integer)
mgmt_cpu_threshold_pct (integer)
mgmt_mem_threshold_pct (integer)
network.dns (string)
network.gateway (string)
network.prefix (integer) – NO Mode HERE. net_mode was a FLEET SINGLETON — one row deciding allocate-vs-recall for every node core seeds — so a part-static, part-leased estate could not be expressed: core took one branch for all of them while each node’s golden took its own from its own hwprofile. Deleted by WO-N19, not demoted to a fallback: a fallback would have preserved a silent default on the exact path that work order removes one from, and would have been dead code from the day it shipped (greenfield — no pod predates the pod tag). The posture now belongs to the POD, on its management prefix, resolved per node at seed time (bmo/provision/seed.go resolveNodePosture). A pod is one L2 segment, so that is the scope the fact actually has. Do not reintroduce a fleet-wide or per-node posture here.
queue_overflow (string)
updated_at (string)
- GET /provision/console/{bmc_ip}
Tail a node’s console log
Returns the last lines of a node’s console capture.
- Parameters:
bmc_ip (string) – BMC IP address
- Query Parameters:
tail (integer) – Number of lines, default 200
- Status Codes:
200 OK – bmc_ip and lines
404 Not Found – No console log for the node
- GET /provision/logs/download
Download provision logs
Streams a .tar.gz of a node’s redacted stage log and console capture plus a manifest; batch_id only labels the bundle.
- Query Parameters:
bmc_ip (string) – BMC IP address
batch_id (string) – Batch ID recorded in the manifest
- Status Codes:
200 OK – tar.gz bundle
400 Bad Request – Missing or invalid bmc_ip
404 Not Found – No provision logs for the node
- POST /provision/match
Match revealed nodes against a template in the body
Validates the template given in the body and computes which revealed nodes fit it; a read with no state change.
- Status Codes:
200 OK – OK
400 Bad Request – Invalid body or template
500 Internal Server Error – Database error
- Response JSON Object:
matching[].bmc_ip (string)
matching[].cpu_cores (integer)
matching[].disks[].device_path (string)
matching[].disks[].interface (string)
matching[].disks[].model (string)
matching[].disks[].name (string)
matching[].disks[].raid_vd (boolean)
matching[].disks[].rotational (integer)
matching[].disks[].serial (string)
matching[].disks[].size_gb (integer)
matching[].disks[].type (string)
matching[].disks[].wwn (string)
matching[].guest_nic_candidates[].detection_method (string)
matching[].guest_nic_candidates[].dhcp_server (string)
matching[].guest_nic_candidates[].interface (string)
matching[].guest_nic_candidates[].leased_ipv4 (string) – LeasedIPv4 is the address the CUSTOMER’s DHCP server offered THIS MAC during the reveal, in CIDR form, and DHCPServer is who offered it. Both empty on a static reveal — there is no lease when Karios stamped the address itself. This is the binding an operator needs to create a reservation BEFORE the node installs. On a network Karios does not own, the reservation has to exist before the node ever asks in earnest, and until now the reveal obtained a lease, used it to reach the control node, and threw the address away. EMPTY MEANS “NO SERVER ANSWERED ON THIS WIRE”, not “the address is 0”. The reveal appends nothing for a NIC that got no lease, so absence here is real evidence — it is how a wrong-VLAN NIC shows up on a leased pod, where the ARP subnet watch cannot run because there is no address to ARP for.
matching[].guest_nic_candidates[].mac (string)
matching[].guest_nic_candidates[].speed_mbps (integer)
matching[].guest_nic_candidates[].subnet (string)
matching[].guest_nic_candidates[].vlan (string) – VLAN/Subnet the reveal proved this NIC sits on for the traffic it is a candidate for, and how it was detected: lldp (switch dot1 TLV) | gwarp (gateway-ARP, mgmt/public) | peerarp (peer-ARP, gateway-less storage) | operator_assign (guest — never L3-probed).
matching[].has_mixed_sizes (boolean) – HasMixedSizes is true when the chosen root-vdev disks differ in size by more than 10% and the user accepted it with allow_mixed_sizes, so the UI can still show the wasted-capacity banner instead of the mismatch disappearing silently.
matching[].has_raid_vd (boolean) – HasRaidVD is true when any chosen OS or OSD disk is a hardware RAID virtual disk, so the UI can surface one consent banner for the user to acknowledge.
matching[].mgmt_nic (string) – Resolved management NIC: the reveal-proven NIC (by MAC) when known, else the best live physical NIC. The UI shows this read-only instead of asking for a NIC in the template.
matching[].mgmt_nic_candidates[].detection_method (string)
matching[].mgmt_nic_candidates[].dhcp_server (string)
matching[].mgmt_nic_candidates[].interface (string)
matching[].mgmt_nic_candidates[].leased_ipv4 (string) – LeasedIPv4 is the address the CUSTOMER’s DHCP server offered THIS MAC during the reveal, in CIDR form, and DHCPServer is who offered it. Both empty on a static reveal — there is no lease when Karios stamped the address itself. This is the binding an operator needs to create a reservation BEFORE the node installs. On a network Karios does not own, the reservation has to exist before the node ever asks in earnest, and until now the reveal obtained a lease, used it to reach the control node, and threw the address away. EMPTY MEANS “NO SERVER ANSWERED ON THIS WIRE”, not “the address is 0”. The reveal appends nothing for a NIC that got no lease, so absence here is real evidence — it is how a wrong-VLAN NIC shows up on a leased pod, where the ARP subnet watch cannot run because there is no address to ARP for.
matching[].mgmt_nic_candidates[].mac (string)
matching[].mgmt_nic_candidates[].speed_mbps (integer)
matching[].mgmt_nic_candidates[].subnet (string)
matching[].mgmt_nic_candidates[].vlan (string) – VLAN/Subnet the reveal proved this NIC sits on for the traffic it is a candidate for, and how it was detected: lldp (switch dot1 TLV) | gwarp (gateway-ARP, mgmt/public) | peerarp (peer-ARP, gateway-less storage) | operator_assign (guest — never L3-probed).
matching[].mgmt_nic_mac (string)
matching[].model (string)
matching[].nics[].link (string)
matching[].nics[].mac (string)
matching[].nics[].max_mtu (integer) – MaxMTU is the ceiling the NIC’s driver reports. sysfs does not publish it; the reveal reads it over rtnetlink, which is why it was missed. 0 is “not known”, never “cannot carry”.
matching[].nics[].name (string)
matching[].nics[].speed_mbps (integer)
matching[].nics[].subnet (string)
matching[].nics[].vlan (string) – VLAN/Subnet the reveal detected on this NIC (LLDP dot1 TLV primary, L3 probe fallback). Empty when the reveal predates per-NIC fabric detection or the NIC is on no known VLAN.
matching[].os_disks[] (string)
matching[].osd_disks[] (string)
matching[].public_nic (string)
matching[].public_nic_candidates[].detection_method (string)
matching[].public_nic_candidates[].dhcp_server (string)
matching[].public_nic_candidates[].interface (string)
matching[].public_nic_candidates[].leased_ipv4 (string) – LeasedIPv4 is the address the CUSTOMER’s DHCP server offered THIS MAC during the reveal, in CIDR form, and DHCPServer is who offered it. Both empty on a static reveal — there is no lease when Karios stamped the address itself. This is the binding an operator needs to create a reservation BEFORE the node installs. On a network Karios does not own, the reservation has to exist before the node ever asks in earnest, and until now the reveal obtained a lease, used it to reach the control node, and threw the address away. EMPTY MEANS “NO SERVER ANSWERED ON THIS WIRE”, not “the address is 0”. The reveal appends nothing for a NIC that got no lease, so absence here is real evidence — it is how a wrong-VLAN NIC shows up on a leased pod, where the ARP subnet watch cannot run because there is no address to ARP for.
matching[].public_nic_candidates[].mac (string)
matching[].public_nic_candidates[].speed_mbps (integer)
matching[].public_nic_candidates[].subnet (string)
matching[].public_nic_candidates[].vlan (string) – VLAN/Subnet the reveal proved this NIC sits on for the traffic it is a candidate for, and how it was detected: lldp (switch dot1 TLV) | gwarp (gateway-ARP, mgmt/public) | peerarp (peer-ARP, gateway-less storage) | operator_assign (guest — never L3-probed).
matching[].public_nic_mac (string)
matching[].ram_gb (integer)
matching[].storage_nic (string) – Resolved storage/public NIC: auto-selected when the reveal found exactly one candidate, empty when 0 or >1 so the user picks (the UI shows a selector over the candidates). Guest has no auto NIC — it is user-assigned, so only its candidate list is carried.
matching[].storage_nic_candidates[].detection_method (string)
matching[].storage_nic_candidates[].dhcp_server (string)
matching[].storage_nic_candidates[].interface (string)
matching[].storage_nic_candidates[].leased_ipv4 (string) – LeasedIPv4 is the address the CUSTOMER’s DHCP server offered THIS MAC during the reveal, in CIDR form, and DHCPServer is who offered it. Both empty on a static reveal — there is no lease when Karios stamped the address itself. This is the binding an operator needs to create a reservation BEFORE the node installs. On a network Karios does not own, the reservation has to exist before the node ever asks in earnest, and until now the reveal obtained a lease, used it to reach the control node, and threw the address away. EMPTY MEANS “NO SERVER ANSWERED ON THIS WIRE”, not “the address is 0”. The reveal appends nothing for a NIC that got no lease, so absence here is real evidence — it is how a wrong-VLAN NIC shows up on a leased pod, where the ARP subnet watch cannot run because there is no address to ARP for.
matching[].storage_nic_candidates[].mac (string)
matching[].storage_nic_candidates[].speed_mbps (integer)
matching[].storage_nic_candidates[].subnet (string)
matching[].storage_nic_candidates[].vlan (string) – VLAN/Subnet the reveal proved this NIC sits on for the traffic it is a candidate for, and how it was detected: lldp (switch dot1 TLV) | gwarp (gateway-ARP, mgmt/public) | peerarp (peer-ARP, gateway-less storage) | operator_assign (guest — never L3-probed).
matching[].storage_nic_mac (string)
matching[].vendor (string)
matching[].warnings[] (string)
matching_count (integer)
rejected[].bmc_ip (string)
rejected[].cpu_cores (integer)
rejected[].disks[].device_path (string)
rejected[].disks[].interface (string)
rejected[].disks[].model (string)
rejected[].disks[].name (string)
rejected[].disks[].raid_vd (boolean)
rejected[].disks[].rotational (integer)
rejected[].disks[].serial (string)
rejected[].disks[].size_gb (integer)
rejected[].disks[].type (string)
rejected[].disks[].wwn (string)
rejected[].model (string)
rejected[].nics[].link (string)
rejected[].nics[].mac (string)
rejected[].nics[].max_mtu (integer) – MaxMTU is the ceiling the NIC’s driver reports. sysfs does not publish it; the reveal reads it over rtnetlink, which is why it was missed. 0 is “not known”, never “cannot carry”.
rejected[].nics[].name (string)
rejected[].nics[].speed_mbps (integer)
rejected[].nics[].subnet (string)
rejected[].nics[].vlan (string) – VLAN/Subnet the reveal detected on this NIC (LLDP dot1 TLV primary, L3 probe fallback). Empty when the reveal predates per-NIC fabric detection or the NIC is on no known VLAN.
rejected[].ram_gb (integer)
rejected[].reason (string)
rejected[].vendor (string)
revealed_total (integer)
- POST /provision/metal-progress
Report metal install progress
Called without authentication by the metal installer during the on-disk install; records the node’s install phase and progress for its batch item.
- Status Codes:
200 OK – ok
400 Bad Request – Invalid body or missing bmc_ip
- GET /provision/network/probe-uplinks
List control node probe uplinks
Returns this control node’s interfaces, ranked, for the lease probe attachment choice.
- Status Codes:
200 OK – uplinks (provision.ProbeUplink list)
- GET /provision/network/{bmc_ip}
Get a revealed node’s network topology
Returns the per-traffic interface and MAC picks and the reveal’s candidates for a revealed node, for the manual topology form.
- Parameters:
bmc_ip (string) – BMC IP address
- Status Codes:
200 OK – OK
404 Not Found – No revealed node for the BMC
500 Internal Server Error – Revealed node could not be loaded
- Response JSON Object:
bmc_ip (string)
declared_mtu (any) – DeclaredMTU is the size each role’s pick will be checked against, so the form can show it read only beside the picker instead of leaving the number to be discovered by a refusal. It is set on the cluster MTU page, not here. 0 means this cluster declared nothing for that role.
guest.candidates[].detection_method (string)
guest.candidates[].dhcp_server (string)
guest.candidates[].interface (string)
guest.candidates[].leased_ipv4 (string) – LeasedIPv4 is the address the CUSTOMER’s DHCP server offered THIS MAC during the reveal, in CIDR form, and DHCPServer is who offered it. Both empty on a static reveal — there is no lease when Karios stamped the address itself. This is the binding an operator needs to create a reservation BEFORE the node installs. On a network Karios does not own, the reservation has to exist before the node ever asks in earnest, and until now the reveal obtained a lease, used it to reach the control node, and threw the address away. EMPTY MEANS “NO SERVER ANSWERED ON THIS WIRE”, not “the address is 0”. The reveal appends nothing for a NIC that got no lease, so absence here is real evidence — it is how a wrong-VLAN NIC shows up on a leased pod, where the ARP subnet watch cannot run because there is no address to ARP for.
guest.candidates[].mac (string)
guest.candidates[].speed_mbps (integer)
guest.candidates[].subnet (string)
guest.candidates[].vlan (string) – VLAN/Subnet the reveal proved this NIC sits on for the traffic it is a candidate for, and how it was detected: lldp (switch dot1 TLV) | gwarp (gateway-ARP, mgmt/public) | peerarp (peer-ARP, gateway-less storage) | operator_assign (guest — never L3-probed).
guest.interface (string)
guest.mac (string)
guest.speed_mbps (integer)
guest.tagged (boolean)
guest.vlan (string)
mgmt.candidates[].detection_method (string)
mgmt.candidates[].dhcp_server (string)
mgmt.candidates[].interface (string)
mgmt.candidates[].leased_ipv4 (string) – LeasedIPv4 is the address the CUSTOMER’s DHCP server offered THIS MAC during the reveal, in CIDR form, and DHCPServer is who offered it. Both empty on a static reveal — there is no lease when Karios stamped the address itself. This is the binding an operator needs to create a reservation BEFORE the node installs. On a network Karios does not own, the reservation has to exist before the node ever asks in earnest, and until now the reveal obtained a lease, used it to reach the control node, and threw the address away. EMPTY MEANS “NO SERVER ANSWERED ON THIS WIRE”, not “the address is 0”. The reveal appends nothing for a NIC that got no lease, so absence here is real evidence — it is how a wrong-VLAN NIC shows up on a leased pod, where the ARP subnet watch cannot run because there is no address to ARP for.
mgmt.candidates[].mac (string)
mgmt.candidates[].speed_mbps (integer)
mgmt.candidates[].subnet (string)
mgmt.candidates[].vlan (string) – VLAN/Subnet the reveal proved this NIC sits on for the traffic it is a candidate for, and how it was detected: lldp (switch dot1 TLV) | gwarp (gateway-ARP, mgmt/public) | peerarp (peer-ARP, gateway-less storage) | operator_assign (guest — never L3-probed).
mgmt.interface (string)
mgmt.mac (string)
mgmt.speed_mbps (integer)
mgmt.tagged (boolean)
mgmt.vlan (string)
public.candidates[].detection_method (string)
public.candidates[].dhcp_server (string)
public.candidates[].interface (string)
public.candidates[].leased_ipv4 (string) – LeasedIPv4 is the address the CUSTOMER’s DHCP server offered THIS MAC during the reveal, in CIDR form, and DHCPServer is who offered it. Both empty on a static reveal — there is no lease when Karios stamped the address itself. This is the binding an operator needs to create a reservation BEFORE the node installs. On a network Karios does not own, the reservation has to exist before the node ever asks in earnest, and until now the reveal obtained a lease, used it to reach the control node, and threw the address away. EMPTY MEANS “NO SERVER ANSWERED ON THIS WIRE”, not “the address is 0”. The reveal appends nothing for a NIC that got no lease, so absence here is real evidence — it is how a wrong-VLAN NIC shows up on a leased pod, where the ARP subnet watch cannot run because there is no address to ARP for.
public.candidates[].mac (string)
public.candidates[].speed_mbps (integer)
public.candidates[].subnet (string)
public.candidates[].vlan (string) – VLAN/Subnet the reveal proved this NIC sits on for the traffic it is a candidate for, and how it was detected: lldp (switch dot1 TLV) | gwarp (gateway-ARP, mgmt/public) | peerarp (peer-ARP, gateway-less storage) | operator_assign (guest — never L3-probed).
public.interface (string)
public.mac (string)
public.speed_mbps (integer)
public.tagged (boolean)
public.vlan (string)
storage.candidates[].detection_method (string)
storage.candidates[].dhcp_server (string)
storage.candidates[].interface (string)
storage.candidates[].leased_ipv4 (string) – LeasedIPv4 is the address the CUSTOMER’s DHCP server offered THIS MAC during the reveal, in CIDR form, and DHCPServer is who offered it. Both empty on a static reveal — there is no lease when Karios stamped the address itself. This is the binding an operator needs to create a reservation BEFORE the node installs. On a network Karios does not own, the reservation has to exist before the node ever asks in earnest, and until now the reveal obtained a lease, used it to reach the control node, and threw the address away. EMPTY MEANS “NO SERVER ANSWERED ON THIS WIRE”, not “the address is 0”. The reveal appends nothing for a NIC that got no lease, so absence here is real evidence — it is how a wrong-VLAN NIC shows up on a leased pod, where the ARP subnet watch cannot run because there is no address to ARP for.
storage.candidates[].mac (string)
storage.candidates[].speed_mbps (integer)
storage.candidates[].subnet (string)
storage.candidates[].vlan (string) – VLAN/Subnet the reveal proved this NIC sits on for the traffic it is a candidate for, and how it was detected: lldp (switch dot1 TLV) | gwarp (gateway-ARP, mgmt/public) | peerarp (peer-ARP, gateway-less storage) | operator_assign (guest — never L3-probed).
storage.interface (string)
storage.mac (string)
storage.speed_mbps (integer)
storage.tagged (boolean)
storage.vlan (string)
- POST /provision/network/{bmc_ip}/bond-eligibility
Check bond eligibility for a node being provisioned
Answered on the management node from the reveal NIC inventory; the node is never contacted and carrier is not judged. Members are matched by name, then MAC. Runs the same bond rules the seed render applies (at least two members, supported mode, 802.3ad needs lacp_confirmed, one NIC per bond across other_bonds). Mixed link speeds return ok=true with an advisory reason.
- Parameters:
bmc_ip (string) – BMC IP of the revealed node
- Request JSON Object:
lacp_confirmed (boolean) – LACPConfirmed records that a ToR probe observed a real LACP partner. Required for 802.3ad: validateBonds refuses it otherwise, mirroring the golden, whose kernel has no lacp_fallback_ab.
members[] (string)
mode (string) – Mode is active-backup or 802.3ad — the exact allow-list the golden renders. (required)
name (string) – Name is the bond device name; empty defaults to bond0 (one bond per host).
other_bonds[].lacp_confirmed (boolean) – LACPConfirmed records that a ToR probe observed a real LACP partner. Required for 802.3ad: the golden refuses to render it otherwise, because the kernel has no lacp_fallback_ab and hardcoded LACP against a switch with no port-channel takes the uplink down instead of degrading.
other_bonds[].members[] (string)
other_bonds[].mode (string) – Mode is active-backup or 802.3ad.
other_bonds[].mtu (integer) – MTU for the bond and its members. Zero omits the key.
other_bonds[].name (string) – Name must be the bond device name, e.g. “bond0”.
- Status Codes:
200 OK – OK
400 Bad Request – Invalid body (need members, mode)
404 Not Found – No revealed node for this BMC
500 Internal Server Error – Failed to load the revealed node
- Response JSON Object:
members[].code (string)
members[].mac (string)
members[].name (string)
members[].reason (string)
members[].status (string) – available | blocked
ok (boolean)
reason (string)
- POST /provision/network/{bmc_ip}/confirm-lease
Confirm a DHCP reservation for a node
Records the address the operator reserved on their DHCP server for a MAC of this node as its management address; provisioning then reuses it instead of allocating one.
- Parameters:
bmc_ip (string) – BMC IP address
- Request JSON Object:
address (string)
mac (string)
- Status Codes:
200 OK – bmc_ip, mac, os_ip, message and optional bookkeeping_warning
400 Bad Request – Invalid body
409 Conflict – Confirmation refused by recorded state
- POST /provision/network/{bmc_ip}/lacp-probe
Live bond test on a node being provisioned
Runs on the node’s reveal environment. 802.3ad (the default when mode is empty) forms a throwaway bond and waits for a switch LACP partner; active-backup confirms every member is present, free and has carrier. Node-side failures (not revealed, no known address, BMC unreachable, reveal validate service gone, reveal image too old, unreadable reply) are 200 with ok=false and a reason. An unsupported mode returns 200 with ok=true and no members.
- Parameters:
bmc_ip (string) – BMC IP of the revealed node
- Request JSON Object:
members[] (string)
mode (string) – Mode is active-backup or 802.3ad (empty defaults to 802.3ad). Both are tested live on the node: 802.3ad waits for a switch LACP partner; active-backup confirms every member is present, free, and has carrier now.
name (string) – Name is advisory (the ephemeral probe device is fixed); carried for symmetry.
- Status Codes:
200 OK – OK
400 Bad Request – Invalid body (need members)
404 Not Found – No BMC record or no revealed node
500 Internal Server Error – Failed to load the revealed node
- Response JSON Object:
members[].mac (string)
members[].name (string)
ok (boolean)
reason (string)
- POST /provision/network/{bmc_ip}/mgmt-mac
Get a node’s management MAC reservation
Returns the management MAC reservation view for the node; read only and idempotent.
- Parameters:
bmc_ip (string) – BMC IP address
- Status Codes:
200 OK – OK
409 Conflict – Reservation refused
- Response JSON Object:
address (string) – Address is the address on record for this plane (bmc_infos.os_ip / storage_ip), the one Configure will use; empty until observed or confirmed.
applicable (boolean) – Applicable is false when this node needs no management reservation: a STATIC pod addresses itself, and a control node declares its address at install.
bmc_ip (string)
candidates[].adapter (string) – adapter model/manufacturer when known
candidates[].link (string) – LinkStatus when reported (advisory: many NICs are unpowered with the host off)
candidates[].mac (string) – lowercase, usableMAC-validated
candidates[].name (string) – port/function name as the BMC names it
candidates[].source (string) – “adapter” | “system”
confirmed_mac (string) – ConfirmedMAC is the MAC on record for this plane: the port the operator confirmed a reservation against (ConfirmLeasedAddress / ConfirmStoragePort), or the card Karios observed the customer’s DHCP server lease to (Source says which). Empty until either.
message (string)
not_known_yet (string) – NotKnownYet is set, with the reason, when the BMC reported no usable NIC MAC.
plane (string) – “mgmt” | “storage”
source (string) – Source is the provenance of ConfirmedMAC and Address: “confirmed” (operator declared a reservation), “observed” (Karios saw the lease: the reveal for mgmt, the storage test for storage), “” (nothing on record, or recorded before provenance existed).
- POST /provision/network/{bmc_ip}/probe-lease
Probe a node’s DHCP lease
From a control node uplink carrying the pod segment, asks DHCP under the node’s MAC for one plane and reports the gateway and DHCP evidence; a probe that could not run is still a 200 with that verdict.
- Parameters:
bmc_ip (string) – BMC IP address
- Request JSON Object:
mac (string) – MAC: the factory MAC to ask under, BEFORE it is confirmed — the candidate the operator has picked from the BMC’s list (Reserve → Test → Confirm). Must be one the BMC reports for this node; empty = the confirmed MAC on the row.
plane (string) – “mgmt” (default) | “storage”
uplink (string) – control-node interface carrying the pod segment
vlan_id (integer) – VLANID: absent (nil) = the pod’s DECLARED VLAN for this plane, read from its NetBox record (PodFabric.DeclaredVID) so the operator is not asked for a number Karios already holds; 0 = untagged, explicitly; 1..4094 = an override.
wire_sweep (boolean) – WireSweep opts IN to the broadcast ping + neighbour read. OFF by default (operator, 2026-09-03): on an enterprise segment Windows and hardened Linux do not answer broadcast echo and a directed-broadcast burst is a smurf signature an IDS may flag — so its yield is near zero and it can cost a security ticket. Where it runs, a reply proves TAKEN; silence proves nothing, and nothing here ever reads silence as free.
- Status Codes:
200 OK – OK
400 Bad Request – Invalid body
409 Conflict – Probe cannot start
- Response JSON Object:
arp.broadcast (string) – the directed broadcast pinged
arp.cleared[] (string)
arp.error (string)
arp.mac_seen_at[] (string)
arp.ran (boolean)
attachment.attempts[].error (string)
attachment.attempts[].gateway_answered (boolean)
attachment.attempts[].iface (string)
attachment.attempts[].server_answered (boolean)
attachment.attempts[].uplink (string)
attachment.iface (string) – the interface actually probed on
attachment.source (string) – Source: “request” (named in the call), “remembered” (recorded for this pod on this control node), “discovered” (found by trying the physical uplinks), “default” (untagged on the management bridge).
attachment.tried[] (string)
attachment.uplink (string)
attachment.vlan_id (integer)
bmc_ip (string)
detail (string)
dhcp.error (string)
dhcp.offered (string)
dhcp.ran (boolean)
dhcp.router (string)
dhcp.server (string)
dhcp.server_answered (boolean)
dhcp.subnet_mask (string)
expected_ip (string) – confirm-lease’d address, if any
hint (string)
mac (string)
mac_source (string) – MACSource says where the MAC came from: “confirmed” (the row), “candidate” (the operator is testing one), “factory” (none confirmed — the first the BMC reports), or “probe” (the BMC reports none before boot, e.g. Supermicro X11: a locally-administered MAC derived from the uplink, asked under only to learn whether the SEGMENT answers; never persisted as the node’s).
plane (string)
probe[].address (string)
probe[].error (string)
probe[].holder_mac (string) – HolderMAC is who answered. Equal to the MAC probed under means the node itself is already up there under its current OS (a re-probe after boot) — not a collision.
probe[].in_use (boolean)
probe[].ran (boolean)
trunk (any) – Trunk is the test of whether the pod VLAN is actually carried to the probed uplink: an RFC 5227 ARP probe of the pod GATEWAY on the VLAN sub-interface. The gateway answers whatever the DHCP situation is, so its reply separates “VLAN not allowed on this NIC” (nothing answers) from “no DHCP server on this segment” (gateway answers, DHCP silent) — the 2026-08-17 LB incident, where the reply appeared the moment the VLAN was permitted.
verdict (string) – Verdict is one word for the UI to key on; Detail is the sentence the operator reads; Hint is what to change, when the verdict names something to fix (the switch port, the scope).
- GET /provision/network/{bmc_ip}/segment-check
Get a node’s segment check status
Returns the node’s management posture, pod uplinks, latest lease probe, skip decision and whether the reveal ISO mount is allowed.
- Parameters:
bmc_ip (string) – BMC IP address
- Status Codes:
200 OK – OK
404 Not Found – No BMO record for the BMC
503 Service Unavailable – Provisioning database not wired
- Response JSON Object:
bmc_ip (string)
candidates[].adapter (string) – adapter model/manufacturer when known
candidates[].link (string) – LinkStatus when reported (advisory: many NICs are unpowered with the host off)
candidates[].mac (string) – lowercase, usableMAC-validated
candidates[].name (string) – port/function name as the BMC names it
candidates[].source (string) – “adapter” | “system”
confirmed_mac (string)
expected_ip (string)
fresh (boolean) – Last is within bmo.LeaseProbeFreshFor
gateway (string)
last.bmc_ip (string)
last.checked_at (string)
last.detail (string)
last.gateway (string)
last.gateway_answered (boolean)
last.hint (string)
last.iface (string)
last.mac (string)
last.offered (string)
last.pod_id (string)
last.probe_mac (boolean) – asked under a probe MAC, not a node MAC (BMC reported none)
last.server (string)
last.tagged_seen (string) – VLAN ids whose frames arrived on the uplink, comma-separated
last.target_seen (boolean)
last.uplink (string)
last.verdict (string)
last.vlan_id (integer)
leased (boolean)
mount_allowed (boolean) – static pod, or a fresh proving probe
mount_blocked_reason (string)
not_known_yet (string)
pod_id (string)
posture (string) – “leased” | “static” | “” (unknown)
remembered_uplink (string)
skip_note (string) – the sentence every surface shows
skip_reason (string)
skipped (boolean) – Skipped: the operator recorded a BLIND reveal for this node (segment proof bypassed).
skipped_at (string)
skipped_by (string)
uplinks[].bridge (string) – Bridge names the bridge this interface is enslaved to, if any (“cloudbr0” for the management uplink). A probe on a bridge MEMBER bypasses the bridge; a tagged probe on the member is the WO-N18 attachment. Untagged on the bridge itself is the control node’s own segment.
uplinks[].carrier (boolean)
uplinks[].enslaved_to_bond (boolean) – EnslavedToBond is true when Bridge names a BOND rather than a bridge. Such a link is not an attachment the probe can use — its bond is, and the bond is listed separately.
uplinks[].kind (string) – Kind: “physical” | “bridge” | “bond” | “vlan”. The form offers physical + bond as uplinks and the management bridge for the untagged case; vlan sub-interfaces are what the probe CREATES, so they are listed only to be recognisable, never picked.
uplinks[].mac (string)
uplinks[].name (string)
vlan_id (integer)
- POST /provision/network/{bmc_ip}/segment-check/skip
Record or clear a blind reveal
Records (skip true) or clears (skip false) the operator’s decision to reveal the node without a segment proof, with who, when and why, and returns the refreshed segment check status.
- Parameters:
bmc_ip (string) – BMC IP address
- Request JSON Object:
reason (string)
skip (boolean)
- Status Codes:
200 OK – OK
400 Bad Request – Invalid body
404 Not Found – No BMO record for the BMC
500 Internal Server Error – Decision could not be recorded
503 Service Unavailable – Provisioning database not wired
- Response JSON Object:
bmc_ip (string)
candidates[].adapter (string) – adapter model/manufacturer when known
candidates[].link (string) – LinkStatus when reported (advisory: many NICs are unpowered with the host off)
candidates[].mac (string) – lowercase, usableMAC-validated
candidates[].name (string) – port/function name as the BMC names it
candidates[].source (string) – “adapter” | “system”
confirmed_mac (string)
expected_ip (string)
fresh (boolean) – Last is within bmo.LeaseProbeFreshFor
gateway (string)
last.bmc_ip (string)
last.checked_at (string)
last.detail (string)
last.gateway (string)
last.gateway_answered (boolean)
last.hint (string)
last.iface (string)
last.mac (string)
last.offered (string)
last.pod_id (string)
last.probe_mac (boolean) – asked under a probe MAC, not a node MAC (BMC reported none)
last.server (string)
last.tagged_seen (string) – VLAN ids whose frames arrived on the uplink, comma-separated
last.target_seen (boolean)
last.uplink (string)
last.verdict (string)
last.vlan_id (integer)
leased (boolean)
mount_allowed (boolean) – static pod, or a fresh proving probe
mount_blocked_reason (string)
not_known_yet (string)
pod_id (string)
posture (string) – “leased” | “static” | “” (unknown)
remembered_uplink (string)
skip_note (string) – the sentence every surface shows
skip_reason (string)
skipped (boolean) – Skipped: the operator recorded a BLIND reveal for this node (segment proof bypassed).
skipped_at (string)
skipped_by (string)
uplinks[].bridge (string) – Bridge names the bridge this interface is enslaved to, if any (“cloudbr0” for the management uplink). A probe on a bridge MEMBER bypasses the bridge; a tagged probe on the member is the WO-N18 attachment. Untagged on the bridge itself is the control node’s own segment.
uplinks[].carrier (boolean)
uplinks[].enslaved_to_bond (boolean) – EnslavedToBond is true when Bridge names a BOND rather than a bridge. Such a link is not an attachment the probe can use — its bond is, and the bond is listed separately.
uplinks[].kind (string) – Kind: “physical” | “bridge” | “bond” | “vlan”. The form offers physical + bond as uplinks and the management bridge for the untagged case; vlan sub-interfaces are what the probe CREATES, so they are listed only to be recognisable, never picked.
uplinks[].mac (string)
uplinks[].name (string)
vlan_id (integer)
- POST /provision/network/{bmc_ip}/storage-mac
Get or record a node’s storage port
With no body or an empty mac, returns the storage reservation view; with a mac, records it as the node’s storage port first and returns the refreshed view.
- Parameters:
bmc_ip (string) – BMC IP address
- Request JSON Object:
mac (string)
- Status Codes:
200 OK – OK
400 Bad Request – Invalid body
409 Conflict – Storage port or reservation refused
- Response JSON Object:
address (string) – Address is the address on record for this plane (bmc_infos.os_ip / storage_ip), the one Configure will use; empty until observed or confirmed.
applicable (boolean) – Applicable is false when this node needs no management reservation: a STATIC pod addresses itself, and a control node declares its address at install.
bmc_ip (string)
candidates[].adapter (string) – adapter model/manufacturer when known
candidates[].link (string) – LinkStatus when reported (advisory: many NICs are unpowered with the host off)
candidates[].mac (string) – lowercase, usableMAC-validated
candidates[].name (string) – port/function name as the BMC names it
candidates[].source (string) – “adapter” | “system”
confirmed_mac (string) – ConfirmedMAC is the MAC on record for this plane: the port the operator confirmed a reservation against (ConfirmLeasedAddress / ConfirmStoragePort), or the card Karios observed the customer’s DHCP server lease to (Source says which). Empty until either.
message (string)
not_known_yet (string) – NotKnownYet is set, with the reason, when the BMC reported no usable NIC MAC.
plane (string) – “mgmt” | “storage”
source (string) – Source is the provenance of ConfirmedMAC and Address: “confirmed” (operator declared a reservation), “observed” (Karios saw the lease: the reveal for mgmt, the storage test for storage), “” (nothing on record, or recorded before provenance existed).
- POST /provision/network/{bmc_ip}/validate-live
Live-test network picks on a node being provisioned
Checks the requested mgmt/storage/public/guest picks structurally, then proves them on the node’s reveal environment. A pick with members and mode is a bond: the node forms it and probes through it. The reveal/management NIC can never be a bond member. ok is true only when every requested class is both ok and proven; test outcomes are 200.
- Parameters:
bmc_ip (string) – BMC IP of the revealed node
- Request JSON Object:
guest.cidr (string) – CIDR/Gateway are optional and only meaningful when Tagged — the network this VLAN carries. Fail-closed pairing mirrors mgmtClusterFabricSeed’s existing rule for the cluster-wide fabric (a CIDR without its VLAN is the “Ceph-on-mgmt trap”): CIDR/Gateway here require Tagged=true + a valid VLANID, or they’re rejected. Untagged/dedicated topology carries no CIDR at this layer — that’s what KARIOS_<CLASS>_CIDR from mgmtClusterFabricSeed already governs for the cluster-wide case; this is the per-node manual-pick equivalent.
guest.gateway (string)
guest.interface (string)
guest.members[] (string)
guest.mode (string)
guest.name (string) – Name is the operator-facing network name for this pick (e.g. the the platform guest network “test” / “guest-shared”). Optional, and used only to label validate-live messages so an operator sees the name they chose rather than a positional “Guest 3”. The UI has it from /config’s guest_bridges[].networks[].name. Absent => the message falls back to “Guest N”.
guest.tagged (boolean)
guest.uplink (string) – Uplink names the DECLARED bond this role rides, the per-pick spelling of TemplateProvision.Uplinks. Both are accepted so a caller can say it wherever it already builds the role row; roleUplink() is the single resolver, so the two cannot drift. Empty (the default) keeps the pre-bond behaviour exactly: the pick’s Interface resolves to a MAC as before. Unlike Members (a validate-live-only TEST bond), this names a bond that the seed actually renders — it is the link between a role and Bonds.
guest.vlan_id (integer) – VLANID is required when Tagged, ignored otherwise. Valid range 1-4094 (802.1Q).
guests[].cidr (string) – CIDR/Gateway are optional and only meaningful when Tagged — the network this VLAN carries. Fail-closed pairing mirrors mgmtClusterFabricSeed’s existing rule for the cluster-wide fabric (a CIDR without its VLAN is the “Ceph-on-mgmt trap”): CIDR/Gateway here require Tagged=true + a valid VLANID, or they’re rejected. Untagged/dedicated topology carries no CIDR at this layer — that’s what KARIOS_<CLASS>_CIDR from mgmtClusterFabricSeed already governs for the cluster-wide case; this is the per-node manual-pick equivalent.
guests[].gateway (string)
guests[].interface (string)
guests[].members[] (string)
guests[].mode (string)
guests[].name (string) – Name is the operator-facing network name for this pick (e.g. the the platform guest network “test” / “guest-shared”). Optional, and used only to label validate-live messages so an operator sees the name they chose rather than a positional “Guest 3”. The UI has it from /config’s guest_bridges[].networks[].name. Absent => the message falls back to “Guest N”.
guests[].tagged (boolean)
guests[].uplink (string) – Uplink names the DECLARED bond this role rides, the per-pick spelling of TemplateProvision.Uplinks. Both are accepted so a caller can say it wherever it already builds the role row; roleUplink() is the single resolver, so the two cannot drift. Empty (the default) keeps the pre-bond behaviour exactly: the pick’s Interface resolves to a MAC as before. Unlike Members (a validate-live-only TEST bond), this names a bond that the seed actually renders — it is the link between a role and Bonds.
guests[].vlan_id (integer) – VLANID is required when Tagged, ignored otherwise. Valid range 1-4094 (802.1Q).
mgmt.interface (string)
mgmt.members[] (string)
mgmt.mode (string)
public.cidr (string) – CIDR/Gateway are optional and only meaningful when Tagged — the network this VLAN carries. Fail-closed pairing mirrors mgmtClusterFabricSeed’s existing rule for the cluster-wide fabric (a CIDR without its VLAN is the “Ceph-on-mgmt trap”): CIDR/Gateway here require Tagged=true + a valid VLANID, or they’re rejected. Untagged/dedicated topology carries no CIDR at this layer — that’s what KARIOS_<CLASS>_CIDR from mgmtClusterFabricSeed already governs for the cluster-wide case; this is the per-node manual-pick equivalent.
public.gateway (string)
public.interface (string)
public.members[] (string)
public.mode (string)
public.name (string) – Name is the operator-facing network name for this pick (e.g. the the platform guest network “test” / “guest-shared”). Optional, and used only to label validate-live messages so an operator sees the name they chose rather than a positional “Guest 3”. The UI has it from /config’s guest_bridges[].networks[].name. Absent => the message falls back to “Guest N”.
public.tagged (boolean)
public.uplink (string) – Uplink names the DECLARED bond this role rides, the per-pick spelling of TemplateProvision.Uplinks. Both are accepted so a caller can say it wherever it already builds the role row; roleUplink() is the single resolver, so the two cannot drift. Empty (the default) keeps the pre-bond behaviour exactly: the pick’s Interface resolves to a MAC as before. Unlike Members (a validate-live-only TEST bond), this names a bond that the seed actually renders — it is the link between a role and Bonds.
public.vlan_id (integer) – VLANID is required when Tagged, ignored otherwise. Valid range 1-4094 (802.1Q).
storage.cidr (string) – CIDR/Gateway are optional and only meaningful when Tagged — the network this VLAN carries. Fail-closed pairing mirrors mgmtClusterFabricSeed’s existing rule for the cluster-wide fabric (a CIDR without its VLAN is the “Ceph-on-mgmt trap”): CIDR/Gateway here require Tagged=true + a valid VLANID, or they’re rejected. Untagged/dedicated topology carries no CIDR at this layer — that’s what KARIOS_<CLASS>_CIDR from mgmtClusterFabricSeed already governs for the cluster-wide case; this is the per-node manual-pick equivalent.
storage.gateway (string)
storage.interface (string)
storage.members[] (string)
storage.mode (string)
storage.name (string) – Name is the operator-facing network name for this pick (e.g. the the platform guest network “test” / “guest-shared”). Optional, and used only to label validate-live messages so an operator sees the name they chose rather than a positional “Guest 3”. The UI has it from /config’s guest_bridges[].networks[].name. Absent => the message falls back to “Guest N”.
storage.tagged (boolean)
storage.uplink (string) – Uplink names the DECLARED bond this role rides, the per-pick spelling of TemplateProvision.Uplinks. Both are accepted so a caller can say it wherever it already builds the role row; roleUplink() is the single resolver, so the two cannot drift. Empty (the default) keeps the pre-bond behaviour exactly: the pick’s Interface resolves to a MAC as before. Unlike Members (a validate-live-only TEST bond), this names a bond that the seed actually renders — it is the link between a role and Bonds.
storage.vlan_id (integer) – VLANID is required when Tagged, ignored otherwise. Valid range 1-4094 (802.1Q).
- Status Codes:
200 OK – ok, proven, detail, classes (per-class ok, proven, detail)
400 Bad Request – Invalid body
404 Not Found – Node not found
500 Internal Server Error – Internal error
- POST /provision/network/{bmc_ip}/validate-mtu
Check picked NICs against the declared MTU
Reports whether each picked NIC can carry the MTU the cluster declared for its role, naming alternatives when not; for the management pick the node also DF-pings the control node at that size. The result is recorded as the node’s last MTU check.
- Parameters:
bmc_ip (string) – BMC IP address
- Request JSON Object:
guest.cidr (string) – CIDR/Gateway are optional and only meaningful when Tagged — the network this VLAN carries. Fail-closed pairing mirrors mgmtClusterFabricSeed’s existing rule for the cluster-wide fabric (a CIDR without its VLAN is the “Ceph-on-mgmt trap”): CIDR/Gateway here require Tagged=true + a valid VLANID, or they’re rejected. Untagged/dedicated topology carries no CIDR at this layer — that’s what KARIOS_<CLASS>_CIDR from mgmtClusterFabricSeed already governs for the cluster-wide case; this is the per-node manual-pick equivalent.
guest.gateway (string)
guest.interface (string)
guest.members[] (string)
guest.mode (string)
guest.name (string) – Name is the operator-facing network name for this pick (e.g. the the platform guest network “test” / “guest-shared”). Optional, and used only to label validate-live messages so an operator sees the name they chose rather than a positional “Guest 3”. The UI has it from /config’s guest_bridges[].networks[].name. Absent => the message falls back to “Guest N”.
guest.tagged (boolean)
guest.uplink (string) – Uplink names the DECLARED bond this role rides, the per-pick spelling of TemplateProvision.Uplinks. Both are accepted so a caller can say it wherever it already builds the role row; roleUplink() is the single resolver, so the two cannot drift. Empty (the default) keeps the pre-bond behaviour exactly: the pick’s Interface resolves to a MAC as before. Unlike Members (a validate-live-only TEST bond), this names a bond that the seed actually renders — it is the link between a role and Bonds.
guest.vlan_id (integer) – VLANID is required when Tagged, ignored otherwise. Valid range 1-4094 (802.1Q).
guests[].cidr (string) – CIDR/Gateway are optional and only meaningful when Tagged — the network this VLAN carries. Fail-closed pairing mirrors mgmtClusterFabricSeed’s existing rule for the cluster-wide fabric (a CIDR without its VLAN is the “Ceph-on-mgmt trap”): CIDR/Gateway here require Tagged=true + a valid VLANID, or they’re rejected. Untagged/dedicated topology carries no CIDR at this layer — that’s what KARIOS_<CLASS>_CIDR from mgmtClusterFabricSeed already governs for the cluster-wide case; this is the per-node manual-pick equivalent.
guests[].gateway (string)
guests[].interface (string)
guests[].members[] (string)
guests[].mode (string)
guests[].name (string) – Name is the operator-facing network name for this pick (e.g. the the platform guest network “test” / “guest-shared”). Optional, and used only to label validate-live messages so an operator sees the name they chose rather than a positional “Guest 3”. The UI has it from /config’s guest_bridges[].networks[].name. Absent => the message falls back to “Guest N”.
guests[].tagged (boolean)
guests[].uplink (string) – Uplink names the DECLARED bond this role rides, the per-pick spelling of TemplateProvision.Uplinks. Both are accepted so a caller can say it wherever it already builds the role row; roleUplink() is the single resolver, so the two cannot drift. Empty (the default) keeps the pre-bond behaviour exactly: the pick’s Interface resolves to a MAC as before. Unlike Members (a validate-live-only TEST bond), this names a bond that the seed actually renders — it is the link between a role and Bonds.
guests[].vlan_id (integer) – VLANID is required when Tagged, ignored otherwise. Valid range 1-4094 (802.1Q).
mgmt.interface (string)
mgmt.members[] (string)
mgmt.mode (string)
public.cidr (string) – CIDR/Gateway are optional and only meaningful when Tagged — the network this VLAN carries. Fail-closed pairing mirrors mgmtClusterFabricSeed’s existing rule for the cluster-wide fabric (a CIDR without its VLAN is the “Ceph-on-mgmt trap”): CIDR/Gateway here require Tagged=true + a valid VLANID, or they’re rejected. Untagged/dedicated topology carries no CIDR at this layer — that’s what KARIOS_<CLASS>_CIDR from mgmtClusterFabricSeed already governs for the cluster-wide case; this is the per-node manual-pick equivalent.
public.gateway (string)
public.interface (string)
public.members[] (string)
public.mode (string)
public.name (string) – Name is the operator-facing network name for this pick (e.g. the the platform guest network “test” / “guest-shared”). Optional, and used only to label validate-live messages so an operator sees the name they chose rather than a positional “Guest 3”. The UI has it from /config’s guest_bridges[].networks[].name. Absent => the message falls back to “Guest N”.
public.tagged (boolean)
public.uplink (string) – Uplink names the DECLARED bond this role rides, the per-pick spelling of TemplateProvision.Uplinks. Both are accepted so a caller can say it wherever it already builds the role row; roleUplink() is the single resolver, so the two cannot drift. Empty (the default) keeps the pre-bond behaviour exactly: the pick’s Interface resolves to a MAC as before. Unlike Members (a validate-live-only TEST bond), this names a bond that the seed actually renders — it is the link between a role and Bonds.
public.vlan_id (integer) – VLANID is required when Tagged, ignored otherwise. Valid range 1-4094 (802.1Q).
storage.cidr (string) – CIDR/Gateway are optional and only meaningful when Tagged — the network this VLAN carries. Fail-closed pairing mirrors mgmtClusterFabricSeed’s existing rule for the cluster-wide fabric (a CIDR without its VLAN is the “Ceph-on-mgmt trap”): CIDR/Gateway here require Tagged=true + a valid VLANID, or they’re rejected. Untagged/dedicated topology carries no CIDR at this layer — that’s what KARIOS_<CLASS>_CIDR from mgmtClusterFabricSeed already governs for the cluster-wide case; this is the per-node manual-pick equivalent.
storage.gateway (string)
storage.interface (string)
storage.members[] (string)
storage.mode (string)
storage.name (string) – Name is the operator-facing network name for this pick (e.g. the the platform guest network “test” / “guest-shared”). Optional, and used only to label validate-live messages so an operator sees the name they chose rather than a positional “Guest 3”. The UI has it from /config’s guest_bridges[].networks[].name. Absent => the message falls back to “Guest N”.
storage.tagged (boolean)
storage.uplink (string) – Uplink names the DECLARED bond this role rides, the per-pick spelling of TemplateProvision.Uplinks. Both are accepted so a caller can say it wherever it already builds the role row; roleUplink() is the single resolver, so the two cannot drift. Empty (the default) keeps the pre-bond behaviour exactly: the pick’s Interface resolves to a MAC as before. Unlike Members (a validate-live-only TEST bond), this names a bond that the seed actually renders — it is the link between a role and Bonds.
storage.vlan_id (integer) – VLANID is required when Tagged, ignored otherwise. Valid range 1-4094 (802.1Q).
- Status Codes:
200 OK – OK
400 Bad Request – Invalid body
404 Not Found – No BMC record or no revealed node
500 Internal Server Error – Revealed node could not be loaded
- Response JSON Object:
detail (string)
roles[].declared (integer)
roles[].detail (string)
roles[].interface (string)
roles[].nic.detail (string)
roles[].nic.interface (string)
roles[].nic.max_mtu (integer)
roles[].nic.requested (integer)
roles[].nic.state (string)
roles[].remedy (string) – Remedy names the other cards on this node that could carry Declared. Empty when nothing needs fixing.
roles[].role (string)
roles[].state (string)
state (string)
- POST /provision/node
Configure a single node
Validates the spec for a revealed node, runs the readiness gate, stores a per-node template and queues a one-node batch; returns 202 while the node is queued.
- Request JSON Object:
bmc_ip (string)
filter.min_cpu_cores (integer)
filter.min_disks (integer)
filter.min_ram_gb (integer)
filter.model (string)
filter.vendor (string)
id (integer)
name (string)
provision.admin_pw (string)
provision.admin_user (string)
provision.allow_mixed_sizes (boolean) – AllowMixedSizes is the user’s acknowledgment that a redundant root vdev may be built from members whose sizes differ by more than 10%. ZFS sizes a mirror/raidz vdev by its SMALLEST member, so the difference is silently wasted and usually means the wrong disk was picked. It gates KARIOS_ALLOW_MIXED_SIZES in the seed, matching the installer’s own homogeneity gate.
provision.allow_raid_vd (boolean) – AllowRaidVD is the user’s acknowledgment, captured at template creation, that the chosen disks are hardware RAID virtual disks and ZFS-on-RAID-VD is intended. It gates KARIOS_ALLOW_RAID_VD in the seed so the unattended installer only proceeds on RAID VDs when the user consented.
provision.benchmark_enabled (boolean) – BenchmarkEnabled: K-Forge opt-in mirror of setup-node’s flag; written to bmc_infos in ProvisionNodeHandler.
provision.bonds[].lacp_confirmed (boolean) – LACPConfirmed records that a ToR probe observed a real LACP partner. Required for 802.3ad: the golden refuses to render it otherwise, because the kernel has no lacp_fallback_ab and hardcoded LACP against a switch with no port-channel takes the uplink down instead of degrading.
provision.bonds[].members[] (string)
provision.bonds[].mode (string) – Mode is active-backup or 802.3ad.
provision.bonds[].mtu (integer) – MTU for the bond and its members. Zero omits the key.
provision.bonds[].name (string) – Name must be the bond device name, e.g. “bond0”.
provision.cluster (string) – Cluster names the the platform cluster a joining MANAGEMENT peer inherits (KARIOS_CLUSTER) when the running control plane cannot name it alone: a management-only control plane is not a host itself, so on a zone with several clusters the render cannot pick one and refuses, naming the candidates. Ignored for agents (their placement is the device’s cluster link) and whenever the zone holds exactly one cluster.
provision.gpus[].driver_id (integer)
provision.gpus[].mode (string)
provision.gpus[].pci_address (string)
provision.guest_nic (string)
provision.manual (any) – Manual network topology (2026-07-31): explicit per-traffic interface + tagging mode, bypassing reveal-candidate auto-detect entirely. nil/absent fields fall back to the existing StorageNIC/PublicNIC/GuestNIC candidate-matching path unchanged. See ManualNIC.
provision.mgmt_uplink (string) – MgmtUplink names which declared bond carries the management path. That bond is the one the golden enslaves to cloudbr0; every other is rendered standalone for the role VLANs to attach to.
provision.nic (string)
provision.public_nic (string)
provision.role (string)
provision.storage_cidr (string) – StorageCIDR is the greenfield first-node override. On node-1 of a fresh cluster there is no storage peer to ARP and no LLDP storage VLAN, so the reveal yields no storage fabric to inherit; set this explicitly to seed STORAGE_CIDR directly and bootstrap the storage island instead of deadlocking. Ignored once the cluster fabric already supplies a storage CIDR.
provision.storage_nic (string) – Per-traffic NIC overrides, mirror of NIC for mgmt: empty or “auto” means auto-select from the reveal’s per-traffic candidates; a value is matched by NAME or MAC against that traffic’s candidate set and resolves the >=2-candidate case. Guest is user-assigned (GuestNIC carries the chosen base-bridge name = the PhysicalNetwork Tag).
provision.uplinks (object) – Uplinks is the per-role uplink map, the port of the installer’s networks.uplinks (Karios-installer parse.rs parse_role_uplinks). Keys are STORAGE/PUBLIC (MGMT keeps MgmtUplink above); a value names a DECLARED bond. It exists because a role could not otherwise ride a bond. The auto/manual NIC pick resolves to a physical MAC, and the golden’s resolve_uplink (karios-fb-net.sh:96-107) treats a MAC as THAT NIC — so a role whose pick happened to be a bond member rendered its VLAN on an ENSLAVED slave. The installer states the same rule: “a bond rides the <ROLE>_UPLINK path instead, and enslaving a bond as a raw role NIC would break it” (parse.rs untagged_role_nic_mac). A bond therefore reaches a role by NAME through <ROLE>_UPLINK, and a <ROLE>_NIC_SELECTOR must never name one. GUEST is accepted too. The zone still owns what the guest bridge is CALLED (its traffic label); this only says which WIRE that bridge rides, and a bond is as valid there as anywhere else. Refusing it left the member MAC as the only expressible option — which is the broken one.
provision.use_default_creds (boolean)
storage.db_offload (boolean) – DbOffload is the user’s intent, captured at template creation, to place each rotational (HDD) data OSD’s RocksDB block.db on a fast device on hybrid hosts instead of making every disk a co-equal standalone OSD. BMO only CARRIES this intent into the seed (KARIOS_DB_OFFLOAD); the on-node INSTALLER — which has the real disk inventory — designates the concrete fast device’s by-id into OSD_DB_BYID (hwprofile.env) subject to the durability floor, and the golden is a pure validating consumer. Absent/false => no key is emitted and behavior is byte-identical (all-NVMe/all-HDD/uniform unaffected).
storage.disk_size_gb (integer) – DiskSizeGB optionally targets a specific OS-disk size (e.g. 200 to pick the 200GB SSDs on a node that also has 400GB SSDs). 0 = no size filter; the matcher then prefers the smallest usable disks for the root vdev.
storage.disk_type (string)
storage.include_raid_vds (boolean)
storage.max_size_gb (integer)
storage.min_size_gb (integer)
storage.os_disk_count (integer)
storage.os_disks[] (string)
storage.topology (string)
- Status Codes:
202 Accepted – bmc_ip and state
400 Bad Request – Invalid body or spec, unrevealed node, or provision config incomplete
409 Conflict – Node already being configured
422 Unprocessable Entity – Readiness checks blocking
500 Internal Server Error – Config or database error
- GET /provision/nodes
List revealed nodes
Returns the revealed nodes with an MTU shortfall flag against the cluster’s declared MTUs, optionally paged with limit and offset.
- Query Parameters:
state (string) – Only revealed is supported
limit (integer) – Page size; 0 or absent returns all
offset (integer) – Page offset
- Status Codes:
200 OK – total and nodes (provision.RevealedNode list)
400 Bad Request – Unsupported state
500 Internal Server Error – Database error
- GET /provision/onboard-readiness
Get onboarding readiness
Returns the composite readiness verdict: cluster sections (control plane, ceph, artifacts), plus per-node sections when bmc_ip is given.
- Query Parameters:
bmc_ip (string) – Add per-node sections for this BMC
- Status Codes:
200 OK – OK
- Response JSON Object:
blocking[].code (string)
blocking[].field (string) – tier B only; same dotted names apiErrField emits (e.g. “storage.os_disks”)
blocking[].reason (string)
blocking[].severity (string)
blocking[].summary (string)
blocking[].tier (string) – “A” (modal open) | “B” (field change) | “C” (Configure click)
detail (string)
ready (boolean)
scope (string) – “cluster” (no bmc_ip) | “node”
sections (object) – per-executor detail
status (string)
warnings[].code (string)
warnings[].field (string) – tier B only; same dotted names apiErrField emits (e.g. “storage.os_disks”)
warnings[].reason (string)
warnings[].severity (string)
warnings[].summary (string)
warnings[].tier (string) – “A” (modal open) | “B” (field change) | “C” (Configure click)
- GET /provision/preflight
Check provisioning artifacts
Probes the serving dependencies a metal provision needs (installer ISO, netfetch install.squashfs, seed service, golden image, reveal base ISO); ok is false when any check fails.
- Status Codes:
200 OK – OK
- Response JSON Object:
checks[].detail (string)
checks[].name (string)
checks[].ok (boolean)
ok (boolean)
- GET /provision/progress/{bmc_ip}
Get provision progress for a node
Returns the latest batch item progress for a BMC with its stage log history; a failure message is replaced by its failure class and possible causes.
- Parameters:
bmc_ip (string) – BMC IP address
- Status Codes:
200 OK – bmc_ip, batch_id, state, phase, progress, message, failure_class, possible_causes and log
404 Not Found – BMC has never been in a batch
- POST /provision/render-seed
Render a node seed
Renders and stores the installer answer file for a revealed node from a template and the provision config, and reports disk matches, the assigned IP and golden image validation.
- Status Codes:
200 OK – seed_id, seed_url, answer_env and validation
400 Bad Request – Invalid body, missing field or seed render refused
404 Not Found – Template or node not found
409 Conflict – Node not revealed yet
500 Internal Server Error – Database or render error
- GET /provision/seeds/{file}
Get a rendered seed file
Returns the stored answer file for a seed ID as plain text; the .env suffix on the file name is optional.
- Parameters:
file (string) – Seed ID, optionally with .env suffix
- Status Codes:
200 OK – Answer file contents
400 Bad Request – Invalid seed ID
404 Not Found – Seed not found
- GET /provision/templates
List provision templates
Returns every stored provisioning template ordered by ID; rows whose spec cannot be decoded are skipped.
- Status Codes:
200 OK – total and templates (provision.TemplateSpec list)
500 Internal Server Error – Database error
- POST /provision/templates
Create a provision template
Creates a provisioning template. Bonds for a node being onboarded are declared here under provision.bonds (members are MAC addresses), with provision.mgmt_uplink naming the management bond and provision.uplinks mapping roles to bond names. Bonds are checked when the seed is rendered for a node, not at save time.
- Request JSON Object:
filter.min_cpu_cores (integer)
filter.min_disks (integer)
filter.min_ram_gb (integer)
filter.model (string)
filter.vendor (string)
id (integer)
name (string)
provision.admin_pw (string)
provision.admin_user (string)
provision.allow_mixed_sizes (boolean) – AllowMixedSizes is the user’s acknowledgment that a redundant root vdev may be built from members whose sizes differ by more than 10%. ZFS sizes a mirror/raidz vdev by its SMALLEST member, so the difference is silently wasted and usually means the wrong disk was picked. It gates KARIOS_ALLOW_MIXED_SIZES in the seed, matching the installer’s own homogeneity gate.
provision.allow_raid_vd (boolean) – AllowRaidVD is the user’s acknowledgment, captured at template creation, that the chosen disks are hardware RAID virtual disks and ZFS-on-RAID-VD is intended. It gates KARIOS_ALLOW_RAID_VD in the seed so the unattended installer only proceeds on RAID VDs when the user consented.
provision.benchmark_enabled (boolean) – BenchmarkEnabled: K-Forge opt-in mirror of setup-node’s flag; written to bmc_infos in ProvisionNodeHandler.
provision.bonds[].lacp_confirmed (boolean) – LACPConfirmed records that a ToR probe observed a real LACP partner. Required for 802.3ad: the golden refuses to render it otherwise, because the kernel has no lacp_fallback_ab and hardcoded LACP against a switch with no port-channel takes the uplink down instead of degrading.
provision.bonds[].members[] (string)
provision.bonds[].mode (string) – Mode is active-backup or 802.3ad.
provision.bonds[].mtu (integer) – MTU for the bond and its members. Zero omits the key.
provision.bonds[].name (string) – Name must be the bond device name, e.g. “bond0”.
provision.cluster (string) – Cluster names the the platform cluster a joining MANAGEMENT peer inherits (KARIOS_CLUSTER) when the running control plane cannot name it alone: a management-only control plane is not a host itself, so on a zone with several clusters the render cannot pick one and refuses, naming the candidates. Ignored for agents (their placement is the device’s cluster link) and whenever the zone holds exactly one cluster.
provision.gpus[].driver_id (integer)
provision.gpus[].mode (string)
provision.gpus[].pci_address (string)
provision.guest_nic (string)
provision.manual (any) – Manual network topology (2026-07-31): explicit per-traffic interface + tagging mode, bypassing reveal-candidate auto-detect entirely. nil/absent fields fall back to the existing StorageNIC/PublicNIC/GuestNIC candidate-matching path unchanged. See ManualNIC.
provision.mgmt_uplink (string) – MgmtUplink names which declared bond carries the management path. That bond is the one the golden enslaves to cloudbr0; every other is rendered standalone for the role VLANs to attach to.
provision.nic (string)
provision.public_nic (string)
provision.role (string)
provision.storage_cidr (string) – StorageCIDR is the greenfield first-node override. On node-1 of a fresh cluster there is no storage peer to ARP and no LLDP storage VLAN, so the reveal yields no storage fabric to inherit; set this explicitly to seed STORAGE_CIDR directly and bootstrap the storage island instead of deadlocking. Ignored once the cluster fabric already supplies a storage CIDR.
provision.storage_nic (string) – Per-traffic NIC overrides, mirror of NIC for mgmt: empty or “auto” means auto-select from the reveal’s per-traffic candidates; a value is matched by NAME or MAC against that traffic’s candidate set and resolves the >=2-candidate case. Guest is user-assigned (GuestNIC carries the chosen base-bridge name = the PhysicalNetwork Tag).
provision.uplinks (object) – Uplinks is the per-role uplink map, the port of the installer’s networks.uplinks (Karios-installer parse.rs parse_role_uplinks). Keys are STORAGE/PUBLIC (MGMT keeps MgmtUplink above); a value names a DECLARED bond. It exists because a role could not otherwise ride a bond. The auto/manual NIC pick resolves to a physical MAC, and the golden’s resolve_uplink (karios-fb-net.sh:96-107) treats a MAC as THAT NIC — so a role whose pick happened to be a bond member rendered its VLAN on an ENSLAVED slave. The installer states the same rule: “a bond rides the <ROLE>_UPLINK path instead, and enslaving a bond as a raw role NIC would break it” (parse.rs untagged_role_nic_mac). A bond therefore reaches a role by NAME through <ROLE>_UPLINK, and a <ROLE>_NIC_SELECTOR must never name one. GUEST is accepted too. The zone still owns what the guest bridge is CALLED (its traffic label); this only says which WIRE that bridge rides, and a bond is as valid there as anywhere else. Refusing it left the member MAC as the only expressible option — which is the broken one.
provision.use_default_creds (boolean)
storage.db_offload (boolean) – DbOffload is the user’s intent, captured at template creation, to place each rotational (HDD) data OSD’s RocksDB block.db on a fast device on hybrid hosts instead of making every disk a co-equal standalone OSD. BMO only CARRIES this intent into the seed (KARIOS_DB_OFFLOAD); the on-node INSTALLER — which has the real disk inventory — designates the concrete fast device’s by-id into OSD_DB_BYID (hwprofile.env) subject to the durability floor, and the golden is a pure validating consumer. Absent/false => no key is emitted and behavior is byte-identical (all-NVMe/all-HDD/uniform unaffected).
storage.disk_size_gb (integer) – DiskSizeGB optionally targets a specific OS-disk size (e.g. 200 to pick the 200GB SSDs on a node that also has 400GB SSDs). 0 = no size filter; the matcher then prefers the smallest usable disks for the root vdev.
storage.disk_type (string)
storage.include_raid_vds (boolean)
storage.max_size_gb (integer)
storage.min_size_gb (integer)
storage.os_disk_count (integer)
storage.os_disks[] (string)
storage.topology (string)
- Status Codes:
201 Created – Created
400 Bad Request – Invalid body or spec
409 Conflict – A template with this name already exists
500 Internal Server Error – Database error
- Response JSON Object:
filter.min_cpu_cores (integer)
filter.min_disks (integer)
filter.min_ram_gb (integer)
filter.model (string)
filter.vendor (string)
id (integer)
name (string)
provision.admin_pw (string)
provision.admin_user (string)
provision.allow_mixed_sizes (boolean) – AllowMixedSizes is the user’s acknowledgment that a redundant root vdev may be built from members whose sizes differ by more than 10%. ZFS sizes a mirror/raidz vdev by its SMALLEST member, so the difference is silently wasted and usually means the wrong disk was picked. It gates KARIOS_ALLOW_MIXED_SIZES in the seed, matching the installer’s own homogeneity gate.
provision.allow_raid_vd (boolean) – AllowRaidVD is the user’s acknowledgment, captured at template creation, that the chosen disks are hardware RAID virtual disks and ZFS-on-RAID-VD is intended. It gates KARIOS_ALLOW_RAID_VD in the seed so the unattended installer only proceeds on RAID VDs when the user consented.
provision.benchmark_enabled (boolean) – BenchmarkEnabled: K-Forge opt-in mirror of setup-node’s flag; written to bmc_infos in ProvisionNodeHandler.
provision.bonds[].lacp_confirmed (boolean) – LACPConfirmed records that a ToR probe observed a real LACP partner. Required for 802.3ad: the golden refuses to render it otherwise, because the kernel has no lacp_fallback_ab and hardcoded LACP against a switch with no port-channel takes the uplink down instead of degrading.
provision.bonds[].members[] (string)
provision.bonds[].mode (string) – Mode is active-backup or 802.3ad.
provision.bonds[].mtu (integer) – MTU for the bond and its members. Zero omits the key.
provision.bonds[].name (string) – Name must be the bond device name, e.g. “bond0”.
provision.cluster (string) – Cluster names the the platform cluster a joining MANAGEMENT peer inherits (KARIOS_CLUSTER) when the running control plane cannot name it alone: a management-only control plane is not a host itself, so on a zone with several clusters the render cannot pick one and refuses, naming the candidates. Ignored for agents (their placement is the device’s cluster link) and whenever the zone holds exactly one cluster.
provision.gpus[].driver_id (integer)
provision.gpus[].mode (string)
provision.gpus[].pci_address (string)
provision.guest_nic (string)
provision.manual (any) – Manual network topology (2026-07-31): explicit per-traffic interface + tagging mode, bypassing reveal-candidate auto-detect entirely. nil/absent fields fall back to the existing StorageNIC/PublicNIC/GuestNIC candidate-matching path unchanged. See ManualNIC.
provision.mgmt_uplink (string) – MgmtUplink names which declared bond carries the management path. That bond is the one the golden enslaves to cloudbr0; every other is rendered standalone for the role VLANs to attach to.
provision.nic (string)
provision.public_nic (string)
provision.role (string)
provision.storage_cidr (string) – StorageCIDR is the greenfield first-node override. On node-1 of a fresh cluster there is no storage peer to ARP and no LLDP storage VLAN, so the reveal yields no storage fabric to inherit; set this explicitly to seed STORAGE_CIDR directly and bootstrap the storage island instead of deadlocking. Ignored once the cluster fabric already supplies a storage CIDR.
provision.storage_nic (string) – Per-traffic NIC overrides, mirror of NIC for mgmt: empty or “auto” means auto-select from the reveal’s per-traffic candidates; a value is matched by NAME or MAC against that traffic’s candidate set and resolves the >=2-candidate case. Guest is user-assigned (GuestNIC carries the chosen base-bridge name = the PhysicalNetwork Tag).
provision.uplinks (object) – Uplinks is the per-role uplink map, the port of the installer’s networks.uplinks (Karios-installer parse.rs parse_role_uplinks). Keys are STORAGE/PUBLIC (MGMT keeps MgmtUplink above); a value names a DECLARED bond. It exists because a role could not otherwise ride a bond. The auto/manual NIC pick resolves to a physical MAC, and the golden’s resolve_uplink (karios-fb-net.sh:96-107) treats a MAC as THAT NIC — so a role whose pick happened to be a bond member rendered its VLAN on an ENSLAVED slave. The installer states the same rule: “a bond rides the <ROLE>_UPLINK path instead, and enslaving a bond as a raw role NIC would break it” (parse.rs untagged_role_nic_mac). A bond therefore reaches a role by NAME through <ROLE>_UPLINK, and a <ROLE>_NIC_SELECTOR must never name one. GUEST is accepted too. The zone still owns what the guest bridge is CALLED (its traffic label); this only says which WIRE that bridge rides, and a bond is as valid there as anywhere else. Refusing it left the member MAC as the only expressible option — which is the broken one.
provision.use_default_creds (boolean)
storage.db_offload (boolean) – DbOffload is the user’s intent, captured at template creation, to place each rotational (HDD) data OSD’s RocksDB block.db on a fast device on hybrid hosts instead of making every disk a co-equal standalone OSD. BMO only CARRIES this intent into the seed (KARIOS_DB_OFFLOAD); the on-node INSTALLER — which has the real disk inventory — designates the concrete fast device’s by-id into OSD_DB_BYID (hwprofile.env) subject to the durability floor, and the golden is a pure validating consumer. Absent/false => no key is emitted and behavior is byte-identical (all-NVMe/all-HDD/uniform unaffected).
storage.disk_size_gb (integer) – DiskSizeGB optionally targets a specific OS-disk size (e.g. 200 to pick the 200GB SSDs on a node that also has 400GB SSDs). 0 = no size filter; the matcher then prefers the smallest usable disks for the root vdev.
storage.disk_type (string)
storage.include_raid_vds (boolean)
storage.max_size_gb (integer)
storage.min_size_gb (integer)
storage.os_disk_count (integer)
storage.os_disks[] (string)
storage.topology (string)
- GET /provision/templates/{id}
Get a provision template
Returns one provisioning template by ID.
- Parameters:
id (integer) – Template ID
- Status Codes:
200 OK – OK
400 Bad Request – Invalid template ID
404 Not Found – Template not found
500 Internal Server Error – Database error
- Response JSON Object:
filter.min_cpu_cores (integer)
filter.min_disks (integer)
filter.min_ram_gb (integer)
filter.model (string)
filter.vendor (string)
id (integer)
name (string)
provision.admin_pw (string)
provision.admin_user (string)
provision.allow_mixed_sizes (boolean) – AllowMixedSizes is the user’s acknowledgment that a redundant root vdev may be built from members whose sizes differ by more than 10%. ZFS sizes a mirror/raidz vdev by its SMALLEST member, so the difference is silently wasted and usually means the wrong disk was picked. It gates KARIOS_ALLOW_MIXED_SIZES in the seed, matching the installer’s own homogeneity gate.
provision.allow_raid_vd (boolean) – AllowRaidVD is the user’s acknowledgment, captured at template creation, that the chosen disks are hardware RAID virtual disks and ZFS-on-RAID-VD is intended. It gates KARIOS_ALLOW_RAID_VD in the seed so the unattended installer only proceeds on RAID VDs when the user consented.
provision.benchmark_enabled (boolean) – BenchmarkEnabled: K-Forge opt-in mirror of setup-node’s flag; written to bmc_infos in ProvisionNodeHandler.
provision.bonds[].lacp_confirmed (boolean) – LACPConfirmed records that a ToR probe observed a real LACP partner. Required for 802.3ad: the golden refuses to render it otherwise, because the kernel has no lacp_fallback_ab and hardcoded LACP against a switch with no port-channel takes the uplink down instead of degrading.
provision.bonds[].members[] (string)
provision.bonds[].mode (string) – Mode is active-backup or 802.3ad.
provision.bonds[].mtu (integer) – MTU for the bond and its members. Zero omits the key.
provision.bonds[].name (string) – Name must be the bond device name, e.g. “bond0”.
provision.cluster (string) – Cluster names the the platform cluster a joining MANAGEMENT peer inherits (KARIOS_CLUSTER) when the running control plane cannot name it alone: a management-only control plane is not a host itself, so on a zone with several clusters the render cannot pick one and refuses, naming the candidates. Ignored for agents (their placement is the device’s cluster link) and whenever the zone holds exactly one cluster.
provision.gpus[].driver_id (integer)
provision.gpus[].mode (string)
provision.gpus[].pci_address (string)
provision.guest_nic (string)
provision.manual (any) – Manual network topology (2026-07-31): explicit per-traffic interface + tagging mode, bypassing reveal-candidate auto-detect entirely. nil/absent fields fall back to the existing StorageNIC/PublicNIC/GuestNIC candidate-matching path unchanged. See ManualNIC.
provision.mgmt_uplink (string) – MgmtUplink names which declared bond carries the management path. That bond is the one the golden enslaves to cloudbr0; every other is rendered standalone for the role VLANs to attach to.
provision.nic (string)
provision.public_nic (string)
provision.role (string)
provision.storage_cidr (string) – StorageCIDR is the greenfield first-node override. On node-1 of a fresh cluster there is no storage peer to ARP and no LLDP storage VLAN, so the reveal yields no storage fabric to inherit; set this explicitly to seed STORAGE_CIDR directly and bootstrap the storage island instead of deadlocking. Ignored once the cluster fabric already supplies a storage CIDR.
provision.storage_nic (string) – Per-traffic NIC overrides, mirror of NIC for mgmt: empty or “auto” means auto-select from the reveal’s per-traffic candidates; a value is matched by NAME or MAC against that traffic’s candidate set and resolves the >=2-candidate case. Guest is user-assigned (GuestNIC carries the chosen base-bridge name = the PhysicalNetwork Tag).
provision.uplinks (object) – Uplinks is the per-role uplink map, the port of the installer’s networks.uplinks (Karios-installer parse.rs parse_role_uplinks). Keys are STORAGE/PUBLIC (MGMT keeps MgmtUplink above); a value names a DECLARED bond. It exists because a role could not otherwise ride a bond. The auto/manual NIC pick resolves to a physical MAC, and the golden’s resolve_uplink (karios-fb-net.sh:96-107) treats a MAC as THAT NIC — so a role whose pick happened to be a bond member rendered its VLAN on an ENSLAVED slave. The installer states the same rule: “a bond rides the <ROLE>_UPLINK path instead, and enslaving a bond as a raw role NIC would break it” (parse.rs untagged_role_nic_mac). A bond therefore reaches a role by NAME through <ROLE>_UPLINK, and a <ROLE>_NIC_SELECTOR must never name one. GUEST is accepted too. The zone still owns what the guest bridge is CALLED (its traffic label); this only says which WIRE that bridge rides, and a bond is as valid there as anywhere else. Refusing it left the member MAC as the only expressible option — which is the broken one.
provision.use_default_creds (boolean)
storage.db_offload (boolean) – DbOffload is the user’s intent, captured at template creation, to place each rotational (HDD) data OSD’s RocksDB block.db on a fast device on hybrid hosts instead of making every disk a co-equal standalone OSD. BMO only CARRIES this intent into the seed (KARIOS_DB_OFFLOAD); the on-node INSTALLER — which has the real disk inventory — designates the concrete fast device’s by-id into OSD_DB_BYID (hwprofile.env) subject to the durability floor, and the golden is a pure validating consumer. Absent/false => no key is emitted and behavior is byte-identical (all-NVMe/all-HDD/uniform unaffected).
storage.disk_size_gb (integer) – DiskSizeGB optionally targets a specific OS-disk size (e.g. 200 to pick the 200GB SSDs on a node that also has 400GB SSDs). 0 = no size filter; the matcher then prefers the smallest usable disks for the root vdev.
storage.disk_type (string)
storage.include_raid_vds (boolean)
storage.max_size_gb (integer)
storage.min_size_gb (integer)
storage.os_disk_count (integer)
storage.os_disks[] (string)
storage.topology (string)
- PUT /provision/templates/{id}
Update a provision template
Replaces a provisioning template’s spec, including its declared bonds (provision.bonds, provision.mgmt_uplink, provision.uplinks). Bonds are checked when the seed is rendered for a node, not at save time.
- Parameters:
id (integer) – Template ID
- Request JSON Object:
filter.min_cpu_cores (integer)
filter.min_disks (integer)
filter.min_ram_gb (integer)
filter.model (string)
filter.vendor (string)
id (integer)
name (string)
provision.admin_pw (string)
provision.admin_user (string)
provision.allow_mixed_sizes (boolean) – AllowMixedSizes is the user’s acknowledgment that a redundant root vdev may be built from members whose sizes differ by more than 10%. ZFS sizes a mirror/raidz vdev by its SMALLEST member, so the difference is silently wasted and usually means the wrong disk was picked. It gates KARIOS_ALLOW_MIXED_SIZES in the seed, matching the installer’s own homogeneity gate.
provision.allow_raid_vd (boolean) – AllowRaidVD is the user’s acknowledgment, captured at template creation, that the chosen disks are hardware RAID virtual disks and ZFS-on-RAID-VD is intended. It gates KARIOS_ALLOW_RAID_VD in the seed so the unattended installer only proceeds on RAID VDs when the user consented.
provision.benchmark_enabled (boolean) – BenchmarkEnabled: K-Forge opt-in mirror of setup-node’s flag; written to bmc_infos in ProvisionNodeHandler.
provision.bonds[].lacp_confirmed (boolean) – LACPConfirmed records that a ToR probe observed a real LACP partner. Required for 802.3ad: the golden refuses to render it otherwise, because the kernel has no lacp_fallback_ab and hardcoded LACP against a switch with no port-channel takes the uplink down instead of degrading.
provision.bonds[].members[] (string)
provision.bonds[].mode (string) – Mode is active-backup or 802.3ad.
provision.bonds[].mtu (integer) – MTU for the bond and its members. Zero omits the key.
provision.bonds[].name (string) – Name must be the bond device name, e.g. “bond0”.
provision.cluster (string) – Cluster names the the platform cluster a joining MANAGEMENT peer inherits (KARIOS_CLUSTER) when the running control plane cannot name it alone: a management-only control plane is not a host itself, so on a zone with several clusters the render cannot pick one and refuses, naming the candidates. Ignored for agents (their placement is the device’s cluster link) and whenever the zone holds exactly one cluster.
provision.gpus[].driver_id (integer)
provision.gpus[].mode (string)
provision.gpus[].pci_address (string)
provision.guest_nic (string)
provision.manual (any) – Manual network topology (2026-07-31): explicit per-traffic interface + tagging mode, bypassing reveal-candidate auto-detect entirely. nil/absent fields fall back to the existing StorageNIC/PublicNIC/GuestNIC candidate-matching path unchanged. See ManualNIC.
provision.mgmt_uplink (string) – MgmtUplink names which declared bond carries the management path. That bond is the one the golden enslaves to cloudbr0; every other is rendered standalone for the role VLANs to attach to.
provision.nic (string)
provision.public_nic (string)
provision.role (string)
provision.storage_cidr (string) – StorageCIDR is the greenfield first-node override. On node-1 of a fresh cluster there is no storage peer to ARP and no LLDP storage VLAN, so the reveal yields no storage fabric to inherit; set this explicitly to seed STORAGE_CIDR directly and bootstrap the storage island instead of deadlocking. Ignored once the cluster fabric already supplies a storage CIDR.
provision.storage_nic (string) – Per-traffic NIC overrides, mirror of NIC for mgmt: empty or “auto” means auto-select from the reveal’s per-traffic candidates; a value is matched by NAME or MAC against that traffic’s candidate set and resolves the >=2-candidate case. Guest is user-assigned (GuestNIC carries the chosen base-bridge name = the PhysicalNetwork Tag).
provision.uplinks (object) – Uplinks is the per-role uplink map, the port of the installer’s networks.uplinks (Karios-installer parse.rs parse_role_uplinks). Keys are STORAGE/PUBLIC (MGMT keeps MgmtUplink above); a value names a DECLARED bond. It exists because a role could not otherwise ride a bond. The auto/manual NIC pick resolves to a physical MAC, and the golden’s resolve_uplink (karios-fb-net.sh:96-107) treats a MAC as THAT NIC — so a role whose pick happened to be a bond member rendered its VLAN on an ENSLAVED slave. The installer states the same rule: “a bond rides the <ROLE>_UPLINK path instead, and enslaving a bond as a raw role NIC would break it” (parse.rs untagged_role_nic_mac). A bond therefore reaches a role by NAME through <ROLE>_UPLINK, and a <ROLE>_NIC_SELECTOR must never name one. GUEST is accepted too. The zone still owns what the guest bridge is CALLED (its traffic label); this only says which WIRE that bridge rides, and a bond is as valid there as anywhere else. Refusing it left the member MAC as the only expressible option — which is the broken one.
provision.use_default_creds (boolean)
storage.db_offload (boolean) – DbOffload is the user’s intent, captured at template creation, to place each rotational (HDD) data OSD’s RocksDB block.db on a fast device on hybrid hosts instead of making every disk a co-equal standalone OSD. BMO only CARRIES this intent into the seed (KARIOS_DB_OFFLOAD); the on-node INSTALLER — which has the real disk inventory — designates the concrete fast device’s by-id into OSD_DB_BYID (hwprofile.env) subject to the durability floor, and the golden is a pure validating consumer. Absent/false => no key is emitted and behavior is byte-identical (all-NVMe/all-HDD/uniform unaffected).
storage.disk_size_gb (integer) – DiskSizeGB optionally targets a specific OS-disk size (e.g. 200 to pick the 200GB SSDs on a node that also has 400GB SSDs). 0 = no size filter; the matcher then prefers the smallest usable disks for the root vdev.
storage.disk_type (string)
storage.include_raid_vds (boolean)
storage.max_size_gb (integer)
storage.min_size_gb (integer)
storage.os_disk_count (integer)
storage.os_disks[] (string)
storage.topology (string)
- Status Codes:
200 OK – OK
400 Bad Request – Invalid ID, body or spec
404 Not Found – Template not found
409 Conflict – Another template has this name
500 Internal Server Error – Database error
- Response JSON Object:
filter.min_cpu_cores (integer)
filter.min_disks (integer)
filter.min_ram_gb (integer)
filter.model (string)
filter.vendor (string)
id (integer)
name (string)
provision.admin_pw (string)
provision.admin_user (string)
provision.allow_mixed_sizes (boolean) – AllowMixedSizes is the user’s acknowledgment that a redundant root vdev may be built from members whose sizes differ by more than 10%. ZFS sizes a mirror/raidz vdev by its SMALLEST member, so the difference is silently wasted and usually means the wrong disk was picked. It gates KARIOS_ALLOW_MIXED_SIZES in the seed, matching the installer’s own homogeneity gate.
provision.allow_raid_vd (boolean) – AllowRaidVD is the user’s acknowledgment, captured at template creation, that the chosen disks are hardware RAID virtual disks and ZFS-on-RAID-VD is intended. It gates KARIOS_ALLOW_RAID_VD in the seed so the unattended installer only proceeds on RAID VDs when the user consented.
provision.benchmark_enabled (boolean) – BenchmarkEnabled: K-Forge opt-in mirror of setup-node’s flag; written to bmc_infos in ProvisionNodeHandler.
provision.bonds[].lacp_confirmed (boolean) – LACPConfirmed records that a ToR probe observed a real LACP partner. Required for 802.3ad: the golden refuses to render it otherwise, because the kernel has no lacp_fallback_ab and hardcoded LACP against a switch with no port-channel takes the uplink down instead of degrading.
provision.bonds[].members[] (string)
provision.bonds[].mode (string) – Mode is active-backup or 802.3ad.
provision.bonds[].mtu (integer) – MTU for the bond and its members. Zero omits the key.
provision.bonds[].name (string) – Name must be the bond device name, e.g. “bond0”.
provision.cluster (string) – Cluster names the the platform cluster a joining MANAGEMENT peer inherits (KARIOS_CLUSTER) when the running control plane cannot name it alone: a management-only control plane is not a host itself, so on a zone with several clusters the render cannot pick one and refuses, naming the candidates. Ignored for agents (their placement is the device’s cluster link) and whenever the zone holds exactly one cluster.
provision.gpus[].driver_id (integer)
provision.gpus[].mode (string)
provision.gpus[].pci_address (string)
provision.guest_nic (string)
provision.manual (any) – Manual network topology (2026-07-31): explicit per-traffic interface + tagging mode, bypassing reveal-candidate auto-detect entirely. nil/absent fields fall back to the existing StorageNIC/PublicNIC/GuestNIC candidate-matching path unchanged. See ManualNIC.
provision.mgmt_uplink (string) – MgmtUplink names which declared bond carries the management path. That bond is the one the golden enslaves to cloudbr0; every other is rendered standalone for the role VLANs to attach to.
provision.nic (string)
provision.public_nic (string)
provision.role (string)
provision.storage_cidr (string) – StorageCIDR is the greenfield first-node override. On node-1 of a fresh cluster there is no storage peer to ARP and no LLDP storage VLAN, so the reveal yields no storage fabric to inherit; set this explicitly to seed STORAGE_CIDR directly and bootstrap the storage island instead of deadlocking. Ignored once the cluster fabric already supplies a storage CIDR.
provision.storage_nic (string) – Per-traffic NIC overrides, mirror of NIC for mgmt: empty or “auto” means auto-select from the reveal’s per-traffic candidates; a value is matched by NAME or MAC against that traffic’s candidate set and resolves the >=2-candidate case. Guest is user-assigned (GuestNIC carries the chosen base-bridge name = the PhysicalNetwork Tag).
provision.uplinks (object) – Uplinks is the per-role uplink map, the port of the installer’s networks.uplinks (Karios-installer parse.rs parse_role_uplinks). Keys are STORAGE/PUBLIC (MGMT keeps MgmtUplink above); a value names a DECLARED bond. It exists because a role could not otherwise ride a bond. The auto/manual NIC pick resolves to a physical MAC, and the golden’s resolve_uplink (karios-fb-net.sh:96-107) treats a MAC as THAT NIC — so a role whose pick happened to be a bond member rendered its VLAN on an ENSLAVED slave. The installer states the same rule: “a bond rides the <ROLE>_UPLINK path instead, and enslaving a bond as a raw role NIC would break it” (parse.rs untagged_role_nic_mac). A bond therefore reaches a role by NAME through <ROLE>_UPLINK, and a <ROLE>_NIC_SELECTOR must never name one. GUEST is accepted too. The zone still owns what the guest bridge is CALLED (its traffic label); this only says which WIRE that bridge rides, and a bond is as valid there as anywhere else. Refusing it left the member MAC as the only expressible option — which is the broken one.
provision.use_default_creds (boolean)
storage.db_offload (boolean) – DbOffload is the user’s intent, captured at template creation, to place each rotational (HDD) data OSD’s RocksDB block.db on a fast device on hybrid hosts instead of making every disk a co-equal standalone OSD. BMO only CARRIES this intent into the seed (KARIOS_DB_OFFLOAD); the on-node INSTALLER — which has the real disk inventory — designates the concrete fast device’s by-id into OSD_DB_BYID (hwprofile.env) subject to the durability floor, and the golden is a pure validating consumer. Absent/false => no key is emitted and behavior is byte-identical (all-NVMe/all-HDD/uniform unaffected).
storage.disk_size_gb (integer) – DiskSizeGB optionally targets a specific OS-disk size (e.g. 200 to pick the 200GB SSDs on a node that also has 400GB SSDs). 0 = no size filter; the matcher then prefers the smallest usable disks for the root vdev.
storage.disk_type (string)
storage.include_raid_vds (boolean)
storage.max_size_gb (integer)
storage.min_size_gb (integer)
storage.os_disk_count (integer)
storage.os_disks[] (string)
storage.topology (string)
- POST /provision/templates/{id}/match
Match revealed nodes against a stored template
Computes which revealed nodes fit the stored template; a read with no state change.
- Parameters:
id (integer) – Template ID
- Status Codes:
200 OK – OK
400 Bad Request – Invalid template ID
404 Not Found – Template not found
500 Internal Server Error – Database error
- Response JSON Object:
matching[].bmc_ip (string)
matching[].cpu_cores (integer)
matching[].disks[].device_path (string)
matching[].disks[].interface (string)
matching[].disks[].model (string)
matching[].disks[].name (string)
matching[].disks[].raid_vd (boolean)
matching[].disks[].rotational (integer)
matching[].disks[].serial (string)
matching[].disks[].size_gb (integer)
matching[].disks[].type (string)
matching[].disks[].wwn (string)
matching[].guest_nic_candidates[].detection_method (string)
matching[].guest_nic_candidates[].dhcp_server (string)
matching[].guest_nic_candidates[].interface (string)
matching[].guest_nic_candidates[].leased_ipv4 (string) – LeasedIPv4 is the address the CUSTOMER’s DHCP server offered THIS MAC during the reveal, in CIDR form, and DHCPServer is who offered it. Both empty on a static reveal — there is no lease when Karios stamped the address itself. This is the binding an operator needs to create a reservation BEFORE the node installs. On a network Karios does not own, the reservation has to exist before the node ever asks in earnest, and until now the reveal obtained a lease, used it to reach the control node, and threw the address away. EMPTY MEANS “NO SERVER ANSWERED ON THIS WIRE”, not “the address is 0”. The reveal appends nothing for a NIC that got no lease, so absence here is real evidence — it is how a wrong-VLAN NIC shows up on a leased pod, where the ARP subnet watch cannot run because there is no address to ARP for.
matching[].guest_nic_candidates[].mac (string)
matching[].guest_nic_candidates[].speed_mbps (integer)
matching[].guest_nic_candidates[].subnet (string)
matching[].guest_nic_candidates[].vlan (string) – VLAN/Subnet the reveal proved this NIC sits on for the traffic it is a candidate for, and how it was detected: lldp (switch dot1 TLV) | gwarp (gateway-ARP, mgmt/public) | peerarp (peer-ARP, gateway-less storage) | operator_assign (guest — never L3-probed).
matching[].has_mixed_sizes (boolean) – HasMixedSizes is true when the chosen root-vdev disks differ in size by more than 10% and the user accepted it with allow_mixed_sizes, so the UI can still show the wasted-capacity banner instead of the mismatch disappearing silently.
matching[].has_raid_vd (boolean) – HasRaidVD is true when any chosen OS or OSD disk is a hardware RAID virtual disk, so the UI can surface one consent banner for the user to acknowledge.
matching[].mgmt_nic (string) – Resolved management NIC: the reveal-proven NIC (by MAC) when known, else the best live physical NIC. The UI shows this read-only instead of asking for a NIC in the template.
matching[].mgmt_nic_candidates[].detection_method (string)
matching[].mgmt_nic_candidates[].dhcp_server (string)
matching[].mgmt_nic_candidates[].interface (string)
matching[].mgmt_nic_candidates[].leased_ipv4 (string) – LeasedIPv4 is the address the CUSTOMER’s DHCP server offered THIS MAC during the reveal, in CIDR form, and DHCPServer is who offered it. Both empty on a static reveal — there is no lease when Karios stamped the address itself. This is the binding an operator needs to create a reservation BEFORE the node installs. On a network Karios does not own, the reservation has to exist before the node ever asks in earnest, and until now the reveal obtained a lease, used it to reach the control node, and threw the address away. EMPTY MEANS “NO SERVER ANSWERED ON THIS WIRE”, not “the address is 0”. The reveal appends nothing for a NIC that got no lease, so absence here is real evidence — it is how a wrong-VLAN NIC shows up on a leased pod, where the ARP subnet watch cannot run because there is no address to ARP for.
matching[].mgmt_nic_candidates[].mac (string)
matching[].mgmt_nic_candidates[].speed_mbps (integer)
matching[].mgmt_nic_candidates[].subnet (string)
matching[].mgmt_nic_candidates[].vlan (string) – VLAN/Subnet the reveal proved this NIC sits on for the traffic it is a candidate for, and how it was detected: lldp (switch dot1 TLV) | gwarp (gateway-ARP, mgmt/public) | peerarp (peer-ARP, gateway-less storage) | operator_assign (guest — never L3-probed).
matching[].mgmt_nic_mac (string)
matching[].model (string)
matching[].nics[].link (string)
matching[].nics[].mac (string)
matching[].nics[].max_mtu (integer) – MaxMTU is the ceiling the NIC’s driver reports. sysfs does not publish it; the reveal reads it over rtnetlink, which is why it was missed. 0 is “not known”, never “cannot carry”.
matching[].nics[].name (string)
matching[].nics[].speed_mbps (integer)
matching[].nics[].subnet (string)
matching[].nics[].vlan (string) – VLAN/Subnet the reveal detected on this NIC (LLDP dot1 TLV primary, L3 probe fallback). Empty when the reveal predates per-NIC fabric detection or the NIC is on no known VLAN.
matching[].os_disks[] (string)
matching[].osd_disks[] (string)
matching[].public_nic (string)
matching[].public_nic_candidates[].detection_method (string)
matching[].public_nic_candidates[].dhcp_server (string)
matching[].public_nic_candidates[].interface (string)
matching[].public_nic_candidates[].leased_ipv4 (string) – LeasedIPv4 is the address the CUSTOMER’s DHCP server offered THIS MAC during the reveal, in CIDR form, and DHCPServer is who offered it. Both empty on a static reveal — there is no lease when Karios stamped the address itself. This is the binding an operator needs to create a reservation BEFORE the node installs. On a network Karios does not own, the reservation has to exist before the node ever asks in earnest, and until now the reveal obtained a lease, used it to reach the control node, and threw the address away. EMPTY MEANS “NO SERVER ANSWERED ON THIS WIRE”, not “the address is 0”. The reveal appends nothing for a NIC that got no lease, so absence here is real evidence — it is how a wrong-VLAN NIC shows up on a leased pod, where the ARP subnet watch cannot run because there is no address to ARP for.
matching[].public_nic_candidates[].mac (string)
matching[].public_nic_candidates[].speed_mbps (integer)
matching[].public_nic_candidates[].subnet (string)
matching[].public_nic_candidates[].vlan (string) – VLAN/Subnet the reveal proved this NIC sits on for the traffic it is a candidate for, and how it was detected: lldp (switch dot1 TLV) | gwarp (gateway-ARP, mgmt/public) | peerarp (peer-ARP, gateway-less storage) | operator_assign (guest — never L3-probed).
matching[].public_nic_mac (string)
matching[].ram_gb (integer)
matching[].storage_nic (string) – Resolved storage/public NIC: auto-selected when the reveal found exactly one candidate, empty when 0 or >1 so the user picks (the UI shows a selector over the candidates). Guest has no auto NIC — it is user-assigned, so only its candidate list is carried.
matching[].storage_nic_candidates[].detection_method (string)
matching[].storage_nic_candidates[].dhcp_server (string)
matching[].storage_nic_candidates[].interface (string)
matching[].storage_nic_candidates[].leased_ipv4 (string) – LeasedIPv4 is the address the CUSTOMER’s DHCP server offered THIS MAC during the reveal, in CIDR form, and DHCPServer is who offered it. Both empty on a static reveal — there is no lease when Karios stamped the address itself. This is the binding an operator needs to create a reservation BEFORE the node installs. On a network Karios does not own, the reservation has to exist before the node ever asks in earnest, and until now the reveal obtained a lease, used it to reach the control node, and threw the address away. EMPTY MEANS “NO SERVER ANSWERED ON THIS WIRE”, not “the address is 0”. The reveal appends nothing for a NIC that got no lease, so absence here is real evidence — it is how a wrong-VLAN NIC shows up on a leased pod, where the ARP subnet watch cannot run because there is no address to ARP for.
matching[].storage_nic_candidates[].mac (string)
matching[].storage_nic_candidates[].speed_mbps (integer)
matching[].storage_nic_candidates[].subnet (string)
matching[].storage_nic_candidates[].vlan (string) – VLAN/Subnet the reveal proved this NIC sits on for the traffic it is a candidate for, and how it was detected: lldp (switch dot1 TLV) | gwarp (gateway-ARP, mgmt/public) | peerarp (peer-ARP, gateway-less storage) | operator_assign (guest — never L3-probed).
matching[].storage_nic_mac (string)
matching[].vendor (string)
matching[].warnings[] (string)
matching_count (integer)
rejected[].bmc_ip (string)
rejected[].cpu_cores (integer)
rejected[].disks[].device_path (string)
rejected[].disks[].interface (string)
rejected[].disks[].model (string)
rejected[].disks[].name (string)
rejected[].disks[].raid_vd (boolean)
rejected[].disks[].rotational (integer)
rejected[].disks[].serial (string)
rejected[].disks[].size_gb (integer)
rejected[].disks[].type (string)
rejected[].disks[].wwn (string)
rejected[].model (string)
rejected[].nics[].link (string)
rejected[].nics[].mac (string)
rejected[].nics[].max_mtu (integer) – MaxMTU is the ceiling the NIC’s driver reports. sysfs does not publish it; the reveal reads it over rtnetlink, which is why it was missed. 0 is “not known”, never “cannot carry”.
rejected[].nics[].name (string)
rejected[].nics[].speed_mbps (integer)
rejected[].nics[].subnet (string)
rejected[].nics[].vlan (string) – VLAN/Subnet the reveal detected on this NIC (LLDP dot1 TLV primary, L3 probe fallback). Empty when the reveal predates per-NIC fabric detection or the NIC is on no known VLAN.
rejected[].ram_gb (integer)
rejected[].reason (string)
rejected[].vendor (string)
revealed_total (integer)