0
# Plugin and Role Management
1

2
Discover, document, and manage Ansible plugins and roles programmatically. Provides access to plugin documentation, role specifications, inventory operations, and Ansible configuration management through a consistent programmatic interface.
3

4
## Capabilities
5

6
### Plugin Documentation
7

8
Retrieve documentation for Ansible plugins including modules, lookup plugins, filter plugins, and other plugin types.
9

10
```python { .api }
11
def get_plugin_docs(
12
    plugin_names: list,
13
    plugin_type: str = None,
14
    response_format: str = None,
15
    snippet: bool = False,
16
    playbook_dir: str = None,
17
    module_path: str = None,
18
    private_data_dir: str = None,
19
    artifact_dir: str = None,
20
    ident: str = None,
21
    rotate_artifacts: int = 0,
22
    timeout: int = None,
23
    process_isolation: bool = False,
24
    process_isolation_executable: str = None,
25
    container_image: str = None,
26
    envvars: dict = None,
27
    **kwargs
28
) -> Runner
29
```
30

31
Parameters:
32
- **plugin_names** (list): List of plugin names to get documentation for
33
- **plugin_type** (str): Type of plugin ('module', 'lookup', 'filter', 'test', etc.)
34
- **response_format** (str): Output format ('json', 'yaml', 'text')
35
- **snippet** (bool): Return only brief documentation snippets
36
- **playbook_dir** (str): Directory containing playbooks and collections
37
- **module_path** (str): Additional paths to search for modules
38

39
Usage examples:
40

41
```python
42
import ansible_runner
43

44
# Get documentation for specific modules
45
result = ansible_runner.get_plugin_docs(
46
    plugin_names=['copy', 'template', 'service'],
47
    plugin_type='module',
48
    response_format='json'
49
)
50

51
# Get brief snippets for quick reference
52
result = ansible_runner.get_plugin_docs(
53
    plugin_names=['file', 'lineinfile'],
54
    plugin_type='module',
55
    snippet=True,
56
    response_format='text'
57
)
58

59
# Get lookup plugin documentation
60
result = ansible_runner.get_plugin_docs(
61
    plugin_names=['env', 'file', 'template'],
62
    plugin_type='lookup',
63
    response_format='yaml'
64
)
65
```
66

67
### Asynchronous Plugin Documentation
68

69
```python { .api }
70
def get_plugin_docs_async(
71
    plugin_names: list,
72
    plugin_type: str = None,
73
    response_format: str = None,
74
    snippet: bool = False,
75
    playbook_dir: str = None,
76
    module_path: str = None,
77
    private_data_dir: str = None,
78
    artifact_dir: str = None,
79
    ident: str = None,
80
    rotate_artifacts: int = 0,
81
    timeout: int = None,
82
    process_isolation: bool = False,
83
    process_isolation_executable: str = None,
84
    container_image: str = None,
85
    envvars: dict = None,
86
    **kwargs
87
) -> Runner
88
```
89

90
Usage example:
91

92
```python
93
# Async plugin documentation retrieval
94
runner = ansible_runner.get_plugin_docs_async(
95
    plugin_names=['yum', 'apt', 'package'],
96
    plugin_type='module',
97
    response_format='json'
98
)
99

100
# Wait for completion
101
while runner.status in ['pending', 'running']:
102
    time.sleep(0.5)
103

104
if runner.status == 'successful':
105
    print("Plugin documentation retrieved successfully")
106
```
107

108
### Plugin Listing
109

110
List available Ansible plugins by type or search criteria.
111

112
```python { .api }
113
def get_plugin_list(
114
    list_files: str = None,
115
    response_format: str = None,
116
    plugin_type: str = None,
117
    playbook_dir: str = None,
118
    module_path: str = None,
119
    private_data_dir: str = None,
120
    artifact_dir: str = None,
121
    ident: str = None,
122
    rotate_artifacts: int = 0,
123
    timeout: int = None,
124
    process_isolation: bool = False,
125
    process_isolation_executable: str = None,
126
    container_image: str = None,
127
    envvars: dict = None,
128
    **kwargs
129
) -> Runner
130
```
131

132
Parameters:
133
- **list_files** (str): File containing list of plugins to query
134
- **plugin_type** (str): Type of plugins to list ('module', 'lookup', 'filter', etc.)
135
- **response_format** (str): Output format ('json', 'yaml', 'text')
136

137
Usage examples:
138

139
```python
140
# List all available modules
141
result = ansible_runner.get_plugin_list(
142
    plugin_type='module',
143
    response_format='json'
144
)
145

146
# List lookup plugins
147
result = ansible_runner.get_plugin_list(
148
    plugin_type='lookup',
149
    response_format='text'
150
)
151

152
# List all plugin types
153
result = ansible_runner.get_plugin_list(
154
    response_format='yaml'
155
)
156
```
157

158
### Role Listing
159

160
List available Ansible roles from collections or local directories.
161

162
```python { .api }
163
def get_role_list(
164
    collection: str = None,
165
    playbook_dir: str = None,
166
    private_data_dir: str = None,
167
    artifact_dir: str = None,
168
    ident: str = None,
169
    rotate_artifacts: int = 0,
170
    timeout: int = None,
171
    process_isolation: bool = False,
172
    process_isolation_executable: str = None,
173
    container_image: str = None,
174
    envvars: dict = None,
175
    **kwargs
176
) -> Runner
177
```
178

179
Parameters:
180
- **collection** (str): Specific collection to list roles from
181
- **playbook_dir** (str): Directory containing roles and collections
182

183
Usage examples:
184

185
```python
186
# List all available roles
187
result = ansible_runner.get_role_list()
188

189
# List roles from specific collection
190
result = ansible_runner.get_role_list(
191
    collection='community.general'
192
)
193

194
# List roles from specific directory
195
result = ansible_runner.get_role_list(
196
    playbook_dir='/path/to/ansible/project'
197
)
198
```
199

200
### Role Argument Specification
201

202
Get detailed argument specifications for Ansible roles.
203

204
```python { .api }
205
def get_role_argspec(
206
    role: str,
207
    collection: str = None,
208
    playbook_dir: str = None,
209
    private_data_dir: str = None,
210
    artifact_dir: str = None,
211
    ident: str = None,
212
    rotate_artifacts: int = 0,
213
    timeout: int = None,
214
    process_isolation: bool = False,
215
    process_isolation_executable: str = None,
216
    container_image: str = None,
217
    envvars: dict = None,
218
    **kwargs
219
) -> Runner
220
```
221

222
Parameters:
223
- **role** (str): Name of the role to get argument specification for
224
- **collection** (str): Collection containing the role
225
- **playbook_dir** (str): Directory containing the role
226

227
Usage examples:
228

229
```python
230
# Get argument spec for a role
231
result = ansible_runner.get_role_argspec(
232
    role='nginx'
233
)
234

235
# Get argument spec for role in collection
236
result = ansible_runner.get_role_argspec(
237
    role='apache',
238
    collection='community.general'
239
)
240

241
# Get argument spec with custom playbook directory
242
result = ansible_runner.get_role_argspec(
243
    role='custom_app',
244
    playbook_dir='/path/to/roles'
245
)
246
```
247

248
### Inventory Operations
249

250
Execute ansible-inventory commands for inventory management and inspection.
251

252
```python { .api }
253
def get_inventory(
254
    action: str,
255
    inventories: list,
256
    response_format: str = None,
257
    host: str = None,
258
    playbook_dir: str = None,
259
    private_data_dir: str = None,
260
    artifact_dir: str = None,
261
    ident: str = None,
262
    rotate_artifacts: int = 0,
263
    timeout: int = None,
264
    process_isolation: bool = False,
265
    process_isolation_executable: str = None,
266
    container_image: str = None,
267
    envvars: dict = None,
268
    **kwargs
269
) -> Runner
270
```
271

272
Parameters:
273
- **action** (str): Inventory action ('list', 'host', 'graph')
274
- **inventories** (list): List of inventory files or directories
275
- **response_format** (str): Output format ('json', 'yaml', 'text')
276
- **host** (str): Specific host to query (for 'host' action)
277

278
Usage examples:
279

280
```python
281
# List entire inventory
282
result = ansible_runner.get_inventory(
283
    action='list',
284
    inventories=['inventory/hosts'],
285
    response_format='json'
286
)
287

288
# Get information for specific host
289
result = ansible_runner.get_inventory(
290
    action='host',
291
    inventories=['inventory/hosts'],
292
    host='web01',
293
    response_format='json'
294
)
295

296
# Generate inventory graph
297
result = ansible_runner.get_inventory(
298
    action='graph',
299
    inventories=['inventory/hosts', 'inventory/groups'],
300
    response_format='text'
301
)
302
```
303

304
### Ansible Configuration
305

306
Get and manage Ansible configuration settings.
307

308
```python { .api }
309
def get_ansible_config(
310
    action: str,
311
    config_file: str = None,
312
    only_changed: bool = None,
313
    private_data_dir: str = None,
314
    artifact_dir: str = None,
315
    ident: str = None,
316
    rotate_artifacts: int = 0,
317
    timeout: int = None,
318
    process_isolation: bool = False,
319
    process_isolation_executable: str = None,
320
    container_image: str = None,
321
    envvars: dict = None,
322
    **kwargs
323
) -> Runner
324
```
325

326
Parameters:
327
- **action** (str): Configuration action ('list', 'dump', 'view')
328
- **config_file** (str): Specific configuration file to use
329
- **only_changed** (bool): Show only changed configuration values
330

331
Usage examples:
332

333
```python
334
# View current configuration
335
result = ansible_runner.get_ansible_config(
336
    action='view'
337
)
338

339
# Dump all configuration settings
340
result = ansible_runner.get_ansible_config(
341
    action='dump'
342
)
343

344
# List all available configuration options
345
result = ansible_runner.get_ansible_config(
346
    action='list'
347
)
348

349
# Show only changed settings
350
result = ansible_runner.get_ansible_config(
351
    action='dump',
352
    only_changed=True
353
)
354
```
355

356
## Common Patterns
357

358
### Plugin Discovery Workflow
359

360
```python
361
import ansible_runner
362

363
# 1. List available modules
364
modules_result = ansible_runner.get_plugin_list(
365
    plugin_type='module',
366
    response_format='json'
367
)
368

369
# 2. Get documentation for specific modules
370
if modules_result.status == 'successful':
371
    docs_result = ansible_runner.get_plugin_docs(
372
        plugin_names=['file', 'copy', 'template'],
373
        plugin_type='module',
374
        response_format='json'
375
    )
376

377
# 3. Get brief snippets for quick reference
378
snippets_result = ansible_runner.get_plugin_docs(
379
    plugin_names=['file', 'copy'],
380
    plugin_type='module',
381
    snippet=True,
382
    response_format='text'
383
)
384
```
385

386
### Role Management Workflow
387

388
```python
389
# 1. List all available roles
390
roles_result = ansible_runner.get_role_list()
391

392
# 2. Get argument specification for specific role
393
if roles_result.status == 'successful':
394
    argspec_result = ansible_runner.get_role_argspec(
395
        role='nginx',
396
        collection='community.general'
397
    )
398

399
# 3. Validate role arguments
400
if argspec_result.status == 'successful':
401
    print("Role arguments validated successfully")
402
```
403

404
### Inventory Analysis
405

406
```python
407
# 1. Get complete inventory listing
408
inventory_result = ansible_runner.get_inventory(
409
    action='list',
410
    inventories=['production/hosts'],
411
    response_format='json'
412
)
413

414
# 2. Analyze specific hosts
415
for host in ['web01', 'db01', 'app01']:
416
    host_result = ansible_runner.get_inventory(
417
        action='host',
418
        inventories=['production/hosts'],
419
        host=host,
420
        response_format='json'
421
    )
422
    if host_result.status == 'successful':
423
        print(f"Host {host} configuration retrieved")
424

425
# 3. Generate inventory visualization
426
graph_result = ansible_runner.get_inventory(
427
    action='graph',
428
    inventories=['production/hosts'],
429
    response_format='text'
430
)
431
```