network_spec.yml¶

This file defines the admin network, the optional InfiniBand network, and any additional DHCP subnets. Orchestrator and Discovery stage independent copies of this file in their respective project input directories.

IPv4-only input contract

The current schema and validator accept IPv4 network values only. The optional ib_network object represents one IPv4 subnet; it does not accept an IPv6 prefix or select dual-stack or IPv6-only IPoIB behavior.

IPv6 InfiniBand is under design review. See the IPv6 InfiniBand engineering draft for the proposed scope and the unresolved input-contract decisions. Do not use the proposed behavior as a current configuration procedure.

Location¶

$OMNIA_DATA_PATH/orchestrator/input/$OMNIA_PROJECT_NAME/network_spec.yml
$OMNIA_DATA_PATH/discovery/input/$OMNIA_PROJECT_NAME/network_spec.yml

The Orchestrator data root is $OMNIA_DATA_PATH/orchestrator. Discovery derives its input directory from $OMNIA_DATA_PATH/discovery. Configure the Discovery copy for node discovery and the Orchestrator copy for provisioning.

Discovery currently reads only admin_network.subnet and ib_network.subnet. It uses their first two octets with the last two octets of each server's BMC address to derive ADMIN_IP and IB_IP. The Discovery validate tag does not validate this file. Orchestrator consumes and validates the remaining network fields from its own copy.

Top-level structure¶

network_spec.yml contains a single top-level key, Networks, which is a YAML list of network definitions.

Define exactly one admin_network entry and no more than one ib_network entry. Although the schema represents these definitions as list items, the runtime combines them into one network mapping; a later duplicate network type would replace the earlier definition.

File: $OMNIA_DATA_PATH/orchestrator/input/$OMNIA_PROJECT_NAME/network_spec.yml

Networks:
  - admin_network:
      oim_nic_name: "eno1"
      subnet: "172.16.107.0"
      netmask_bits: "24"
      primary_oim_admin_ip: "172.16.107.254"
      primary_oim_bmc_ip: ""
      router: "172.16.107.254"
      dynamic_range: "172.16.107.201-172.16.107.250"
      dns: []
      ntp_servers: []
      additional_subnets: []

Omit the ib_network list item when InfiniBand is not used. When it is present, both subnet and netmask_bits must contain valid values; an empty ib_network object does not satisfy the schema.

Every subnet, including ib_network.subnet, must be its canonical IPv4 network address. Each router and DHCP range must belong to its declared admin subnet, and ranges must be ordered. Primary and additional admin subnets must be pairwise non-overlapping and must not overlap the optional InfiniBand subnet. Configured DHCP ranges must also be pairwise non-overlapping. The OIM admin address must be inside its primary admin subnet and outside its DHCP range. A non-empty OIM BMC address must differ from every OIM admin address and remain outside every configured DHCP range.

Admin Network Configuration Parameters¶

Parameter	Details
admin_network dict / required	Admin network configuration. Essential for PXE boot and host communication.
oim_nic_name string / required	The name of the interface on the OIM server associated with the admin network. Example value: `eno1`
subnet string / required	The canonical IPv4 network address for the admin network. It must not overlap another primary or additional admin subnet, or the optional InfiniBand subnet. Example value: `172.16.107.0`
netmask_bits string / required	The number of bits in the subnet mask. Example value: `24`
primary_oim_admin_ip string / required	The OIM admin IPv4 address. It must belong to the primary admin subnet and remain outside that subnet's dynamic range. Example value: `172.16.107.254`
primary_oim_bmc_ip string / required	The OIM BMC/iDRAC IP address. Specify an IPv4 address to include the OIM in the generated BMC group data consumed by iDRAC telemetry. Set the value to an empty string to exclude the OIM. A non-empty value must differ from every OIM admin address and remain outside every configured DHCP range. Example value: `""`
router string / required	In connected deployments, the router field should typically be set to the external rack gateway, such as a SONiC switch, which provides connectivity beyond the rack network. In air-gapped deployments, the router field can be set to the OIM’s IP address if the OIM is acting as the rack gateway. If another dedicated router or gateway is available, its IP address should be specified instead. The configured value must belong to this subnet and is advertised to nodes via DHCP as their default gateway. Example value: `172.16.107.254`
dynamic_range string / required	An ordered start-end IPv4 range contained by this subnet. It must not contain the OIM admin or BMC address and must not overlap another configured DHCP range. The current precheck does not cross-check the pool against PXE mapping addresses; reserve static node addresses outside the pool. Example value: `172.16.107.201-172.16.107.250`
dns list / elements=string	The list of external DNS server IP addresses for the admin network. Example value: `[]`
ntp_servers list / elements=dict	The list of NTP servers for the admin network. Each NTP server entry should include address (IP address or hostname) and type (server or pool). Example value: `[]`
address string / required	IP address or hostname of the NTP server.
type string / required	NTP source type. Accepted values: server, pool.

Infiniband Network Configuration Parameters (optional)¶

Parameter	Details
ib_network dict	InfiniBand network configuration.
subnet string / required	The canonical IPv4 network address of the IB network. It must not overlap a primary or additional admin subnet. Example value: `192.168.0.0`
netmask_bits string / required	The number of bits in the InfiniBand subnet mask. This value is applied independently to node InfiniBand interfaces and may differ from the primary admin_network netmask_bits. Example value: `24`
dns list / elements=string	External DNS server IP addresses for the InfiniBand network. Example value: `[]`

Additional Subnets Configuration Parameters (optional)¶

Parameter	Details
additional_subnets list / elements=dict	Optional field for multi-RAC/multi-subnet PXE deployments. Each entry defines a separate subnet that the CoreDHCP server will manage via DHCP relay (giaddr-based routing). Leave empty array (`[]`) for single-subnet deployments. Default value: `[]` For more information about configuring Multi-Subnet DHCP, see Multi-Subnet DHCP.
subnet string / required	The network address of the additional subnet (e.g. "10.40.1.0").
netmask_bits string / required	The CIDR prefix length (e.g. "24").
router string / required	The gateway/router IP for this subnet (used as DHCP option 3).
dynamic_range string / required	The DHCP IP pool range in "start_ip-end_ip" format. It must fall within this subnet, must not overlap another configured DHCP range, and must not contain a static ADMIN_IP in the PXE mapping file. The current precheck does not cross-check the pool against PXE mapping addresses; reserve those addresses outside the pool.

Usage example¶

File: $OMNIA_DATA_PATH/orchestrator/input/$OMNIA_PROJECT_NAME/network_spec.yml

---
Networks:
  - admin_network:
      oim_nic_name: "eno1"
      subnet: "172.16.107.0"
      netmask_bits: "24"
      primary_oim_admin_ip: "172.16.107.254"
      primary_oim_bmc_ip: ""
      router: "172.16.107.254"
      dynamic_range: "172.16.107.201-172.16.107.250"
      dns: []
      ntp_servers: []
      additional_subnets:
        - subnet: "10.40.1.0"
          netmask_bits: "24"
          router: "10.40.1.1"
          dynamic_range: "10.40.1.100-10.40.1.200"
        - subnet: "10.40.3.0"
          netmask_bits: "24"
          router: "10.40.3.1"
          dynamic_range: "10.40.3.100-10.40.3.200"

  - ib_network:
      subnet: "192.168.0.0"
      netmask_bits: "24"
      dns: []

Note

The router field is required and specifies the gateway IP address advertised to nodes through DHCP option 3 as their default gateway.
In connected deployments, set router to the external rack gateway (such as a SONiC switch) which provides connectivity beyond the rack network.
In air-gapped deployments, set router to the OIM's IP address if the OIM is acting as the rack gateway. If a dedicated router or gateway is available, specify its IP address instead.
Sample value: 172.16.107.254. The schema requires router; the runtime does not supply this value when it is omitted.
Every primary and additional dynamic_range must be contained within its subnet, must not overlap another configured DHCP range, and must not contain the OIM admin or BMC address. Orchestrator does not currently cross-check these DHCP pools against static ADMIN_IP values in the PXE mapping file, so reserve those addresses outside the pools.
When ib_network is configured, its subnet must not overlap an admin subnet. Its netmask_bits value is applied independently to node InfiniBand interfaces and may differ from the admin-network prefix.

Info

Network Topologies -- How topologies affect NIC and VLAN assignments.
Nics -- Supported NIC models.