0
# Playbook Execution
1

2
Execute Ansible playbooks with comprehensive configuration options, event handling, and artifact collection. Supports both synchronous and asynchronous execution modes with full callback support for monitoring progress and handling results.
3

4
## Capabilities
5

6
### Synchronous Playbook Execution
7

8
Execute a playbook and wait for completion. Returns a Runner instance with results, artifacts, and event data.
9

10
```python { .api }
11
def run(
12
    private_data_dir: str = None,
13
    playbook: str = None,
14
    inventory: str = None,
15
    roles_path: str = None,
16
    verbosity: int = None,
17
    quiet: bool = False,
18
    rotate_artifacts: int = 0,
19
    artifact_dir: str = None,
20
    project_dir: str = None,
21
    ident: str = None,
22
    json_mode: bool = False,
23
    check: bool = False,
24
    tags: str = None,
25
    skip_tags: str = None,
26
    limit: str = None,
27
    module_path: str = None,
28
    forks: int = None,
29
    vault_ids: list = None,
30
    vault_password_file: str = None,
31
    extravars: dict = None,
32
    suppress_ansible_output: bool = False,
33
    ssh_key: str = None,
34
    process_isolation: bool = False,
35
    process_isolation_executable: str = None,
36
    process_isolation_path: str = None,
37
    process_isolation_hide_paths: list = None,
38
    process_isolation_show_paths: list = None,
39
    process_isolation_ro_paths: list = None,
40
    container_image: str = None,
41
    container_volume_mounts: list = None,
42
    container_options: list = None,
43
    directory_isolation_base_path: str = None,
44
    envvars: dict = None,
45
    passwords: dict = None,
46
    timeout: int = None,
47
    job_timeout: int = None,
48
    idle_timeout: int = None,
49
    pexpect_timeout: int = None,
50
    pexpect_use_poll: bool = True,
51
    runner_mode: str = 'pexpect',
52
    host_cwd: str = None,
53
    fact_cache: str = None,
54
    fact_cache_type: str = None,
55
    project: str = None,
56
    cmdline: str = None,
57
    start_at_task: str = None,
58
    step: bool = False,
59
    cancel_callback: callable = None,
60
    finished_callback: callable = None,
61
    status_handler: callable = None,
62
    event_handler: callable = None,
63
    artifacts_handler: callable = None,
64
    ignore_logging: bool = True,
65
    debug: bool = None,
66
    logfile: str = None
67
) -> Runner
68
```
69

70
Parameters:
71
- **private_data_dir** (str): Directory containing playbook files and artifacts
72
- **playbook** (str): Path to playbook file relative to project_dir
73
- **inventory** (str): Path to inventory file or directory
74
- **extravars** (dict): Extra variables to pass to the playbook
75
- **verbosity** (int): Ansible verbosity level (0-4)
76
- **timeout** (int): Maximum execution time in seconds
77
- **event_handler** (callable): Function to handle playbook events
78
- **status_handler** (callable): Function to handle status changes
79
- **process_isolation** (bool): Enable process isolation using containers
80

81
Usage example:
82

83
```python
84
import ansible_runner
85

86
# Basic playbook execution
87
result = ansible_runner.run(
88
    private_data_dir='/path/to/private_data',
89
    playbook='site.yml',
90
    inventory='hosts',
91
    extravars={'env': 'production'}
92
)
93

94
# With event handling
95
def handle_event(event):
96
    if event['event'] == 'playbook_on_task_start':
97
        print(f"Starting task: {event['event_data']['task']}")
98
    return True
99

100
result = ansible_runner.run(
101
    private_data_dir='/path/to/private_data',
102
    playbook='site.yml',
103
    inventory='hosts',
104
    event_handler=handle_event,
105
    verbosity=2
106
)
107

108
print(f"Playbook finished with status: {result.status}")
109
print(f"Return code: {result.rc}")
110
```
111

112
### Asynchronous Playbook Execution
113

114
Execute a playbook asynchronously, allowing for non-blocking execution with callback-based progress monitoring.
115

116
```python { .api }
117
def run_async(
118
    private_data_dir: str = None,
119
    playbook: str = None,
120
    inventory: str = None,
121
    roles_path: str = None,
122
    verbosity: int = None,
123
    quiet: bool = False,
124
    rotate_artifacts: int = 0,
125
    artifact_dir: str = None,
126
    project_dir: str = None,
127
    ident: str = None,
128
    json_mode: bool = False,
129
    check: bool = False,
130
    tags: str = None,
131
    skip_tags: str = None,
132
    limit: str = None,
133
    module_path: str = None,
134
    forks: int = None,
135
    vault_ids: list = None,
136
    vault_password_file: str = None,
137
    extravars: dict = None,
138
    suppress_ansible_output: bool = False,
139
    ssh_key: str = None,
140
    process_isolation: bool = False,
141
    process_isolation_executable: str = None,
142
    process_isolation_path: str = None,
143
    process_isolation_hide_paths: list = None,
144
    process_isolation_show_paths: list = None,
145
    process_isolation_ro_paths: list = None,
146
    container_image: str = None,
147
    container_volume_mounts: list = None,
148
    container_options: list = None,
149
    directory_isolation_base_path: str = None,
150
    envvars: dict = None,
151
    passwords: dict = None,
152
    timeout: int = None,
153
    job_timeout: int = None,
154
    idle_timeout: int = None,
155
    pexpect_timeout: int = None,
156
    pexpect_use_poll: bool = True,
157
    runner_mode: str = 'pexpect',
158
    host_cwd: str = None,
159
    fact_cache: str = None,
160
    fact_cache_type: str = None,
161
    project: str = None,
162
    cmdline: str = None,
163
    start_at_task: str = None,
164
    step: bool = False,
165
    cancel_callback: callable = None,
166
    finished_callback: callable = None,
167
    status_handler: callable = None,
168
    event_handler: callable = None,
169
    artifacts_handler: callable = None,
170
    ignore_logging: bool = True,
171
    debug: bool = None,
172
    logfile: str = None
173
) -> Runner
174
```
175

176
Usage example:
177

178
```python
179
import ansible_runner
180
import time
181

182
def status_callback(data, runner_config):
183
    print(f"Status changed to: {data['status']}")
184

185
def finished_callback(runner):
186
    print(f"Playbook completed with status: {runner.status}")
187

188
# Start async execution
189
runner = ansible_runner.run_async(
190
    private_data_dir='/path/to/private_data',
191
    playbook='site.yml',
192
    inventory='hosts',
193
    status_handler=status_callback,
194
    finished_callback=finished_callback
195
)
196

197
# Do other work while playbook runs
198
while runner.status not in ['successful', 'failed', 'error', 'canceled']:
199
    print("Playbook still running...")
200
    time.sleep(1)
201

202
print(f"Final status: {runner.status}")
203
```
204

205
## Common Patterns
206

207
### Directory Structure
208

209
Ansible Runner expects a specific directory structure for `private_data_dir`:
210

211
```
212
private_data_dir/
213
├── project/          # Playbooks and related files
214
│   ├── site.yml
215
│   └── roles/
216
├── inventory/        # Inventory files
217
│   └── hosts
218
├── artifacts/        # Output artifacts (created automatically)
219
├── env/             # Environment files
220
│   ├── extravars    # Extra variables (YAML)
221
│   ├── passwords    # Vault and connection passwords
222
│   └── ssh_key      # SSH private key
223
└── tmp/             # Temporary files
224
```
225

226
### Event Handling
227

228
Event handlers receive detailed information about playbook execution:
229

230
```python
231
def comprehensive_event_handler(event):
232
    event_type = event.get('event')
233
    
234
    if event_type == 'playbook_on_start':
235
        print("Playbook started")
236
    elif event_type == 'playbook_on_play_start':
237
        play_name = event['event_data']['play']
238
        print(f"Starting play: {play_name}")
239
    elif event_type == 'playbook_on_task_start':
240
        task_name = event['event_data']['task']
241
        print(f"Starting task: {task_name}")
242
    elif event_type == 'runner_on_ok':
243
        host = event['event_data']['host']
244
        task_name = event['event_data']['task']
245
        print(f"Task '{task_name}' succeeded on {host}")
246
    elif event_type == 'runner_on_failed':
247
        host = event['event_data']['host']
248
        print(f"Task failed on {host}")
249
        
250
    return True  # Continue processing events
251

252
result = ansible_runner.run(
253
    private_data_dir='/path/to/private_data',
254
    playbook='site.yml',
255
    event_handler=comprehensive_event_handler
256
)
257
```
258

259
### Process Isolation
260

261
Enable container-based execution for security and reproducibility:
262

263
```python
264
result = ansible_runner.run(
265
    private_data_dir='/path/to/private_data',
266
    playbook='site.yml',
267
    process_isolation=True,
268
    process_isolation_executable='podman',
269
    container_image='quay.io/ansible/ansible-runner:latest',
270
    container_volume_mounts=['/host/path:/container/path:Z'],
271
    container_options=['--network=host']
272
)
273
```