Creating configurable actors

Leapp provides (since framework_version = 6.0) a built-in way on creating configurable actors. Therefore, there is no need to use ad-hoc configuration files with an actor-specific format or introduce environmental variables. Instead, it suffices to declare how your config should look like, and the framework will take care of locating, parsing and merging config files so that the config values are provided in a simple, dictionary-like form. User provides leapp with YAML files stored within /etc/leapp/actor_conf.d/. These files are then read, parsed and type-checked. Afterwards, any actor that declares need to access specific configuration fields is provided with its own copy of the user-provided configuration.

Declaring your configuration

Leapp scopes configuration declarations in the same way as it handles libraries. Configuration available for all actors within a repository is located within $repository/configs whereas actor-specific configuration is searched for within $actor_directory/configs. Configuration declarations are ordinary Python files, somewhat similar to model declarations. To declare a config field, one creates a class inheriting from leapp.actors.config.Config that declares the following class attributes:

Field	Semantics
section	Section of the config to which the field belongs
name	Field name set within the actual config, i.e., the config will contain name : value
type_	Type of the field value. If the user-provided config contains incorrect type, an error will be raised early in leapp execution
default	Default value for the field, if the field is not set in user-provided config files
description	String documenting semantics of the config field represented by the class

For example, to create a configuration field controlling whether network- interface renaming is managed accessible be all actors, start by creating the file $repository/configs/network_cfg.py with the following contents:

from leapp.actors.config import Config

class EnableNICRenamingChecksField(Config):
    section = 'networking'
    name = 'enable_nic_renaming_checks'
    type_ = fields.Boolean()
    default = True  # Enabled by default
    description = """
        If set to True, actors will check and manage network interfaces getting renamed during the upgrade.
    """

Accessing configuration values

Any actor that requires reading the networking.enable_nic_renaming_checks configuration value provided by the user must then declare access to this config value within its definition. After declaring its configuration access, the actor can access the corresponding config field using api.current_actor().config[$section][$field_name] where $section is the value of the $section and $field_name are the values of section and name class attribute, respectively. For example, given an actor defined in scan_source_nic_names/actor.py, we would have:

from leapp.actors import Actor
from leapp.configs.common.network_cfg import EnableNICRenamingChecksField
from leapp.models import SourceNICsInfo
from leapp.tags import FactsPhaseTag, IPUWorkflowTag


class ScanSourceNICs(Actor):
    """
    Gather information about NICs installed on the source system
    """

    name = 'scan_source_nics'
    config_schemas = (EnableNICRenamingChecksField,)  # Declare what configuration we are accessing
    consumes = ()
    produces = (SourceNICsInfo)
    tags = (FactsPhaseTag, IPUWorkflowTag)

    def process(self):
        config_value = api.current_actor().config['networking']['enable_nic_renaming_checks']
        # Do something with config value

Not that, naturally, one can use the api.current_actor().config dictionary from any library as well.

Providing actors with configuration

Framework scans for any YAML files (directly) under /etc/leapp/actor_conf.d/. The structure of these YAML files is the following:

sectionA:
  field1: value1
  field2: value2
  field3: value3

sectionB:
  field1: value1
  field2: value2
  field3: value3

Therefore, to turn off NIC renaming checks using the networking.enable_nic_renaming_checks field defined above, one would create, e.g., a file named /etc/leapp/actors.conf.d/networking.yaml with the following content:

networking:
  enable_nic_renaming_checks: False