-
Notifications
You must be signed in to change notification settings - Fork 43
Configuration
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.
From Broker 0.6.x and onward it is recommended to use the broker config command group to interact with Broker's configuration file. See the section on that below for more information.
Let's take a look at the example settings file and break down some important settings and concepts.
logging:
console_level: info
file_level: debugBroker 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
ssh:
backend: hussh
host_username: root
host_password: toor
host_ipv6: false
host_ipv4_fallback: trueOne 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.
Broker also supports a number of backend libraries that perform the actual ssh interactions. You can set your desired backend in this field. However, be sure you also install the corresponding dependency! (uv) pip install broker[hussh]
You can also try to force an ipv6 connection against a host when establishing an ssh connection. However, if that fails, broker can also attempt to fall back to ipv4 if you let it.
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: 50For 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.
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: FalseThe 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]
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: 50Broker 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: TrueHere 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()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.
Broker offers a convenient command group to assist in viewing, editing, and migrating your configuration file.
Simply just print out the config when no config chunk is passed in
broker config view
When a config chunk is passed in, print out just that chunk
broker config view Container
broker config view Container.instances.remote
A chunk is any section of the config smaller than the whole
Since broker uses yaml for it's config, each chunk is likely to be a key
We will use dotted notation to access nested chunks
broker config view Container.instances.remote
When no chunk is passed in, edit the entire config file
broker config edit
When passed a valid config chunk, edit that chunk
broker config edit AnsibleTower
broker config view Container.instances.remote
Set the value of a single config entry
broker config set Container.host_name test.host
Or copy the contents of a file into a config chunk
broker config set Foreman foreman_settings.yaml
broker config set Container.instances.local local_podman.json
Did you make a mistake in your last edit or set? That's ok, because each time you perform one of those actions, broker will make a backup if your settings before the change. You can then restore from that backup by using the restore command.
broker config restore
However, there is only one backup file, so you can't restore further than your last change!
Some users just want to see a list of their active nicks
broker config nicks
Will just print out a list of the current nicks
You can also see details of a specific nick
broker config nick sat617
# This is basically just an alias for
broker config view nicks.sat617
Gives users a more explicit way to get their settings
broker config init
# can also just init one chunk
broker config init Container
# can also choose the source file
broker config init Container --from /path/to/settings.yaml
broker config init --from https://raw.githubuser.../file.yaml
Will still automatically run when needed
Migrate an old config to the current version of broker
broker config migrate
Each config file will have a _version attribute that will only be updated by the migrate command (or manually)
These migrations will attempt to run automatically. However, you can also force migrations for a specific version to run.
broker config migrate --force-version 0.6.0
Validate high-level config chunks
# base settings <base>
broker config validate
# validate a provider
broker config validate AnsibleTower
# validate a provider instance
broker config validate Container:ipv4_podman
# validate all settings
broker config validate all