0
# Ansible Runner
1

2
Ansible Runner is a comprehensive tool and Python library that provides a stable, consistent interface abstraction to Ansible automation platform. It functions as a standalone command-line tool, container image interface, and importable Python module, designed to facilitate seamless integration with Ansible in various deployment scenarios. The library offers process and container isolation runtime capabilities, supports programmatic execution of Ansible playbooks and ad-hoc commands, provides comprehensive event streaming and callback mechanisms for monitoring execution progress, and includes advanced features like artifact collection, job isolation, and result processing.
3

4
## Package Information
5

6
- **Package Name**: ansible-runner
7
- **Language**: Python
8
- **Installation**: `pip install ansible-runner`
9

10
## Core Imports
11

12
```python
13
import ansible_runner
14
```
15

16
Common imports for specific functionality:
17

18
```python
19
from ansible_runner import run, run_async, run_command
20
from ansible_runner import Runner, RunnerConfig
21
from ansible_runner import AnsibleRunnerException, ConfigurationError
22
```
23

24
## Basic Usage
25

26
```python
27
import ansible_runner
28

29
# Simple playbook execution
30
result = ansible_runner.run(
31
    private_data_dir='/tmp/demo',
32
    playbook='playbook.yml',
33
    inventory='inventory',
34
    extravars={'key': 'value'}
35
)
36

37
print(f"Status: {result.status}")
38
print(f"Return code: {result.rc}")
39

40
# Process events
41
for event in result.events:
42
    if event['event'] == 'playbook_on_play_start':
43
        print(f"Starting play: {event['event_data']['play']}")
44

45
# Simple command execution
46
result = ansible_runner.run_command(
47
    executable_cmd='ansible-playbook',
48
    cmdline_args=['playbook.yml', '-i', 'inventory'],
49
    private_data_dir='/tmp/demo'
50
)
51

52
# Async execution with callbacks
53
def status_handler(data, runner_config):
54
    print(f"Status: {data['status']}")
55

56
def event_handler(data):
57
    print(f"Event: {data['event']}")
58
    return True  # Continue processing
59

60
result = ansible_runner.run_async(
61
    private_data_dir='/tmp/demo',
62
    playbook='playbook.yml',
63
    status_handler=status_handler,
64
    event_handler=event_handler
65
)
66

67
# Wait for completion
68
result.wait()
69
```
70

71
## Architecture
72

73
Ansible Runner provides multiple layers of abstraction:
74

75
- **Interface Layer**: High-level functions (`run`, `run_async`, `run_command`) for common use cases
76
- **Runner Class**: Core execution engine with event handling and process management
77
- **Configuration Classes**: Specialized configuration for different execution modes (playbooks, commands, inventory operations)
78
- **Streaming Components**: Support for distributed execution and real-time event processing
79
- **Isolation Support**: Container and process isolation capabilities for secure execution
80

81
This architecture enables flexible deployment patterns from simple script integration to complex orchestration platforms with distributed execution capabilities.
82

83
## Capabilities
84

85
### Playbook Execution
86

87
Execute Ansible playbooks with comprehensive configuration options, event handling, and artifact collection. Supports both synchronous and asynchronous execution modes with full callback support.
88

89
```python { .api }
90
def run(
91
    private_data_dir: str = None,
92
    playbook: str = None,
93
    inventory: str = None,
94
    **kwargs
95
) -> Runner: ...
96

97
def run_async(
98
    private_data_dir: str = None,
99
    playbook: str = None,
100
    inventory: str = None,
101
    **kwargs
102
) -> Runner: ...
103
```
104

105
[Playbook Execution](./playbook-execution.md)
106

107
### Command Execution
108

109
Execute Ansible command-line tools (ansible-playbook, ansible, ansible-inventory, etc.) programmatically with full argument support and output capture.
110

111
```python { .api }
112
def run_command(
113
    executable_cmd: str,
114
    cmdline_args: list = None,
115
    **kwargs
116
) -> Runner: ...
117

118
def run_command_async(
119
    executable_cmd: str,
120
    cmdline_args: list = None,
121
    **kwargs
122
) -> Runner: ...
123
```
124

125
[Command Execution](./command-execution.md)
126

127
### Plugin and Role Management
128

129
Discover, document, and manage Ansible plugins and roles programmatically. Provides access to plugin documentation, role specifications, and inventory operations.
130

131
```python { .api }
132
def get_plugin_docs(
133
    plugin_names: list,
134
    plugin_type: str = None,
135
    response_format: str = None,
136
    **kwargs
137
) -> Runner: ...
138

139
def get_role_list(
140
    collection: str = None,
141
    playbook_dir: str = None,
142
    **kwargs
143
) -> Runner: ...
144

145
def get_role_argspec(
146
    role: str,
147
    collection: str = None,
148
    **kwargs
149
) -> Runner: ...
150
```
151

152
[Plugin and Role Management](./plugin-role-management.md)
153

154
### Configuration and Runner Classes
155

156
Core classes for advanced use cases requiring fine-grained control over execution parameters, event handling, and process management.
157

158
```python { .api }
159
class Runner:
160
    def __init__(
161
        self,
162
        config,
163
        cancel_callback=None,
164
        event_handler=None,
165
        **kwargs
166
    ): ...
167

168
class RunnerConfig:
169
    def __init__(self, **kwargs): ...
170
```
171

172
[Configuration and Runner Classes](./configuration-runner.md)
173

174
### Streaming and Distributed Execution
175

176
Components for distributed execution across multiple processes or containers with real-time event streaming and coordination.
177

178
```python { .api }
179
class Transmitter:
180
    def __init__(self, private_data_dir: str, **kwargs): ...
181

182
class Worker:
183
    def __init__(self, private_data_dir: str, **kwargs): ...
184

185
class Processor:
186
    def __init__(self, private_data_dir: str, **kwargs): ...
187
```
188

189
[Streaming and Distributed Execution](./streaming-distributed.md)
190

191
### Utilities and Cleanup
192

193
Helper functions for artifact management, cleanup operations, output handling, and system integration.
194

195
```python { .api }
196
def cleanup_folder(folder: str) -> bool: ...
197
def register_for_cleanup(folder: str) -> None: ...
198

199
class Bunch:
200
    def __init__(self, **kwargs): ...
201
```
202

203
[Utilities and Cleanup](./utilities-cleanup.md)
204

205
## Types
206

207
```python { .api }
208
class AnsibleRunnerException(Exception):
209
    """Generic Runner Error"""
210

211
class ConfigurationError(AnsibleRunnerException):
212
    """Misconfiguration of Runner"""
213

214
class CallbackError(AnsibleRunnerException):
215
    """Exception occurred in Callback"""
216
```