===========================
Kolla-ansible Configuration
===========================

Kayobe relies heavily on kolla-ansible for deployment of the OpenStack control
plane. Kolla-ansible is installed locally on the Ansible control host (the host
from which kayobe commands are executed), and kolla-ansible commands are
executed from there.

Local Environment
=================

Environment variables are used to configure the environment in which
kolla-ansible is installed and executed.

.. table:: Kolla-ansible environment variables

   ====================== ================================================== ============================
   Variable               Purpose                                            Default
   ====================== ================================================== ============================
   ``$KOLLA_CONFIG_PATH`` Path on the Ansible control host in which          ``/etc/kolla``
                          the kolla-ansible configuration will be generated.
                          These files should not be manually edited.
   ``$KOLLA_SOURCE_PATH`` Path on the Ansible control host in which          ``$PWD/src/kolla-ansible``
                          the kolla-ansible source code will be cloned.
   ``$KOLLA_VENV_PATH``   Path on the Ansible control host in which          ``$PWD/venvs/kolla-ansible``
                          the kolla-ansible virtualenv will be created.
   ====================== ================================================== ============================

Extra Python packages can be installed inside the kolla-ansible virtualenv,
such as when required by Ansible plugins, using the
``kolla_ansible_venv_extra_requirements`` list variable in
``$KAYOBE_CONFIG_PATH/kolla.yml``. For example, to use the `hashi_vault Ansible
lookup plugin
<https://docs.ansible.com/ansible/devel/plugins/lookup/hashi_vault.html>`_, its
``hvac`` dependency can be installed using:

.. code-block:: yaml
   :caption: ``$KAYOBE_CONFIG_PATH/kolla.yml``

   ---
   # Extra requirements to install inside the kolla-ansible virtualenv.
   kolla_ansible_venv_extra_requirements:
     - "hvac"

.. _configuration-kolla-ansible-venv:

Remote Execution Environment
============================

By default, ansible executes modules remotely using the system python
interpreter, even if the ansible control process is executed from within a
virtual environment (unless the ``local`` connection plugin is used).
This is not ideal if there are python dependencies that must be installed
with isolation from the system python packages. Ansible can be configured to
use a virtualenv by setting the host variable ``ansible_python_interpreter``
to a path to a python interpreter in an existing virtual environment.

If the variable ``kolla_ansible_target_venv`` is set, kolla-ansible will be
configured to create and use a virtual environment on the remote hosts.
This variable is by default set to ``{{ virtualenv_path }}/kolla-ansible``.
The previous behaviour of installing python dependencies directly to the host
can be used by setting ``kolla_ansible_target_venv`` to ``None``.

Control Plane Services
======================

Kolla-ansible provides a flexible mechanism for configuring the services that
it deploys. Kayobe adds some commonly required configuration options to the
defaults provided by kolla-ansible, but also allows for the free-form
configuration supported by kolla-ansible. The `kolla-ansible documentation
<https://docs.openstack.org/kolla-ansible/latest/>`_ should be used as a
reference.

Global Variables
----------------

Kolla-ansible uses a single file for global variables, ``globals.yml``. Kayobe
provides configuration variables for all required variables and many of the
most commonly used the variables in this file. Some of these are in
``$KAYOBE_CONFIG_PATH/kolla.yml``, and others are determined from other sources
such as the networking configuration in ``$KAYOBE_CONFIG_PATH/networks.yml``.

Configuring Custom Global Variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Additional global configuration may be provided by creating
``$KAYOBE_CONFIG_PATH/kolla/globals.yml``. Variables in this file will be
templated using Jinja2, and merged with the Kayobe ``globals.yml``
configuration.

.. code-block:: yaml
   :caption: ``$KAYOBE_CONFIG_PATH/kolla/globals.yml``

   ---
   # Use a custom tag for the nova-api container image.
   nova_api_tag: v1.2.3

Passwords
---------

Kolla-ansible auto-generates passwords to a file, ``passwords.yml``. Kayobe
handles the orchestration of this, as well as encryption of the file using an
ansible vault password specified in the ``KAYOBE_VAULT_PASSWORD`` environment
variable, if present. The file is generated to
``$KAYOBE_CONFIG_PATH/kolla/passwords.yml``, and should be stored along with
other kayobe configuration files. This file should not be manually modified.

Configuring Custom Passwords
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In order to write additional passwords to ``passwords.yml``, set the kayobe
variable ``kolla_ansible_custom_passwords`` in
``$KAYOBE_CONFIG_PATH/kolla.yml``.

.. code-block:: yaml
   :caption: ``$KAYOBE_CONFIG_PATH/kolla.yml``

   ---
   # Dictionary containing custom passwords to add or override in the Kolla
   # passwords file.
   kolla_ansible_custom_passwords: >
     {{ kolla_ansible_default_custom_passwords |
        combine({'my_custom_password': 'correcthorsebatterystaple'}) }}

Service Configuration
---------------------

Kolla-ansible's flexible configuration is described in the `kolla-ansible
service configuration documentation
<https://docs.openstack.org/kolla-ansible/latest/admin/advanced-configuration.html#openstack-service-configuration-in-kolla>`_.
We won't duplicate that here, but essentially it involves creating files under
a directory which for users of kayobe will be ``$KOLLA_CONFIG_PATH/config``. In
kayobe, files in this directory are auto-generated and managed by kayobe.
Instead, users should create files under ``$KAYOBE_CONFIG_PATH/kolla/config``
with the same directory structure.  These files will be templated using Jinja2,
merged with kayobe's own configuration, and written out to
``$KOLLA_CONFIG_PATH/config``.

The following files, if present, will be templated and provided to
kolla-ansible.  All paths are relative to ``$KAYOBE_CONFIG_PATH/kolla/config``.
Note that typically kolla-ansible does not use the same wildcard patterns, and
has a more restricted set of files that it will process.  In some cases, it may
be necessary to inspect the kolla-ansible configuration tasks to determine
which files are supported.

.. table: Kolla-ansible configuration files

   =============================== =======================================================
   File                            Purpose
   =============================== =======================================================
   ``ceph/*``                      Ceph configuration.
   ``glance.conf``                 Glance configuration.
   ``glance/*``                    Extended glance configuration.
   ``fluentd/filter``              Fluentd filter configuration.
   ``fluentd/input``               Fluentd input configuration.
   ``fluentd/output``              Fluentd output configuration.
   ``heat.conf``                   Heat configuration.
   ``heat/*``                      Extended heat configuration.
   ``horizon/*``                   Extended horizon configuration.
   ``ironic-inspector.conf``       Ironic inspector configuration.
   ``ironic.conf``                 Ironic configuration.
   ``ironic/*``                    Extended ironic configuration.
   ``keystone/*``                  Extended keystone configuration.
   ``magnum.conf``                 Magnum configuration.
   ``magnum/*``                    Extended magnum configuration.
   ``manila.conf``                 Manila configuration.
   ``manila/*``                    Extended manila configuration.
   ``murano.conf``                 Murano configuration.
   ``murano/*``                    Extended murano configuration.
   ``neutron.conf``                Neutron configuration.
   ``neutron/*``                   Extended neutron configuration.
   ``nova.conf``                   Nova configuration.
   ``nova/*``                      Extended nova configuration.
   ``sahara.conf``                 Sahara configuration.
   ``sahara/*``                    Extended sahara configuration.
   ``swift/*``                     Extended swift configuration.
   =============================== =======================================================

Configuring an OpenStack Component
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To provide custom configuration to be applied to all glance services, create
``$KAYOBE_CONFIG_PATH/kolla/config/glance.conf``.  For example:

.. code-block:: yaml
   :caption: ``$KAYOBE_CONFIG_PATH/kolla/config/glance.conf``

   [DEFAULT]
   api_limit_max = 500

Configuring an OpenStack Service
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To provide custom configuration for the glance API service, create
``$KAYOBE_CONFIG_PATH/kolla/config/glance/glance-api.conf``.  For example:

.. code-block:: yaml
   :caption: ``$KAYOBE_CONFIG_PATH/kolla/config/glance/glance-api.conf``

   [DEFAULT]
   api_limit_max = 500
