Ansible
Runs Ansible playbooks and ad-hoc commands against remote hosts via the ansible-playbook and ansible CLIs. An agent can run a playbook (with extra vars, host limits, and dry-run/--check mode), run a single ad-hoc module, ping hosts to verify connectivity, and gather system facts.
This is the agent-tool connector for Ansible. There is also a separate
ansibleworkflow node that runsansible-playbookdirectly as a workflow step (not as an agent tool) — use that for a fixed deploy/provisioning step in a pipeline, and this connector when an agent needs to decide when and how to run Ansible.
Add to an agent node's tools array with _node_type: "tool-ansible". See Connector Reference — How connectors are used.
Authentication
| Field | Required | Description |
|---|---|---|
inventory | No | Inventory content (INI/YAML) or a path to an inventory file. If the value is not an existing file path, it's treated as inventory content and written to a temporary file before each command (-i <file>). |
private_key | No | PEM-encoded SSH private key content. Written to a temporary file (mode 0600) and passed via --private-key for the duration of each call. |
become_password | No | Privilege-escalation (sudo) password. Currently read but not yet wired into any command's arguments. |
vault_password | No | Ansible Vault password. Currently read but not yet wired into any command's arguments. |
{
"name": "ansible",
"_node_type": "tool-ansible",
"inventory": "[web]\nweb1.example.com\nweb2.example.com ansible_user=deploy\n",
"private_key": "{{ secret.ANSIBLE_SSH_KEY }}"
}
Tools
ansible_playbook
Run an Ansible playbook on remote hosts. Provide the playbook as YAML content.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
playbook | string | Yes | Ansible playbook YAML content |
extra_vars | string | No | Extra variables as JSON string, e.g. {"env":"prod"} |
hosts | string | No | Limit to specific hosts or groups |
dry_run | boolean | No | Run with --check (no changes) |
Returns: The combined stdout+stderr of ansible-playbook <file> [-e <extra_vars>] [-l <hosts>] [--check]. If the command exits non-zero, returns playbook error: <err>\n<output> instead of failing the tool call.
ansible_adhoc
Run an Ansible ad-hoc command (single module) on remote hosts.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
hosts | string | Yes | Host pattern or group name |
module | string | Yes | Ansible module name e.g. command shell copy |
args | string | No | Module arguments e.g. uptime or src=/tmp/f dest=/opt/f |
become | boolean | No | Run with privilege escalation (sudo) |
Returns: The combined stdout+stderr of ansible <hosts> -m <module> [-a <args>] [--become]. If the command exits non-zero, returns adhoc error: <err>\n<output> instead of failing the tool call.
ansible_ping
Ping hosts to verify Ansible connectivity. Returns SUCCESS or FAILED per host.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
hosts | string | No | Host pattern to ping (default: all) |
Returns: The combined stdout+stderr of ansible <hosts> -m ping. If the command exits non-zero, returns ping error: <err>\n<output> instead of failing the tool call.
ansible_gather_facts
Gather system facts from remote hosts (OS, memory, CPU, network interfaces).
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
hosts | string | Yes | Host pattern to gather facts from |
Returns: The combined stdout+stderr of ansible <hosts> -m setup -a "filter=ansible_distribution,ansible_memtotal_mb,ansible_processor_count,ansible_default_ipv4". If the command exits non-zero, returns facts error: <err>\n<output> instead of failing the tool call.