### Configure Beaker Client

Source: https://github.com/satelliteqe/broker/wiki/Installation

Provides example configurations for the Broker settings file (broker_settings.yaml) and the ~/.beaker_client/config file, including hub URL and authentication methods for the Beaker provider.

```yaml
Beaker:
    hub_url: https://beaker.engineering.<host>.com
```

```yaml
KRB_REALM = "IPA.<HOST>.COM"
AUTH_METHOD = "krbv"
HUB_URL = "https://beaker.engineering.<host>.com/"
```

--------------------------------

### Install Broker from Git Clone

Source: https://github.com/satelliteqe/broker/wiki/Installation

Installs Broker by cloning the repository and then using pip to install it locally. This method is useful for development or when using the latest unreleased version.

```bash
cd <broker repo directory>
pip install .
```

--------------------------------

### Install Broker via pip

Source: https://github.com/satelliteqe/broker/wiki/Installation

Installs the Broker package from the Python Package Index (PyPI) using pip. This is the recommended method for most users.

```bash
pip install broker
```

--------------------------------

### Install Container Provider Dependencies (pip)

Source: https://github.com/satelliteqe/broker/wiki/Installation

Installs optional dependencies for the Container provider, supporting either Podman or Docker as the container runtime.

```bash
pip install broker[podman]
```

```bash
pip install broker[docker]
```

--------------------------------

### Install Beaker Dependencies (pip)

Source: https://github.com/satelliteqe/broker/wiki/Installation

Installs the Beaker provider-specific dependencies for Broker using pip.

```bash
pip install broker[beaker]
```

--------------------------------

### Check Broker Version and Configuration

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Checks the installed Broker version and verifies the location of its configuration file. If no `broker_settings.yaml` exists, it guides the user through setup.

```Shell
broker --version
```

--------------------------------

### Install Linux Prerequisites (dnf)

Source: https://github.com/satelliteqe/broker/wiki/Installation

Installs necessary system packages like cmake and python development headers on Fedora, RHEL, or CentOS systems using the dnf package manager.

```bash
dnf install cmake python3-devel
```

--------------------------------

### Install Beaker Provider Dependencies (dnf)

Source: https://github.com/satelliteqe/broker/wiki/Installation

Installs the krb5-devel system package required for the Beaker provider, which relies on Kerberos authentication.

```bash
sudo dnf install -y krb5-devel
```

--------------------------------

### Install macOS Prerequisites (brew)

Source: https://github.com/satelliteqe/broker/wiki/Installation

Installs necessary development tools and libraries on macOS using the Homebrew package manager, including cmake, openssl, and libssh2.

```bash
brew install cmake
brew install openssl
brew install libssh2
```

--------------------------------

### Test Beaker Provider Configuration

Source: https://github.com/satelliteqe/broker/wiki/Installation

A command to verify that the Beaker provider is correctly configured by listing jobs associated with the current user.

```bash
broker providers Beaker --jobs --mine
```

--------------------------------

### Install Broker with uv

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Installs the Broker tool using the uv package manager. uv is recommended for managing Python installations and dependencies.

```Shell
uv tool install broker
```

--------------------------------

### Install Broker with Beaker Provider

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Installs Broker with the extra dependency for the Beaker provider. This requires installing `krb5-devel` first and then installing the Broker package with the Beaker extra.

```Shell
dnf install krb5-devel
... install broker[beaker]
```

--------------------------------

### Install Broker with Container Provider (Podman)

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Installs Broker with the extra dependency for the Podman container runtime. This is an optional step if you are using the Container provider.

```Shell
... install broker[podman]
```

--------------------------------

### Custom Host Setup and Teardown Methods

Source: https://github.com/satelliteqe/broker/wiki/API-Usage

Shows how to implement setup and teardown methods within a custom Host class that are automatically called by the Broker context manager.

```Python
class MyHost(Host):
    ...
    def setup(self):
        self.register()

    def teardown(self):
        self.unregister()
```

--------------------------------

### Broker Checkout API Example

Source: https://github.com/satelliteqe/broker/wiki/API-Usage

Shows how to perform a host checkout using the Broker class, mirroring CLI arguments with underscore syntax.

```Python
rhel7_host = Broker(nick="rhel7", args_file="tests/data/broker_args.json", environment={"VAR1": "val1", "VAR2": "val2"}).checkout()
```

--------------------------------

### Install Broker with pip

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Installs the Broker package using pip. It is recommended to perform this installation within a Python virtual environment.

```Shell
pip install broker
```

--------------------------------

### Set DYLD_LIBRARY_PATH for libssh2 on macOS

Source: https://github.com/satelliteqe/broker/wiki/Installation

Instructs how to set the DYLD_LIBRARY_PATH environment variable to help the system locate libssh2 .dylib files, often required after Homebrew installations.

```bash
export DYLD_LIBRARY_PATH=/opt/homebrew/Cellar/libssh2/1.10.0/lib/
```

--------------------------------

### Set Broker Directory Environment Variable

Source: https://github.com/satelliteqe/broker/wiki/Installation

Configures the BROKER_DIRECTORY environment variable to specify the location of Broker's files, allowing it to run outside its base directory.

```bash
BROKER_DIRECTORY=/home/jake/Programming/broker/ broker inventory
```

--------------------------------

### Install Broker with Container Provider (Docker)

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Installs Broker with the extra dependency for the Docker container runtime. This is an optional step if you are using the Container provider.

```Shell
... install broker[docker]
```

--------------------------------

### Get Help for Providers Command

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Displays general help information for the 'providers' command.

```bash
broker providers --help
```

--------------------------------

### Get Provider Help Information

Source: https://github.com/satelliteqe/broker/wiki/CLI-Usage

Retrieves help information about Broker providers and their actions. This includes general help, help for specific providers, listing available workflows, and details about workflow arguments.

```bash
broker providers --help
```

```bash
broker providers AnsibleTower --help
```

```bash
broker providers AnsibleTower --workflows
```

```bash
broker providers AnsibleTower --workflow remove-vm
```

--------------------------------

### Get Help for Specific Provider

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Displays help information for a specific provider, such as AnsibleTower.

```bash
broker providers AnsibleTower --help
```

--------------------------------

### Define and Use Nicknames for Broker Arguments

Source: https://github.com/satelliteqe/broker/wiki/Configuration

Illustrates how to define configurable nicknames in Broker to bundle arguments. It shows two examples, 'rhel7' and 'test_nick', with their respective key-value pairs. It also provides CLI and library usage examples for these nicknames.

```yaml
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
```

--------------------------------

### Recommended Broker Context Manager Usage

Source: https://github.com/satelliteqe/broker/wiki/API-Usage

Provides an example of using the Broker class as a context manager for automatic checkout and checkin, including executing a command.

```Python
with Broker(container_host="ch-d:rhel7") as container_host:
    assert container_host.hostname in container_host.execute("hostname").stdout
```

--------------------------------

### Fix pycurl Installation Error on macOS

Source: https://github.com/satelliteqe/broker/wiki/Installation

Provides commands to uninstall pycurl and reinstall it using OpenSSL, resolving potential build issues on macOS.

```bash
$ pip uninstall pycurl
$ PYCURL_SSL_LIBRARY=openssl LDFLAGS="-L$(brew --prefix openssl)/lib" CPPFLAGS="-I$(brew --prefix openssl)/include" pip install --compile --install-option="--with-openssl" pycurl
```

--------------------------------

### Filter by Template Prefix

Source: https://github.com/satelliteqe/broker/wiki/Filters

This filter checks if the 'template' property, nested within '_broker_args', starts with the string 'deploy-sat'. It uses Python's string startswith() method.

```Shell
--filter '@inv._broker_args.template.startswith("deploy-sat")'
```

--------------------------------

### Broker Library Usage with Nickname

Source: https://github.com/satelliteqe/broker/wiki/Configuration

Provides an example of using a defined nickname ('test_nick') when utilizing the Broker library in Python to execute a set of bundled arguments.

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

--------------------------------

### Get Information about a Specific Workflow

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Retrieves detailed information about a specific workflow for a provider.

```bash
broker providers AnsibleTower --workflow test-workflow
```

--------------------------------

### Chained Filters: Hostname and Provider

Source: https://github.com/satelliteqe/broker/wiki/Filters

This example demonstrates chaining two filters using the pipe symbol. It first filters hosts whose names contain 'test' and then further filters those results to exclude hosts where the provider is 'RHV'.

```Shell
--filter '"test" in @inv.name | @inv._broker_args.provider != "RHV"'
```

--------------------------------

### Disable Global Configuration Loading in Broker

Source: https://github.com/satelliteqe/broker/wiki/(Non‐GA)-Local-Config-Objects

Explains how to prevent Broker from loading the global configuration file (`~/.broker/broker_settings.yaml`) by setting `ConfigManager.no_global_config = True` or the `BROKER_NO_GLOBAL_CONFIG` environment variable. This ensures Broker starts with default values or programmatically provided settings.

```Python
from broker.config_manager import ConfigManager

# Disable loading of the global configuration file
ConfigManager.no_global_config = True

# Now, any subsequent calls to create_settings() or instantiations of Broker
# will not attempt to load the global settings file if it's not found,
# and will start with a clean slate of default values.
from broker.settings import create_settings

# This will not load any global settings file.
# It will only use default values and environment variables.
settings = create_settings()
```

--------------------------------

### Execute Provider Action with Help

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Displays help information for the 'execute' command.

```bash
broker execute --help
```

--------------------------------

### Checkout Single VM with Arguments

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Checks out a single VM with specified workflow and arguments.

```bash
broker checkout --workflow test-workflow --workflow-arg1 something --workflow-arg2 else
```

--------------------------------

### Initialize Broker Configuration

Source: https://github.com/satelliteqe/broker/wiki/Configuration

Provides an explicit way to initialize settings, either for the entire configuration or specific chunks. It can also initialize from a specified source file or URL.

```bash
broker config init
broker config init Container
broker config init Container --from /path/to/settings.yaml
broker config init --from https://raw.githubuser.../file.yaml
```

--------------------------------

### Checkout VM/Container using Nick

Source: https://github.com/satelliteqe/broker/wiki/CLI-Usage

Checks out a VM or container using a predefined nick, which serves as a shorthand for host configuration. Nicks are defined in the Broker configuration.

```bash
broker checkout --nick rhel7
```

--------------------------------

### Checkin All VMs and Containers

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Returns all checked-out VMs and containers to their providers.

```bash
broker checkin --all
```

--------------------------------

### Checkout with Complex Data Structures

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Checks out a VM using complex data structures passed via files for arguments and extra configurations.

```bash
broker checkout --container-host my-image --args-file tests/data/broker_args.json --extra tests/data/args_file.yaml
```

--------------------------------

### Checkout VM/Container with File-based Arguments (JSON)

Source: https://github.com/satelliteqe/broker/wiki/CLI-Usage

Checks out a VM or container, providing arguments from a JSON file. Top-level keys in the JSON file map to Broker arguments, and nested structures become their values. CLI arguments take precedence over file arguments.

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

--------------------------------

### View Broker Configuration

Source: https://github.com/satelliteqe/broker/wiki/Configuration

Displays the entire broker configuration or specific chunks using dotted notation. No dependencies are explicitly mentioned, but it operates on the broker's YAML configuration files.

```bash
broker config view
broker config view Container
broker config view Container.instances.remote
```

--------------------------------

### List Workflows for a Provider

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Lists all available workflows for a specific provider.

```bash
broker providers AnsibleTower --workflows
```

--------------------------------

### Import Broker Class in Python

Source: https://github.com/satelliteqe/broker/wiki/Home

Demonstrates how to import the Broker class from the broker library to utilize its functionalities programmatically. This is the entry point for using Broker's API.

```Python
from broker import Broker
```

--------------------------------

### Checkout VM using Nickname

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Checks out a VM using a pre-configured nickname defined in settings.yaml.

```bash
broker checkout --nick rhel7
```

--------------------------------

### Checkout Multiple VMs

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Checks out multiple VMs at once by specifying a count.

```bash
broker checkout --workflow test-workflow --count 3
```

--------------------------------

### Execute Provider Action with Arguments

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Executes a provider action with specified workflow and additional arguments.

```bash
broker execute --workflow my-awesome-workflow --additional-arg True
```

--------------------------------

### Broker Library Equivalent Arguments

Source: https://github.com/satelliteqe/broker/wiki/Configuration

Shows the expanded form of the 'test_nick' nickname when used via the Broker Python library, listing all the individual arguments passed to the execute method.

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

--------------------------------

### Execute Provider Action with Raw Output

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Executes a provider action and outputs the result in raw format, specifying artifacts.

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

--------------------------------

### Checkout VM/Container with Environment Variables

Source: https://github.com/satelliteqe/broker/wiki/CLI-Usage

Checks out a VM or container and sets environment variables within the target instance. This allows for dynamic configuration of the checked-out resource.

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

--------------------------------

### List Local Inventory

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Lists the local inventory of VMs and containers that have been checked out.

```bash
broker inventory
```

--------------------------------

### Checkout Multiple VMs/Containers

Source: https://github.com/satelliteqe/broker/wiki/CLI-Usage

Checks out a specified count of VMs or containers using a given nick. This is a shortcut for provisioning multiple identical resources.

```bash
broker checkout --nick rhel7 --count 3
```

--------------------------------

### Broker CLI Equivalent Arguments

Source: https://github.com/satelliteqe/broker/wiki/Configuration

Shows the expanded form of the 'rhel7' nickname when used via the Broker CLI, listing all the individual arguments that are executed.

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

--------------------------------

### Create Broker Settings from YAML File

Source: https://github.com/satelliteqe/broker/wiki/(Non‐GA)-Local-Config-Objects

Shows how to load Broker configuration settings from a YAML file. This approach is beneficial for managing separate configuration files, especially when dealing with environment-specific settings or testing different configurations.

```Python
from broker.settings import create_settings

# Assume you have a 'special_config.yaml' file
# with content like:
# 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")
```

--------------------------------

### Checkin All VMs/Containers with Filter

Source: https://github.com/satelliteqe/broker/wiki/CLI-Usage

Checks in all VMs and containers managed by Broker, with an optional filter to specify which resources to return. This allows for selective cleanup of resources.

```bash
broker checkin --all
```

```bash
broker checkin --all --filter "name<test"
```

--------------------------------

### Checkout VM/Container with Workflow Arguments

Source: https://github.com/satelliteqe/broker/wiki/CLI-Usage

Checks out a VM or container, passing custom arguments to a specified workflow. This is useful for configuring the environment or execution parameters during the checkout process.

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

--------------------------------

### Import Broker Class

Source: https://github.com/satelliteqe/broker/wiki/API-Usage

Demonstrates how to import the Broker class from the broker library.

```Python
from broker import Broker
```

--------------------------------

### Run Execute in Background

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Executes a provider action in the background, specifying artifacts.

```bash
broker execute -b --workflow my-awesome-workflow --artifacts
```

--------------------------------

### Broker Config Init

Source: https://github.com/satelliteqe/broker/wiki/Version-Updates

Provides a way for users to initialize their broker settings. It can initialize the entire configuration, a specific chunk, or use a specified source file (local path or URL) for initialization.

```Bash
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
```

--------------------------------

### Instantiate Container Provider with Custom Settings

Source: https://github.com/satelliteqe/broker/wiki/(Non‐GA)-Local-Config-Objects

Demonstrates initializing a `Container` provider with a specific, localized settings object. This enables the provider to use custom configurations, such as a different container runtime or socket path, for its operations.

```Python
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
container_provider = Container(broker_settings=podman_settings)
```

--------------------------------

### Checkout VM/Container with File-based Arguments (YAML)

Source: https://github.com/satelliteqe/broker/wiki/CLI-Usage

Checks out a VM or container, providing arguments from a YAML file. The file's content is used as the argument's value. This is useful for passing complex or large data structures.

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

--------------------------------

### Initialize Host with Custom SSH Settings (Python)

Source: https://github.com/satelliteqe/broker/wiki/(Non‐GA)-Local-Config-Objects

This snippet shows how to create a Host object with custom SSH configurations, such as username and connection timeout, by using a local settings object. It then connects to the host and runs a command, printing the output.

```python
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
    }
}
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' and a 10-second timeout
my_host.connect()
result = my_host.session.run("whoami")
print(result.stdout) # ==> "testuser"
```

--------------------------------

### Instantiate Broker with Local Settings

Source: https://github.com/satelliteqe/broker/wiki/(Non‐GA)-Local-Config-Objects

Shows how to initialize the `Broker` class with a custom, localized settings object. This allows the Broker instance to use specific configurations, such as different API endpoints or authentication tokens, for its operations.

```Python
from broker.broker import Broker
from broker.settings import create_settings

# Create a settings object from a dictionary
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()
```

--------------------------------

### Generate Machine Processable Output with Broker

Source: https://github.com/satelliteqe/broker/wiki/CLI-Usage

Broker can output important information in a JSON-formatted file for CI or automated environments. Existing files with the same name will be overwritten.

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

--------------------------------

### Checkin Multiple VMs or Containers

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Returns multiple VMs or containers to their provider using their IDs or hostnames.

```bash
broker checkin 1 3 my.host.fqdn.com
```

--------------------------------

### View Broker Inventory

Source: https://github.com/satelliteqe/broker/wiki/CLI-Usage

Displays the local inventory of VMs and containers managed by Broker. This command provides a list of checked-out resources.

```bash
broker inventory
```

--------------------------------

### Sync Inventory from Provider

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Synchronizes the local inventory from a supported provider.

```bash
broker inventory --sync AnsibleTower
```

--------------------------------

### Execute Arbitrary Provider Actions

Source: https://github.com/satelliteqe/broker/wiki/CLI-Usage

Executes arbitrary actions defined by a provider that do not necessarily result in host creation or removal. This command supports various output options and artifact retrieval.

```bash
broker execute --help
```

```bash
broker execute --workflow my-awesome-workflow --additional-arg True
```

```bash
broker execute -o raw --workflow my-awesome-workflow --additional-arg True
```

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

--------------------------------

### Checkout VM/Container with Specific Instance Override

Source: https://github.com/satelliteqe/broker/wiki/CLI-Usage

Checks out a VM or container, overriding the default instance selection by specifying a provider-specific instance name. The provider class name must match exactly.

```bash
broker checkout --nick rhel7 --AnsibleTower testing
```

--------------------------------

### Output Checkout Command to File

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Executes the checkout command and saves the machine-processable output to a JSON file.

```bash
broker --output-file output.json checkout --nick rhel7
```

--------------------------------

### Run Checkin in Background

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Executes the checkin command in the background using a shorthand flag.

```bash
broker checkin -b --all
```

--------------------------------

### Broker CLI Usage with Nickname

Source: https://github.com/satelliteqe/broker/wiki/Configuration

Demonstrates how to use a defined nickname ('rhel7') on the Broker command-line interface (CLI) to execute a set of bundled arguments.

```bash
broker checkout --nick rhel7
```

--------------------------------

### Create Broker Settings from Dictionary

Source: https://github.com/satelliteqe/broker/wiki/(Non‐GA)-Local-Config-Objects

Demonstrates creating an isolated Broker settings object from a Python dictionary. This method is useful for programmatic configuration and allows specifying parameters like API base URLs and tokens independently of global settings.

```Python
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.
```

--------------------------------

### Sync Inventory for Specific Instance

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Synchronizes the inventory for a specific instance from a provider.

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

--------------------------------

### Checkin VM or Container by ID

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Returns a VM or container to its provider using its local inventory ID.

```bash
broker checkin 0
```

--------------------------------

### Clone Global Broker Settings

Source: https://github.com/satelliteqe/broker/wiki/(Non‐GA)-Local-Config-Objects

Illustrates how to create a copy of the existing global Broker settings using `clone_global_settings`. This allows for modifications to specific settings without affecting the main configuration, useful for testing or minor adjustments.

```Python
from broker.helpers import clone_global_settings

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

# Now you can modify the local_settings object without affecting the global one.
local_settings.ANSIBLETOWER.BASE_URL = "https://tower.example.org"
```

--------------------------------

### Configure Docker Container Provider

Source: https://github.com/satelliteqe/broker/wiki/Configuration

Defines two instances for the Container provider: 'docker' (default) and 'remote'. It specifies connection details like username, password, and host for the container runtime. The 'runtime' setting determines whether to use 'docker' or 'podman'.

```yaml
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
```

--------------------------------

### Checkin VM or Container by Hostname

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Returns a VM or container to its provider using its fully qualified domain name.

```bash
broker checkin my.host.fqdn.com
```

--------------------------------

### Sync Broker Inventory from Provider

Source: https://github.com/satelliteqe/broker/wiki/CLI-Usage

Synchronizes Broker's local inventory with a specified provider. This ensures the local inventory reflects the current state of resources on the provider.

```bash
broker inventory --sync AnsibleTower
```

--------------------------------

### Simplified AnsibleTower Provider Settings

Source: https://github.com/satelliteqe/broker/wiki/Configuration

Shows a simplified configuration for the AnsibleTower provider by removing the 'instances' nesting and placing provider-specific settings at the top level. This includes connection details like base URL, username, password, and workflow configurations.

```yaml
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 Logging Configuration

Source: https://github.com/satelliteqe/broker/wiki/Configuration

Configures the logging levels for both console and file output in Broker. Supported levels include trace, debug, info, warning, and error.

```yaml
logging:
    console_level: info
    file_level: debug
```

--------------------------------

### Output Inventory Command to File

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Executes the inventory command and saves the machine-processable output to a JSON file.

```bash
broker --output-file inventory.json inventory
```

--------------------------------

### SSH Key Copy Command for Remote Container Provider

Source: https://github.com/satelliteqe/broker/wiki/Configuration

Demonstrates the command to copy the local user's SSH public key to a remote host, which is necessary for authenticating the 'remote' Container provider when executing Broker.

```bash
[user1@localsystem]$ ssh-copy-id root@docker-host.example.com
```

--------------------------------

### Sync Broker Inventory for Specific Instance

Source: https://github.com/satelliteqe/broker/wiki/CLI-Usage

Synchronizes Broker's inventory for a specific instance from a supported provider, such as a container. This provides granular control over inventory updates.

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

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

--------------------------------

### Migrate Broker Configuration

Source: https://github.com/satelliteqe/broker/wiki/Configuration

Migrates an old broker configuration to the current version. It can also force migrations for a specific version to run.

```bash
broker config migrate
broker config migrate --force-version 0.6.0
```

--------------------------------

### Set Broker Directory Environment Variable

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Sets the BROKER_DIRECTORY environment variable to specify a custom location for Broker's configuration files, overriding the default `~/.broker/`.

```Shell
export BROKER_DIRECTORY=/path/to/your/broker/config
```

--------------------------------

### Checkin VM/Container by Hostname or Index

Source: https://github.com/satelliteqe/broker/wiki/CLI-Usage

Returns a VM or container to its provider. This can be done using the local ID, hostname, or a range of indices. Containers checked in this way are deleted.

```bash
broker checkin my.host.fqdn.com
```

```bash
broker checkin 0
```

```bash
broker checkin 1 3 my.host.fqdn.com
```

--------------------------------

### Validate Broker Configuration

Source: https://github.com/satelliteqe/broker/wiki/Configuration

Validates high-level configuration chunks, including base settings, specific providers, provider instances, or all settings.

```bash
broker config validate
broker config validate AnsibleTower
broker config validate Container:ipv4_podman
broker config validate all
```

--------------------------------

### Custom Host Class Integration

Source: https://github.com/satelliteqe/broker/wiki/API-Usage

Demonstrates how to define a custom host class inheriting from Broker's Host and integrate it with the Broker context manager.

```Python
from broker import Broker
from broker.hosts import Host

class MyHost(Host):
   ...

with Broker(..., host_class=MyHost) as my_host:
    ...
```

--------------------------------

### AnsibleTower Provider Configuration

Source: https://github.com/satelliteqe/broker/wiki/Configuration

Configures the AnsibleTower provider for Broker, including instance details, authentication (username/password or token), inventory, and workflow settings.

```yaml
AnsibleTower:
    instances:
        production:
            base_url: "https://<ansible tower host>/"
            username: "<username>"
            password: "<plain text password>"
            inventory: "inventory name"
            default: True
        testing:
            base_url: "https://<ansible tower host>/"
            username: "<username>"
            password: "<plain text password>"
            inventory: "inventory name"
    release_workflow: "remove-vm"
    extend_workflow: "extend-vm"
    new_expire_time: "+172800"
    workflow_timeout: 3600
    results_limit: 50
```

--------------------------------

### Broker Config View

Source: https://github.com/satelliteqe/broker/wiki/Version-Updates

Allows users to view their broker configuration. When no specific chunk is provided, it displays the entire configuration. If a configuration chunk is specified (e.g., 'Container' or 'Container.instances.remote'), it displays only that particular chunk.

```Bash
broker config view

broker config view Container

broker config view Container.instances.remote
```

--------------------------------

### Duplicate VM/Container

Source: https://github.com/satelliteqe/broker/wiki/CLI-Usage

Duplicates an existing VM or container that has already been checked out by Broker. This command allows specifying the source VM by its index, hostname, or a range of indices.

```bash
broker duplicate my.awesome.vm.com
```

```bash
broker duplicate 0
```

```bash
broker duplicate 1 3
```

```bash
broker duplicate 0 --count 2
```

--------------------------------

### Sync Broker Inventory for Specific User

Source: https://github.com/satelliteqe/broker/wiki/CLI-Usage

Synchronizes Broker's inventory for a specific user from a supported provider. This allows for targeted inventory updates.

```bash
broker inventory --sync AnsibleTower:<username>
```

--------------------------------

### Broker Config Edit

Source: https://github.com/satelliteqe/broker/wiki/Version-Updates

Enables users to edit their broker configuration. Without any arguments, it opens the entire configuration file for editing. With a valid configuration chunk, it allows editing of that specific chunk.

```Bash
broker config edit

broker config edit AnsibleTower
```

--------------------------------

### Run Checkout in Background

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Executes the checkout command in the background, preventing logs from going to stderr.

```bash
broker checkout --background --nick rhel7
```

--------------------------------

### Broker SSH Connection Settings

Source: https://github.com/satelliteqe/broker/wiki/Configuration

Sets default SSH connection parameters for Broker's interaction with hosts. Includes backend selection, username, password, and IPv6/IPv4 fallback options.

```yaml
ssh:
  backend: hussh
  host_username: root
  host_password: toor
  host_ipv6: false
  host_ipv4_fallback: true
```

--------------------------------

### Execute SSH Command and Check Results

Source: https://github.com/satelliteqe/broker/wiki/API-Usage

Illustrates executing an SSH command on a host object and inspecting the Results object for status and output.

```Python
result = rhel7_host.execute("rpm -qa")
assert result.status == 0
assert "my-package" in result.stdout
```

--------------------------------

### List Broker Nicks

Source: https://github.com/satelliteqe/broker/wiki/Configuration

Displays a list of active user nicks or details of a specific nick. Viewing a specific nick is an alias for viewing a nested chunk.

```bash
broker config nicks
broker config nick sat617
```

--------------------------------

### Set Broker Configuration Value

Source: https://github.com/satelliteqe/broker/wiki/Configuration

Sets the value of a single configuration entry or copies the contents of a file into a configuration chunk. Supports setting values directly or from local files and remote URLs.

```bash
broker config set Container.host_name test.host
broker config set Foreman foreman_settings.yaml
broker config set Container.instances.local local_podman.json
```

--------------------------------

### Restore Broker Configuration

Source: https://github.com/satelliteqe/broker/wiki/Configuration

Restores the broker configuration from the most recent backup. This command is useful for undoing recent 'edit' or 'set' operations.

```bash
broker config restore
```

--------------------------------

### Edit Broker Configuration

Source: https://github.com/satelliteqe/broker/wiki/Configuration

Allows editing of the entire broker configuration or specific chunks. It supports editing a specified chunk using its key.

```bash
broker config edit
broker config edit AnsibleTower
broker config edit Container.instances.remote
```

--------------------------------

### Run Broker Actions in Background

Source: https://github.com/satelliteqe/broker/wiki/CLI-Usage

Certain Broker actions like 'checkout', 'checkin', 'duplicate', and 'execute' can be run in the background. This spins up a new Broker process and logs to a file instead of stderr. Note that background mode may interfere with stdout for 'execute' actions.

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

--------------------------------

### Extend VM Lease Time

Source: https://github.com/satelliteqe/broker/blob/master/README.md

Extends the lease time for a VM, supporting various identifiers like ID, hostname, or VM name.

```bash
broker extend 0
```

```bash
broker extend hostname
```

```bash
broker extend vmname
```

```bash
broker extend --all
```

--------------------------------

### Extend VM Lease Time

Source: https://github.com/satelliteqe/broker/wiki/CLI-Usage

Extends the lease time for a VM managed by Broker, provided the underlying provider supports this functionality. This can be done for specific VMs by index or hostname, or for all VMs.

```bash
broker extend 0
```

```bash
broker extend hostname
```

```bash
broker extend vmname
```

```bash
broker extend --all
```

--------------------------------

### Filter by Hostname Range

Source: https://github.com/satelliteqe/broker/wiki/Filters

This filter selects a range of hosts from the inventory, specifically from the 4th to the 7th host (inclusive). It demonstrates Python's list slicing.

```Shell
--filter '@inv[3:7]'
```

--------------------------------

### Filter by Last Host in Inventory

Source: https://github.com/satelliteqe/broker/wiki/Filters

This filter selects the last host from the inventory list. It uses Python's list indexing with -1 to access the final element.

```Shell
--filter '@inv[-1]'
```

--------------------------------

### Filter by Hostname using Python Expression

Source: https://github.com/satelliteqe/broker/wiki/Filters

This filter checks if the string 'test' is present within the hostname property of the inventory. It utilizes Python's 'in' operator for substring matching.

```Shell
--filter '"test" in @inv.hostname'
```

--------------------------------

### Filter Results by String Presence

Source: https://github.com/satelliteqe/broker/wiki/Filters

This filter checks if the string 'test' exists within each item in the results list. It applies the 'in' operator to the '@res' list.

```Shell
--results-filter '"test" in @res'
```

--------------------------------

### Filter Results by Last Item

Source: https://github.com/satelliteqe/broker/wiki/Filters

This filter returns only the last item from the results list. It uses Python's list indexing with -1.

```Shell
--results-filter '@res[-1]'
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.