From d82e9bc9ba9016fc113577e677747e1910f21eac Mon Sep 17 00:00:00 2001 From: Mark Goddard Date: Wed, 24 May 2017 10:47:43 +0100 Subject: [PATCH] Add documentation of network configuration --- doc/source/configuration.rst | 215 ++++++++++++++++++++++++++++++++++- 1 file changed, 213 insertions(+), 2 deletions(-) diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst index c3a762695..0f53825c5 100644 --- a/doc/source/configuration.rst +++ b/doc/source/configuration.rst @@ -60,8 +60,14 @@ variables. Configuring Kayobe ================== -From a checkout of the Kayobe repository, the baseline Kayobe configuration -should be copied to the Kayobe configuration path:: +The `kayobe-config `_ git repository +contains a Kayobe configuration directory structure and unmodified +configuration files. This repository can be used as a mechanism for version +controlling Kayobe configuration. As Kayobe is updated, the configuration +should be merged to incorporate any upstream changes with local modifications. + +Alternatively, the baseline Kayobe configuration may be copied from a checkout +of the Kayobe repository to the Kayobe configuration path:: $ cp -r etc/ ${KAYOBE_CONFIG_PATH:-/etc/kayobe} @@ -103,3 +109,208 @@ configuration files may be encrypted. Since encryption can make working with Kayobe difficult, it is recommended to follow `best practice `_, adding a layer of indirection and using encryption only where necessary. + +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 is stored in +``${KAYOBE_CONFIG_PATH}/networks.yml``. The following attributes are +supported: + +``cidr`` + CIDR representation (/) 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. +``vlan`` + VLAN ID. +``mtu`` + Maximum Transmission Unit (MTU). + +IP addresses are allocated automatically by Kayobe from the +allocation pool +defined by ``allocation_pool_start`` and ``allocation_pool_end``. 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. + +Some network attributes are specific to a host's role in the system, and +these are stored in +``${KAYOBE_CONFIG_PATH}/inventory/group_vars//network-interfaces``. +The following attributes are supported: + +``interface`` + The name of the network interface attached to the network. +``bridge_ports`` + For bridge interfaces, a list of names of network interfaces to add to the + bridge. + +In order to provide flexibility in the system's network topology, Kayobe maps +the named networks to logical network roles. A single named network may +perform multiple roles, or even none at all. The available roles are: + +``provision_oc_net_name`` + Name of the network used by the seed to provision the bare metal overcloud + hosts. +``provision_wl_net_name`` + Name of the network used by the overcloud hosts to provision the bare metal + workload hosts. +``internal_net_name`` + Name of the network used to expose the internal OpenStack API endpoints. +``external_net_name`` + Name of the network used to expose the external OpenStack API endpoints and + to provide external network access via Neutron. +``storage_net_name`` + Name of the network used to carry storage data traffic. +``storage_mgmt_net_name`` + Name of the network used to carry storage management traffic. +``inspection_net_name`` + Name of the network used to perform hardware introspection on the bare + metal workload hosts. + +These roles are configured in ``${KAYOBE_CONFIG_PATH}/networks.yml``. + +Networks are mapped to hosts using the variable ``network_interfaces``. +Kayobe's playbook group variables define some sensible defaults for this +variable for hosts in the ``seed`` and ``controllers`` groups based on the +logical network roles. These defaults can be extended by setting the variables +``seed_extra_network_interfaces`` and ``controller_extra_network_interfaces`` +in ``${KAYOBE_CONFIG_PATH}/seed.yml`` and +``${KAYOBE_CONFIG_PATH}/controllers.yml`` respectively. + +Example +^^^^^^^ + +In our example cloud we have three networks: ``management``, ``cloud`` and +``external``: + +.. parsed-literal:: + + +------------+ +----------------+ +----------------+ + | | | +-+ | +-+ + | | | | +-+ | Bare metal | +-+ + | Seed | | Cloud hosts | | | | compute hosts | | | + | | | | | | | | | | + | | | | | | | | | | + +-----+------+ +----------------+ | | +----------------+ | | + | +-----------------+ | +-----------------+ | + | +-----------------+ +-----------------+ + | | | | | + | | | | | + | | | | | + | | | | | + management +--------+------------------------+----------------------------------------------+ + | | | + cloud +------------------------------------+------------------------------+------------+ + | + external +---------------------------------------+----------------------------------------+ + +The ``management`` network is used to access the servers' BMCs and by the seed +to provision the cloud hosts. The ``cloud`` network carries all internal +control plane and storage traffic, and is used by the control plane to +provision the bare metal compute hosts. Finally, the ``external`` network +links the cloud to the outside world. + +We could describe such a network as follows: + +.. code-block:: yaml + :name: networks.yml + :caption: ``networks.yml`` + + --- + # Network role mappings. + provision_oc_net_name: management + provision_wl_net_name: cloud + internal_net_name: cloud + external_net_name: external + storage_net_name: cloud + storage_mgmt_net_name: cloud + inspection_net_name: cloud + + # management network definition. + management_cidr: 10.0.0.0/24 + management_allocation_pool_start: 10.0.0.1 + management_allocation_pool_end: 10.0.0.127 + management_inspection_allocation_pool_start: 10.0.0.128 + management_inspection_allocation_pool_end: 10.0.0.254 + + # cloud network definition. + cloud_cidr: 10.0.1.0/23 + cloud_allocation_pool_start: 10.0.1.1 + cloud_allocation_pool_end: 10.0.1.127 + cloud_inspection_allocation_pool_start: 10.0.1.128 + cloud_inspection_allocation_pool_end: 10.0.1.255 + cloud_neutron_allocation_pool_start: 10.0.2.0 + cloud_neutron_allocation_pool_end: 10.0.2.254 + + # external network definition. + external_cidr: 10.0.3.0/24 + external_allocation_pool_start: 10.0.3.1 + external_allocation_pool_end: 10.0.3.127 + external_neutron_allocation_pool_start: 10.0.3.128 + external_neutron_allocation_pool_end: 10.0.3.254 + +We can map these networks to network interfaces on the seed and controller hosts: + +.. code-block:: yaml + :name: inventory/group_vars/seed/network-interfaces + :caption: ``inventory/group_vars/seed/network-interfaces`` + + --- + management_interface: eth0 + +.. code-block:: yaml + :name: inventory/group_vars/controllers/network-interfaces + :caption: ``inventory/group_vars/controllers/network-interfaces`` + + --- + management_interface: eth0 + cloud_interface: breth1 + cloud_bridge_ports: + - eth1 + external_interface: eth2 + +We have defined a bridge for the cloud network on the controllers as this will +allow it to be plugged into a neutron Open vSwitch bridge. + +Kayobe will allocate IP addresses for the hosts that it manages: + +.. code-block:: yaml + :name: network-allocation.yml + :caption: ``network-allocation.yml`` + + --- + management_ips: + seed: 10.0.0.1 + control0: 10.0.0.2 + control1: 10.0.0.3 + control2: 10.0.0.4 + cloud_ips: + control0: 10.0.1.1 + control1: 10.0.1.2 + control2: 10.0.1.3 + external_ips: + control0: 10.0.3.1 + control1: 10.0.3.2 + control2: 10.0.3.3 + +Note that although this file does not need to be created manually, doing so +allows for a predictable IP address mapping which may be desirable in some +cases.