Configuration
=============

Configuration of services can be complex and hard to understand.
Especially in the context of OpenStack where you not only need to configure multiple individual services,
but also have individual configurations for specific nodes.

Configuration generally consists of two layers:

1. The Yaook layer.
   Here you find predefined settings that are either default values or fixed settings.
2. The user layer.
   Here you can define whatever configuration is necessary.
   For services that might need a per-node configuration (such as nova-compute),
   you can define configuration according to the labels of the target nodes.

Overwriting values
------------------

In contrast to many other configuration management solutions, Yaook does not allow you to overwrite values.
Once a setting is defined with a specific value it is guaranteed that this value will end up in the final configuration of the service.
This also means that there are some settings in the Yaook layer that are already set to final values and that you will not be able to change.
We also have default values in there which you can freely overwrite with whatever final value is plausible.

The same concept applies to the per-node configured services.
When you specify two pieces of configuration that match for a given node, these configurations are merged together.
You are also not allowed to specify conflicting values.

Handling of invalid configurations
----------------------------------

Configurations can get invalid by trying to overwrite a value that is already set somewhere else or by specifying a value with a wrong type (e.g. string instead of list).
If a user supplied configuration is invalid, the generation of the service configuration will fail.
If the service has not yet been deployed, then the deployment process will end at this step and wait for an update to the CR.
If the service has already been deployed, then the update of the service will also end at this step.
This ensures that whatever configuration is specified it will only end up in the service if it is valid.

Generating configuration
------------------------

The configuration is generated by a tool named cuelang (https://cuelang.org/).
This tool takes care of validating the configuration. It takes 3 inputs:

1. The configuration specified by OpenStack using oslo.config.
   These are automatically generated files from the services that ensure that types are used in a valid way.
2. The default configuration specified by Yaook.
3. The user defined configuration (or a concatenation of it, if it is a per-node configured service).

From the output of this generation process the particular OpenStack .conf file is created.

.. image:: figures/config_generation.drawio.svg

Non-definable configuration
----------------------------

Some configuration is generated automatically and fed into the config generation process or is generated on the individual Pod in the Kubernetes cluster.
The following is a list of all of these configurations.
They must not be set by the user, as this will cause validation errors.

=========================     ========================================     ================================================
Service                       Configuration                                Description
=========================     ========================================     ================================================
all                           any Keystone Credentials                     generated by the Operator automatically
nova                          ``neutron.metadata_proxy_shared_secret``     generated by the nova Operator
neutron-openvswitch-agent     ``ovs.local_ip``                             Generated on each pod with the IP of it's host
neutron-metadata-agent        ``DEFAULT.metadata_proxy_shared_secret``     extracted from the nova-metadata service secret
=========================     ========================================     ================================================