Skip to content

Configuration

Jump to bottom
synkd edited this page Aug 16, 2023 · 3 revisions

Configuration

Basics

The broker_settings.yaml file is used, through DynaConf, to set configuration values for Broker's interaction with its 'providers'. DynaConf integration provides support for setting environment variables to override any settings from broker's config file.

An environment variable override would take the form of: BROKER_AnsibleTower__base_url="https://my.ansibletower.instance.com". Note the use of double underscores to model nested maps in yaml.

Let's take a look at the example settings file and break down some important settings and concepts.

Example File Breakdown

logging:
    console_level: info
    file_level: debug

Broker allows you to set a different default log level for both console output and file output. The valid values for these fields are:

  • trace
  • debug
  • info
  • warning
  • error
host_username: "root"
host_password: "<password>"
host_ssh_port: "<port>"
host_ssh_key_filename: "</path/to/the/ssh-key>"

One of the main uses of Broker is as a way to manage and interact with infrastructure, called Hosts. For traditional VMs, this likely will be through an SSH connection. The settings above allow you to set default values for all SSH connections to Hosts Broker receives.

AnsibleTower Provider

AnsibleTower:
    instances:
        - production:
            base_url: "https://<ansible tower host>/"
            # Username AND password, OR an OAUTH token can be used for authentication
            username: "<username>"
            password: "<plain text password>"
            # token: "<AT personal access token>"
            inventory: "inventory name"
            default: True
        - testing:
            base_url: "https://<ansible tower host>/"
            # Username AND password, OR an OAUTH token can be used for authentication
            username: "<username>"
            password: "<plain text password>"
            # token: "<AT personal access token>"
            inventory: "inventory name"
    release_workflow: "remove-vm"
    extend_workflow: "extend-vm"
    new_expire_time: "+172800"
    workflow_timeout: 3600
    results_limit: 50

For the AnsibleTower provider, authentication can be achieved by setting a username and password, or through a token (Personal Access Token in Tower). Depending on your organization's security policies, one of these methods may be preferred over the other.

A username can still be provided when using a token to authenticate. This user will be used for inventory syncs. This might be helpful for AnsibleTower administrators who would like to use their own token to authenticate, but want to set a different user in configuration for checking inventory.

Note: Broker is designed to work against the SatLab standard for Ansible Tower (AAP). Without basing your instance on this standard, you likely won't be able to use Broker effectively. Please contact one of the maintainers of this repository to find out how you can adopt the same standard.

Container Provider

Much like the AnsibleTower section, the Container provider example also has two instances defined. Since docker has default set to True, it is the default Container instance.

Container:
    instances:
        - docker:
            host_username: "<username>"
            host_password: "<plain text password>"
            host_port: None
            default: True
        - remote:
            host: "<remote hostname>"
            host_username: "<username>"
            host_password: "<plain text password>"
    runtime: 'docker'
    # name used to prefix container names, used to distinguish yourself
    # if not set, then your local username will be used
    # name_prefix: test
    results_limit: 50
    auto_map_ports: False

The host settings under this section are used to establish a connection to the container runtime of your choice. You will notice that the docker instance does not have a host setting defined. This is because the default for that field, when not set, is localhost.

The runtime setting is used to specify whether Broker should expect to connect to docker or podman.

Broker also has the ability to automatically map ports exposed by a container to one on its parent machine. These mapping will be stored in Broker's inventory as well as on the live Host objects themselves.

Note: Using docker as the container runtime requires that the docker package be installed and the docker service be running on the machine executing broker. Additionally, by default, the SSH key of the local system user executing broker will be used to authenticate to the remote Container provider. Consequently, that user's SSH public key must be copied to the appropriate user on the remote provider system. For example, if user1 will be executing broker to deploy containers as the root user on docker-host.example.com, execute the ssh-copy-id command as follows while logged in as user1:

[user1@localsystem]$ ssh-copy-id [email protected]

Simplified Provider Settings

If you only want to have settings for one instance define, you can simplify your provider settings by removing the instances nesting altogether and moving all provider-specific settings to the provider's top level like below.

AnsibleTower:
    base_url: "https://<ansible tower host>/"
    # Username AND password, OR an OAUTH token can be used for authentication
    username: "<username>"
    password: "<plain text password>"
    # token: "<AT personal access token>"
    inventory: "inventory name"
    default: True
    release_workflow: "remove-vm"
    extend_workflow: "extend-vm"
    new_expire_time: "+172800"
    workflow_timeout: 3600
    results_limit: 50

Nicks

Broker allows you to define configurable nicknames as shorthand when bundling one or more arguments together. These nicks will be expanded at runtime into their argument form. Let's take a look at the below examples.

nicks:
    rhel7:
        workflow: "deploy-base-rhel"
        rhel_version: "7.9"
        notes: "Requested by broker"
    test_nick:
        test_action: "fake"
        arg1: "abc"
        arg2: 123
        arg3: True

Here we have two nicks defined rhel7 and test_nick. Each of these has a handful of key-value pairs defined underneath; all valid arguments for our example user. A runtime example of rhel7 being used in the CLI would look like this.

broker checkout --nick rhel7

Which is equivalent to

broker checkout --workflow: deploy-base-rhel --rhel_version: 7.9 --notes: "Requested by broker"

The same is also true for Broker's library use.

Broker(nick="test_nick").execute()

Which is equivalent to

Broker(test_action="fake", arg1="abc", arg2=123, arg3=True).execute()

Advanced

You may have noticed that Broker's providers have settings at both their top level and at the instance level. This is because Broker will take the instance-level settings and move them to the top level at runtime. This means that you only need to define the settings that are specific to each instance at the instance level. If you have the same username/password/token, those can remain at the top level. The same is true in reverse. You can also override the top-level settings at each instance.

One important note for this is that if you are setting your top-level settings via environment variables, they will override your instance-level settings by default. You can swap this preference by adding override_envars: True in your instance's settings. See the TestProvider in the example settings file.

Clone this wiki locally