Network Configuration¶

Kayobe provides a flexible mechanism for configuring the networks in a system. Kayobe networks are assigned a name which is used as a prefix for variables that define the network’s attributes. For example, to configure the cidr attribute of a network named arpanet, we would use a variable named arpanet_cidr.

Global Network Configuration¶

Global network configuration is stored in ${KAYOBE_CONFIG_PATH}/networks.yml. The following attributes are supported:

cidr

CIDR representation (<IP>/<prefix length>) of the network’s IP subnet.

allocation_pool_start

IP address of the start of Kayobe’s allocation pool range.

allocation_pool_end

IP address of the end of Kayobe’s allocation pool range.

inspection_allocation_pool_start

IP address of the start of ironic inspector’s allocation pool range.

inspection_allocation_pool_end

IP address of the end of ironic inspector’s allocation pool range.

neutron_allocation_pool_start

IP address of the start of neutron’s allocation pool range.

neutron_allocation_pool_end

IP address of the end of neutron’s allocation pool range.

gateway

IP address of the network’s default gateway.

inspection_gateway

IP address of the gateway for the hardware introspection network.

neutron_gateway

IP address of the gateway for a neutron subnet based on this network.

vlan

VLAN ID.

mtu

Maximum Transmission Unit (MTU).

vip_address

Note

Use of the vip_address attribute is deprecated. Instead use kolla_internal_vip_address and kolla_external_vip_address.

Virtual IP address (VIP) used by API services on this network.

fqdn

Note

Use of the fqdn attribute is deprecated. Instead use kolla_internal_fqdn and kolla_external_fqdn.

Fully Qualified Domain Name (FQDN) used by API services on this network.

routes

Note

options is not currently supported on Ubuntu.

List of static IP routes. Each item should be a dict containing the item cidr, and optionally gateway, table and options. cidr is the CIDR representation of the route’s destination. gateway is the IP address of the next hop. table is the name or ID of a routing table to which the route will be added. options is a list of option strings to add to the route.

rules

List of IP routing rules.

On CentOS or Rocky, each item should be a string describing an iproute2 IP routing rule.

On Ubuntu, each item should be a dict containing optional items from, to, priority and table. from is the source address prefix to match with optional prefix. to is the destination address prefix to match with optional prefix. priority is the priority of the rule. table is the routing table ID.

physical_network

Name of the physical network on which this network exists. This aligns with the physical network concept in neutron.

libvirt_network_name

A name to give to a Libvirt network representing this network on the seed hypervisor.

no_ip

Whether to allocate an IP address for this network. If set to true, an IP address will not be allocated.

Configuring an IP Subnet¶

An IP subnet may be configured by setting the cidr attribute for a network to the CIDR representation of the subnet.

To configure a network called example with the 10.0.0.0/24 IP subnet:

networks.yml¶

example_cidr: 10.0.0.0/24

Configuring an IP Gateway¶

An IP gateway may be configured by setting the gateway attribute for a network to the IP address of the gateway.

To configure a network called example with a gateway at 10.0.0.1:

networks.yml¶

example_gateway: 10.0.0.1

This gateway will be configured on all hosts to which the network is mapped. Note that configuring multiple IP gateways on a single host will lead to unpredictable results.

Configuring an API Virtual IP Address¶

A virtual IP (VIP) address may be configured for use by Kolla Ansible on the internal and external networks, on which the API services will be exposed. The variable will be passed through to the kolla_internal_vip_address or kolla_external_vip_address Kolla Ansible variable.

To configure a network called example with a VIP at 10.0.0.2:

networks.yml¶

example_vip_address: 10.0.0.2

Configuring an API Fully Qualified Domain Name¶

A Fully Qualified Domain Name (FQDN) may be configured for use by Kolla Ansible on the internal and external networks, on which the API services will be exposed. The variable will be passed through to the kolla_internal_fqdn or kolla_external_fqdn Kolla Ansible variable.

To configure a network called example with an FQDN at api.example.com:

networks.yml¶

example_fqdn: api.example.com

Configuring Static IP Routes¶

Static IP routes may be configured by setting the routes attribute for a network to a list of routes.

To configure a network called example with a single IP route to the 10.1.0.0/24 subnet via 10.0.0.1:

networks.yml¶

example_routes:
  - cidr: 10.1.0.0/24
    gateway: 10.0.0.1

These routes will be configured on all hosts to which the network is mapped.

If necessary, custom options may be added to the route:

networks.yml¶

example_routes:
  - cidr: 10.1.0.0/24
    gateway: 10.0.0.1
    options:
      - onlink
      - metric 400

Note that custom options are not currently supported on Ubuntu.

Configuring a VLAN¶

A VLAN network may be configured by setting the vlan attribute for a network to the ID of the VLAN.

To configure a network called example with VLAN ID 123:

networks.yml¶

example_vlan: 123

IP Address Allocation¶

IP addresses are allocated automatically by Kayobe from the allocation pool defined by allocation_pool_start and allocation_pool_end. If these variables are undefined, the entire network is used, except for network and broadcast addresses. IP addresses are only allocated if the network cidr is set and DHCP is not used (see bootproto in Per-host Network Configuration). The allocated addresses are stored in ${KAYOBE_CONFIG_PATH}/network-allocation.yml using the global per-network attribute ips which maps Ansible inventory hostnames to allocated IPs.

If static IP address allocation is required, the IP allocation file network-allocation.yml may be manually populated with the required addresses.

Configuring Dynamic IP Address Allocation¶

To configure a network called example with the 10.0.0.0/24 IP subnet and an allocation pool spanning from 10.0.0.4 to 10.0.0.254:

networks.yml¶

example_cidr: 10.0.0.0/24
example_allocation_pool_start: 10.0.0.4
example_allocation_pool_end: 10.0.0.254

Note

This pool should not overlap with an inspection or neutron allocation pool on the same network.

Configuring Static IP Address Allocation¶

To configure a network called example with statically allocated IP addresses for hosts host1 and host2:

network-allocation.yml¶

example_ips:
  host1: 10.0.0.1
  host2: 10.0.0.2

Advanced: Policy-Based Routing¶

Policy-based routing can be useful in complex networking environments, particularly where asymmetric routes exist, and strict reverse path filtering is enabled.

Configuring IP Routing Tables¶

Custom IP routing tables may be configured by setting the global variable network_route_tables in ${KAYOBE_CONFIG_PATH}/networks.yml to a list of route tables. These route tables will be added to /etc/iproute2/rt_tables.

To configure a routing table called exampleroutetable with ID 1:

networks.yml¶

network_route_tables:
  - name: exampleroutetable
    id: 1

To configure route tables on specific hosts, use a host or group variables file.

Configuring IP Routing Policy Rules¶

IP routing policy rules may be configured by setting the rules attribute for a network to a list of rules. Two formats are supported for defining rules: string format and dict format. String format rules are only supported on CentOS Stream and Rocky Linux systems.

Dict format rules¶

The dict format of a rule is a dictionary with optional items from, to, priority, and table. table should be the name of a route table defined in network_route_tables.

To configure a network called example with an IP routing policy rule to handle traffic from the subnet 10.1.0.0/24 using the routing table exampleroutetable:

networks.yml¶

example_rules:
  - from: 10.1.0.0/24
    table: exampleroutetable

These rules will be configured on all hosts to which the network is mapped.

String format rules (CentOS Stream/Rocky Linux only)¶

The string format of a rule is the string which would be appended to ip rule <add|del> to create or delete the rule. Note that when using NetworkManager (the default since Zed and in Yoga when using Rocky Linux 9) the table must be specified by ID.

To configure a network called example with an IP routing policy rule to handle traffic from the subnet 10.1.0.0/24 using the routing table with ID 1:

networks.yml¶

example_rules:
  - from 10.1.0.0/24 table 1

These rules will be configured on all hosts to which the network is mapped.

Configuring IP Routes on Specific Tables¶

A route may be added to a specific routing table by adding the name or ID of the table to a table attribute of the route:

To configure a network called example with a default route and a ‘connected’ (local subnet) route to the subnet 10.1.0.0/24 on the table exampleroutetable:

networks.yml¶

example_routes:
  - cidr: 0.0.0.0/0
    gateway: 10.1.0.1
    table: exampleroutetable
  - cidr: 10.1.0.0/24
    table: exampleroutetable

Per-host Network Configuration¶

Some network attributes are specific to a host’s role in the system, and these are stored in ${KAYOBE_CONFIG_PATH}/inventory/group_vars/<group>/network-interfaces. The following attributes are supported:

interface: The name of the network interface attached to the network.
parent: The name of the parent interface, when configuring a VLAN interface using systemd-networkd syntax.
bootproto: Boot protocol for the interface. Valid values are static and dhcp. The default is static. When set to dhcp, an external DHCP server must be provided.
defroute: Whether to set the interface as the default route. This attribute can be used to disable configuration of the default gateway by a specific interface. This is particularly useful to ignore a gateway address provided via DHCP. Should be set to a boolean value. The default is unset. This attribute is only supported on distributions of the Red Hat family.
bridge_ports: For bridge interfaces, a list of names of network interfaces to add to the bridge.
bridge_stp: Note

For Rocky Linux 9, the bridge_stp attribute is set to false to preserve backwards compatibility with network scripts. This is because the Network Manager sets STP to true by default on bridges.

Enable or disable the Spanning Tree Protocol (STP) on this bridge. Should be set to a boolean value. The default is not set on Ubuntu systems.
bond_mode: For bond interfaces, the bond’s mode, e.g. 802.3ad.
bond_ad_select: For bond interfaces, the 802.3ad aggregation selection logic to use. Valid values are stable (default selection logic if not configured), bandwidth or count.
bond_slaves: For bond interfaces, a list of names of network interfaces to act as slaves for the bond.
bond_miimon: For bond interfaces, the time in milliseconds between MII link monitoring.
bond_updelay: For bond interfaces, the time in milliseconds to wait before declaring an interface up (should be multiple of bond_miimon).
bond_downdelay: For bond interfaces, the time in milliseconds to wait before declaring an interface down (should be multiple of bond_miimon).
bond_xmit_hash_policy: For bond interfaces, the xmit_hash_policy to use for the bond.
bond_lacp_rate: For bond interfaces, the lacp_rate to use for the bond.
ethtool_opts: Note

ethtool_opts is not currently supported on Ubuntu.

Physical network interface options to apply with ethtool. When used on bond and bridge interfaces, settings apply to underlying interfaces. This should be a string of arguments passed to the ethtool utility, for example "-G ${DEVICE} rx 8192 tx 8192".
zone: Note

zone is not currently supported on Ubuntu.

The name of firewalld zone to be attached to network interface.

IP Addresses¶

An interface will be assigned an IP address if the associated network has a cidr attribute. The IP address will be assigned from the range defined by the allocation_pool_start and allocation_pool_end attributes, if one has not been statically assigned in network-allocation.yml.

Configuring Ethernet Interfaces¶

An Ethernet interface may be configured by setting the interface attribute for a network to the name of the Ethernet interface.

To configure a network called example with an Ethernet interface on eth0: