network.rst

.. _configuration-network:

=====================
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``.

.. _configuration-network-global:

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, 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.

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:

.. code-block:: yaml
   :caption: ``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``:

.. code-block:: yaml
   :caption: ``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``:

.. code-block:: yaml
   :caption: ``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``:

.. code-block:: yaml
   :caption: ``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``:

.. code-block:: yaml
   :caption: ``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:

.. code-block:: yaml
   :caption: ``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``:

.. code-block:: yaml
   :caption: ``networks.yml``

   example_vlan: 123

.. _configuration-network-ip-allocation:

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