CLI Usage

CLI Usage

Although Broker's primary actions are checkout and checkin, it also exposes a number of other CLI-based actions to help you manage your infrastructure.

Checking out a VM or Container

You can pass in any arbitrary arguments you want.

broker checkout --workflow "workflow-name" --workflow-arg1 something --workflow-arg2 else

Passing environment variables to the target container.

broker checkout --nick rhel7 --environment "VAR1=val1,VAR2=val2"

Broker can also checkout multiple VMs at once by specifying a count.

broker checkout --nick rhel7 --count 3

Overriding default instance

To specify an instance, checkout should be performed against, pass a flag name matching your provider class and a value matching the instance name.

Note: The provider class must match both name and case, see your settings file for those.

broker checkout --nick rhel7 --AnsibleTower testing

File-based arguments

If you have more complex data structures you need to pass in, you can do that in two ways. You can populate a json or yaml file where the top-level keys will become broker arguments and their nested data structures become values.

Note: The json and yaml files need to use the supported suffix ('json', 'yaml', '.yml') in order to be properly recognized. Any eventual arbitrary arguments passed to CLI will be combined with those in the passed argument file with the CLI ones taking precedence.

broker checkout --nick rhel7 --args-file tests/data/broker_args.json

You can also pass in a file for other arguments, where the contents will become the argument's value

broker checkout --nick rhel7 --extra tests/data/args_file.yaml

Note: Check with the provider to determine specific arguments.

Nicks

You can use nicks as shorthand when checking out hosts.

broker checkout --nick rhel7

Duplicating a VM

Broker offers another shortcut for checking out a VM with the same recipe as one already checked out by Broker. This is via the duplicate command.

broker duplicate my.awesome.vm.com
broker duplicate 0
broker duplicate 1 3
broker duplicate 0 --count 2

Inventory Management

Broker maintains a local inventory of the VMs and containers you've checked out. You can see these with the inventory command.

broker inventory

To sync your inventory from a supported provider, use the --sync option.

broker inventory --sync AnsibleTower

To sync an inventory for a specific user, use the following syntax with --sync.

broker inventory --sync AnsibleTower:<username>

To sync an inventory for a specific instance, use the following syntax with --sync.

broker inventory --sync Container::<instance name>

This can also be combined with the user syntax above.

broker inventory --sync Container:<username>::<instance name>

Extending VM Lease Time

Providers supporting extending a VM's lease time make that functionality available through the extend subcommand.

broker extend 0
broker extend hostname
broker extend vmname
broker extend --all

Checking in VMs and Containers

You can also return a VM to its provider with the checkin command. Containers checked in this way will be fully deleted regardless of their status. You may use either the local id (broker inventory), the hostname, or "all" to checkin everything. You can provide more nuance with all by passing in a filter.

broker checkin my.host.fqdn.com
broker checkin 0
broker checkin 1 3 my.host.fqdn.com
broker checkin --all
broker checkin --all --filter "name<test"

Provider Information

Broker's providers command allows you to gather information about what providers are available as well as each provider's actions. Additionally, you can find out information about different arguments for a provider's action with this command.

broker providers --help
broker providers AnsibleTower --help
broker providers AnsibleTower --workflows
broker providers AnsibleTower --workflow remove-vm

Execute Arbitrary Actions

If a provider action doesn't result in a host creation/removal, Broker allows you to execute that action as well. There are a few output options available as well. When executing with the Container provider, a new container will be spun up with your command (if specified), ran, and cleaned up.

broker execute --help
broker execute --workflow my-awesome-workflow --additional-arg True
broker execute -o raw --workflow my-awesome-workflow --additional-arg True
broker execute -o raw --workflow my-awesome-workflow --additional-arg True --artifacts last

Machine Processable Output

If running in a CI or other automated environment, Broker offers the choice to store important output information in an output file. This is JSON-formatted data. Please be aware that any existing file with the matching path and name will be erased.

broker --output-file output.json checkout --nick rhel7
broker --output-file inventory.json inventory

Run Broker in the Background

Certain Broker actions can be run in the background, these currently are checkout, checkin, duplicate, and execute. When running a command in this mode, it will spin up a new Broker process and no longer log to stderr. To check progress, you can still follow broker's log file.

Note: Background mode will interfere with output options for execute since it won't be able to print to stdout. Those should be kept in log mode.

broker checkout --background --nick rhel7
broker checkin -b --all
broker duplicate -b 0
broker execute -b --workflow my-awesome-workflow --artifacts

Filter Hosts for Broker actions

Certain CLI actions can be used in combination with Broker's filtering mechanism. Please read through the filtering section of this Wiki for more information.

These typically fall into two categories:

1. When filtering hosts in an inventory during checkin and inventory actions.
2. When filtering a list of results in the output of provider help commands.

Note: Due to shell expansion, it is recommended to wrap a filter in single quotes.