============= Configuration ============= This section covers configuration of Kayobe. As an Ansible-based project, Kayobe is for the most part configured using YAML files. Configuration Location ====================== Kayobe configuration is by default located in ``/etc/kayobe`` on the Ansible control host. This location can be overridden to a different location to avoid touching the system configuration directory by setting the environment variable ``KAYOBE_CONFIG_PATH``. Similarly, kolla configuration on the Ansible control host will by default be located in ``/etc/kolla`` and can be overridden via ``KOLLA_CONFIG_PATH``. Configuration Directory Layout ============================== The Kayobe configuration directory contains Ansible ``extra-vars`` files and the Ansible inventory. An example of the directory structure is as follows:: extra-vars1.yml extra-vars2.yml inventory/ group_vars/ group1-vars group2-vars groups host_vars/ host1-vars host2-vars hosts Configuration Patterns ====================== Ansible's variable precedence rules are `fairly well documented `_ and provide a mechanism we can use for providing site localisation and customisation of OpenStack in combination with some reasonable default values. For global configuration options, Kayobe typically uses the following patterns: - Playbook group variables for the *all* group in ``/ansible/group_vars/all/*`` set **global defaults**. These files should not be modified. - Playbook group variables for other groups in ``/ansible/group_vars//*`` set **defaults for some subsets of hosts**. These files should not be modified. - Extra-vars files in ``${KAYOBE_CONFIG_PATH}/*.yml`` set **custom values for global variables** and should be used to apply global site localisation and customisation. By default these variables are commented out. Additionally, variables can be set on a per-host basis using inventory host variables files in ``${KAYOBE_CONFIG_PATH}/inventory/host_vars/*``. It should be noted that variables set in extra-vars files take precedence over per-host variables. Configuring Kayobe ================== 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} Once in place, each of the YAML and inventory files should be manually inspected and configured as required. Inventory ---------- The inventory should contain the following hosts: Control host This should be localhost and should be a member of the ``config-mgmt`` group. Seed hypervisor If provisioning a seed VM, a host should exist for the hypervisor that will run the VM, and should be a member of the ``seed-hypervisor`` group. Seed The seed host, whether provisioned as a VM by Kayobe or externally managed, should exist in the ``seed`` group. Cloud hosts and bare metal compute hosts are not required to exist in the inventory. Site Localisation and Customisation ----------------------------------- Site localisation and customisation is applied using Ansible extra-vars files in ``${KAYOBE_CONFIG_PATH}/*.yml``. Encryption of Secrets --------------------- Kayobe supports the use of `Ansible vault `_ to encrypt sensitive information in its configuration. The ``ansible-vault`` tool should be used to manage individual files for which encryption is required. Any of the 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.