-
Notifications
You must be signed in to change notification settings - Fork 42
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.
Let's take a look at the example settings file and break down some important settings and concepts.
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:
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.
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 root@docker-host.example.com
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
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()
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.