Module sysbot.plugins.ansible
Ansible Plugin Module
This module provides functionality for loading and parsing Ansible inventory files. Supports both INI and YAML inventory formats with automatic format detection. Also provides functionality for executing Ansible playbooks and roles using ansible-runner.
Classes
class Ansible-
Ansible plugin for managing Ansible inventory data and executing playbooks and roles.
This class provides methods to load Ansible inventory files in both INI and YAML formats, execute Ansible playbooks and roles using ansible-runner, and optionally store results in the SysBot secrets cache.
Ancestors
Methods
def inventory(self, file: str, key: str = None) ‑> dict-
Load Ansible inventory file and optionally store in secrets cache.
Supports both INI and YAML inventory formats. Automatically detects format based on file extension (.ini, .yml, .yaml). Files without extensions are treated as INI format.
Args
file- Path to the Ansible inventory file to load.
key- Optional key to store the data in secrets cache. If provided, returns "Imported", otherwise returns the data.
Returns
Dictionary containing parsed Ansible inventory if key is None, otherwise returns "Imported" string after storing in cache.
The returned dictionary has the following structure: { "groups": { "group_name": { "hosts": { "host_name": { "ansible_host": "…", "ansible_user": "…", … } }, "vars": {…}, "children": […] } } }
Raises
FileNotFoundError- If the inventory file does not exist.
RuntimeError- If there's an error reading or parsing the inventory file.
def playbook(self,
playbook: str,
inventory: str = None,
limit: str = None,
tags: str = None,
skip_tags: str = None,
extra_vars: dict = None,
check: bool = False,
diff: bool = False,
verbose: int = 0,
forks: int = None,
**kwargs) ‑> dict-
Execute an Ansible playbook using ansible-runner.
This method uses the official ansible-runner library to execute playbooks, providing better integration, event handling, and artifact management.
Args
playbook- Path to the Ansible playbook file to execute.
inventory- Path to the inventory file, comma-separated host list, or dictionary/list representing inventory structure.
limit- Limit execution to specific hosts or groups.
tags- Only run plays and tasks tagged with these values (comma-separated).
skip_tags- Skip plays and tasks tagged with these values (comma-separated).
extra_vars- Dictionary of extra variables to pass to the playbook.
check- Run in check mode (dry-run), don't make any changes.
diff- Show differences when changing small files and templates.
verbose- Increase verbosity level (0-4, where 0 is default).
forks- Control Ansible parallel concurrency.
**kwargs- Additional ansible-runner options (e.g., timeout, quiet).
Returns
Dictionary containing playbook execution results: { "success": bool, "status": str (one of: successful, failed, timeout, canceled), "rc": int (return code), "stats": dict (playbook statistics per host), "stdout": str (captured output) }
Raises
FileNotFoundError- If the playbook file does not exist.
ValueError- If invalid parameters are provided.
RuntimeError- If there's an error executing the playbook.
Example
result = ansible.playbook( playbook="site.yml", inventory="inventory.ini", limit="webservers", extra_vars={"version": "1.2.3"}, check=True )
def role(self,
role: str,
hosts: str,
inventory: str = None,
extra_vars: dict = None,
check: bool = False,
diff: bool = False,
verbose: int = 0,
forks: int = None,
**kwargs) ‑> dict-
Execute an Ansible role on specific hosts using ansible-runner.
This method dynamically creates a playbook that applies the specified role to the given hosts, then executes it using ansible-runner.
Args
role- Name of the Ansible role to execute. Can be a role name from roles directory or a fully qualified role name (e.g., namespace.rolename).
hosts- Target hosts or groups to execute the role on. Can be a specific host, a group name, or a pattern (e.g., "webservers", "web*.example.com").
inventory- Path to the inventory file, comma-separated host list, or dictionary/list representing inventory structure.
extra_vars- Dictionary of extra variables to pass to the role.
check- Run in check mode (dry-run), don't make any changes.
diff- Show differences when changing small files and templates.
verbose- Increase verbosity level (0-4, where 0 is default).
forks- Control Ansible parallel concurrency.
**kwargs- Additional ansible-runner options (e.g., timeout, quiet).
Returns
Dictionary containing role execution results: { "success": bool, "status": str (one of: successful, failed, timeout, canceled), "rc": int (return code), "stats": dict (playbook statistics per host), "stdout": str (captured output) }
Raises
ValueError- If invalid parameters are provided.
RuntimeError- If there's an error executing the role.
Example
result = ansible.role( role="common", hosts="webservers", inventory="inventory.ini", extra_vars={"ntp_server": "ntp.example.com"}, check=True )