(Non‐GA) Local Config Objects

Using Localized Configurations

Broker offers powerful flexibility for managing configurations. While a central broker_settings.yaml is used by default, you can create and use isolated settings objects for specific tasks. This is ideal for scenarios like:

• Using different credentials for a provider without changing global settings.
• Testing new configuration values in an isolated environment.
• Running multiple Broker instances with distinct configurations simultaneously.
• Embedding Broker in an application with a programmatic and self-contained configuration.

This guide explains how to create and use these localized configurations.

Creating a Local Settings Object

The primary way to create a custom configuration is with the broker.settings.create_settings helper function. It allows you to build a settings object from various sources.

From a Dictionary

For programmatic configuration, you can create a settings object directly from a Python dictionary.

from broker.settings import create_settings

# Define configuration in a dictionary
my_config = {
    "ANSIBLETOWER": {
        "BASE_URL": "https://tower.example.org",
        "TOKEN": "my_secret_token"
    },
    "thread_limit": 5
}

# Create a settings object from the dictionary
local_settings = create_settings(config_dict=my_config)

# This settings object is completely independent of the global settings.

From a YAML file

You can also load settings from any YAML file, which is useful for managing multiple, distinct configuration files.

from broker.settings import create_settings

# Assume you have a 'special_config.yaml' file:
# CONTAINER:
#   RUNTIME: "podman"
#   HOST: "unix:///run/user/1000/podman/podman.sock"

# Create a settings object from the YAML file
file_settings = create_settings(config_file="/path/to/special_config.yaml")

Cloning and Modifying Global Settings

If you just need to tweak the existing global configuration, you can clone it. This creates a deep copy that you can modify without affecting the original.

from broker.settings import clone_global_settings

# Create a deep copy of the global settings
local_settings = clone_global_settings()

# Now, you can safely modify it
local_settings.ANSIBLETOWER.BASE_URL = "https://staging-tower.example.org"
local_settings.SSH.HOST_USERNAME = "staging_user"

How Local Settings Work: Isolation by Default

When you instantiate a Broker, Provider, or Host object, it is automatically provided with an isolated configuration:

1. If you pass a broker_settings object: The instance will use that specific object.
2. If you do not pass one: The instance will automatically receive a clone of the global settings.

This means that any modifications to an instance's settings (e.g., my_host._settings.SSH.HOST_USERNAME = 'new_user') will not affect the global configuration or any other instances. This design ensures predictable behavior and prevents side effects.

Completely Disabling the Global Configuration

In some cases, you might want to prevent Broker from loading the global broker_settings.yaml file entirely. This is useful in controlled environments or when embedding Broker in another application, ensuring that no external configuration files can interfere.

You can achieve this in two ways:

1. Via Environment Variable: Set the BROKER_NO_GLOBAL_CONFIG environment variable to any value (e.g., export BROKER_NO_GLOBAL_CONFIG=1).

2. Programmatically: Set a class-level attribute on ConfigManager before any Broker modules are imported or used.

from broker.config_manager import ConfigManager

# This must be done early, before other Broker components are initialized
ConfigManager.no_global_config = True

# Now, Broker will not attempt to load ~/.broker/broker_settings.yaml.
# It will start with a clean slate of default values, which can be
# populated from environment variables or a settings object you provide.
from broker.settings import create_settings

# This will only use default values and environment variables.
settings = create_settings()

Usage with Broker Components

To use your custom configuration, simply pass it to the constructor of a Broker, Provider, or Host object using the broker_settings argument. The instance will then use these settings for all its operations, including validation.

With the Broker Class

from broker.broker import Broker
from broker.settings import create_settings

# Create a settings object for a specific Tower instance
broker_config = {
    "ANSIBLETOWER": {
        "BASE_URL": "https://special-tower.example.com",
        "TOKEN": "a_different_token"
    }
}
local_settings = create_settings(config_dict=broker_config)

# Instantiate Broker with the local settings
broker = Broker(
    workflow="my-workflow",
    broker_settings=local_settings
)

# This checkout will use the URL and token from 'local_settings'
hosts = broker.checkout()

With Provider Classes

You can also scope a configuration to a single provider instance. The provider will validate its settings against the provided configuration.

from broker.providers.container import Container
from broker.settings import create_settings

# Create local settings for a specific container runtime
podman_config = {
    "CONTAINER": {
        "RUNTIME": "podman",
        "HOST": "unix:///run/user/1000/podman/podman.sock"
    }
}
podman_settings = create_settings(config_dict=podman_config)

# Instantiate the provider with the custom settings
# The provider will validate its section of the config ('CONTAINER')
container_provider = Container(broker_settings=podman_settings)

# This action will be performed using the Podman runtime specified above
apps = container_provider.provider_help(container_apps=True)

With Host Classes

A Host object can be initialized with a local settings object to customize SSH connection parameters without altering the global configuration.

from broker.hosts import Host
from broker.settings import create_settings

# Define a special SSH configuration
special_ssh_config = {
    "SSH": {
        "HOST_USERNAME": "testuser",
        "HOST_CONNECTION_TIMEOUT": 10,
        "HOST_SSH_PORT": 2222
    }
}
special_ssh_settings = create_settings(config_dict=special_ssh_config)

# Create a Host instance with the special settings
my_host = Host(
    hostname="server.special.net",
    broker_settings=special_ssh_settings
)

# The connection will use 'testuser', a 10-second timeout, and port 2222,
# as defined in our special_ssh_settings object.
my_host.connect()
result = my_host.session.run("whoami")
print(result.stdout) # ==> "testuser"