0
# Ansible Core
1

2
Ansible Core is a comprehensive IT automation platform that handles configuration management, application deployment, cloud provisioning, ad-hoc task execution, network automation, and multi-node orchestration. It provides a radically simple approach to automation with agentless architecture leveraging SSH for remote management, human-readable YAML for describing infrastructure, and extensive plugin systems for customization.
3

4
## Package Information
5

6
- **Package Name**: ansible-core
7
- **Language**: Python
8
- **Installation**: `pip install ansible-core`
9
- **Requirements**: Python 3.11+
10
- **License**: GPL-3.0+
11

12
## Core Imports
13

14
```python
15
import ansible
16
from ansible.constants import config
17
from ansible.errors import (
18
    AnsibleError,
19
    AnsibleParserError,
20
    AnsibleRuntimeError,
21
    AnsibleConnectionFailure,
22
    AnsibleTemplateError
23
)
24
```
25

26
For CLI usage:
27
```python
28
from ansible.cli.playbook import main as playbook_main
29
from ansible.cli.adhoc import main as adhoc_main
30
```
31

32
For programmatic usage:
33
```python
34
from ansible.inventory.manager import InventoryManager
35
from ansible.playbook import Playbook
36
from ansible.executor.task_queue_manager import TaskQueueManager
37
from ansible.parsing.dataloader import DataLoader
38
from ansible.template import Templar
39
from ansible.vars.manager import VariableManager
40
```
41

42
## Basic Usage
43

44
### CLI Commands
45
Ansible-core provides 9 command-line tools for different automation tasks:
46

47
```bash
48
# Execute ad-hoc commands on hosts
49
ansible all -m ping
50

51
# Run playbooks
52
ansible-playbook site.yml
53

54
# Manage inventory
55
ansible-inventory --list
56

57
# View documentation
58
ansible-doc -l
59

60
# Manage collections
61
ansible-galaxy collection install community.general
62

63
# Configuration management
64
ansible-config view
65

66
# Interactive console
67
ansible-console
68

69
# Pull mode (git-based automation)
70
ansible-pull -U repo_url playbook.yml
71

72
# Secrets management
73
ansible-vault encrypt secrets.yml
74
```
75

76
### Programmatic Usage
77
```python
78
from ansible.inventory.manager import InventoryManager
79
from ansible.parsing.dataloader import DataLoader
80
from ansible.executor.task_queue_manager import TaskQueueManager
81
from ansible.playbook import Playbook
82
from ansible.vars.manager import VariableManager
83

84
# Initialize core components
85
loader = DataLoader()
86
inventory = InventoryManager(loader=loader, sources=['inventory'])
87
variable_manager = VariableManager(loader=loader, inventory=inventory)
88

89
# Load and execute a playbook
90
pb = Playbook.load('site.yml', variable_manager=variable_manager, loader=loader)
91
tqm = TaskQueueManager(inventory=inventory, variable_manager=variable_manager, loader=loader)
92

93
# Execute the playbook
94
result = tqm.run(pb.get_plays())
95
```
96

97
## Architecture
98

99
Ansible Core follows a modular architecture designed for extensibility and reliability:
100

101
- **CLI Layer**: 9 command-line interfaces providing user-facing functionality
102
- **Core Engine**: Configuration management, parsing, templating, and execution orchestration
103
- **Plugin System**: 17 plugin types enabling customization of connection, action, inventory, callback, and other behaviors
104
- **Inventory Management**: Dynamic host and group management with pattern matching
105
- **Playbook Engine**: YAML-based automation workflow parsing and execution
106
- **Execution Engine**: Task queue management, parallel execution, and result aggregation
107
- **Template Engine**: Jinja2-based variable substitution and expression evaluation
108
- **Module Utilities**: Shared libraries for module development across different platforms
109

110
This architecture enables Ansible's agentless design, where the control node orchestrates automation across managed nodes via SSH without requiring agents on target systems.
111

112
## Capabilities
113

114
### Command Line Interface
115

116
Nine CLI tools providing comprehensive automation functionality including ad-hoc command execution, playbook management, inventory operations, documentation access, collection management, configuration control, interactive console, pull-based automation, and secrets management.
117

118
```python { .api }
119
def main():
120
    """Entry point for ansible CLI commands"""
121

122
# CLI modules
123
from ansible.cli.adhoc import main as adhoc_main
124
from ansible.cli.config import main as config_main
125
from ansible.cli.console import main as console_main
126
from ansible.cli.doc import main as doc_main
127
from ansible.cli.galaxy import main as galaxy_main
128
from ansible.cli.inventory import main as inventory_main
129
from ansible.cli.playbook import main as playbook_main
130
from ansible.cli.pull import main as pull_main
131
from ansible.cli.vault import main as vault_main
132
```
133

134
[Command Line Interface](./cli.md)
135

136
### Error Handling and Exceptions
137

138
Comprehensive exception hierarchy providing detailed error information with source context, supporting error recovery patterns and detailed debugging information for automation failures.
139

140
```python { .api }
141
class AnsibleError(Exception):
142
    """Base exception for all Ansible errors"""
143

144
class AnsibleParserError(AnsibleError):
145
    """Playbook or data file parsing errors"""
146

147
class AnsibleRuntimeError(AnsibleError):
148
    """Runtime execution errors"""
149

150
class AnsibleConnectionFailure(AnsibleRuntimeError):
151
    """Connection and transport failures"""
152

153
class AnsibleTemplateError(AnsibleRuntimeError):
154
    """Template processing errors"""
155
```
156

157
[Error Handling](./errors.md)
158

159
### Inventory Management
160

161
Dynamic host and group management system supporting static and dynamic inventory sources, host pattern matching, group relationships, and variable scoping for target host selection and organization.
162

163
```python { .api }
164
class InventoryManager:
165
    def __init__(self, loader, sources=None, parse=True, cache=True):
166
        """Initialize inventory manager"""
167

168
class Host:
169
    def __init__(self, name, port=None, gen_uuid=True):
170
        """Individual host representation"""
171

172
class Group:
173
    def __init__(self, name):
174
        """Host group representation"""
175
```
176

177
[Inventory Management](./inventory.md)
178

179
### Playbook Engine
180

181
YAML-based automation workflow system supporting plays, tasks, handlers, roles, blocks, includes, and imports with conditional execution, loops, delegation, and comprehensive error handling for complex automation scenarios.
182

183
```python { .api }
184
class Playbook:
185
    @staticmethod
186
    def load(filename, variable_manager, loader):
187
        """Load playbook from file"""
188

189
class Play:
190
    def __init__(self):
191
        """Individual play representation"""
192

193
class Task:
194
    def __init__(self):
195
        """Task representation with action and parameters"""
196
```
197

198
[Playbook Engine](./playbook.md)
199

200
### Plugin System
201

202
Extensible plugin architecture with 17 plugin types including action, callback, connection, filter, inventory, lookup, module, strategy, test, and vars plugins enabling customization of every aspect of Ansible's behavior.
203

204
```python { .api }
205
from ansible.plugins.loader import action_loader, callback_loader, connection_loader
206

207
class ActionBase:
208
    """Base class for action plugins"""
209

210
class CallbackBase:  
211
    """Base class for callback plugins"""
212

213
class ConnectionBase:
214
    """Base class for connection plugins"""
215
```
216

217
[Plugin System](./plugins.md)
218

219
### Configuration Management
220

221
Centralized configuration system supporting multiple sources (config files, environment variables, command line), validation, and runtime access to all Ansible settings with comprehensive default values and documentation.
222

223
```python { .api }
224
from ansible.config.manager import ConfigManager
225
from ansible.constants import config
226

227
class ConfigManager:
228
    def get_config_value(self, config_key):
229
        """Get configuration value"""
230

231
# Global configuration access
232
config_value = config.get_config_value('DEFAULT_HOST_LIST')
233
```
234

235
[Configuration](./configuration.md)
236

237
### Template Engine
238

239
Jinja2-based template processing system with Ansible-specific filters, tests, and functions supporting variable substitution, conditional logic, loops, and expression evaluation with security controls and performance optimization.
240

241
```python { .api }
242
class Templar:
243
    def __init__(self, loader, variables):
244
        """Initialize templating engine"""
245
    
246
    def template(self, variable, **kwargs):
247
        """Template a variable with context"""
248
```
249

250
[Template Engine](./templating.md)
251

252
### Module Utilities
253

254
Comprehensive utility libraries for module development including argument parsing, JSON handling, text conversion, network utilities, validation, platform abstraction, and common functionality shared across modules.
255

256
```python { .api }
257
from ansible.module_utils.basic import AnsibleModule
258
from ansible.module_utils.common.validation import check_required_arguments
259
from ansible.module_utils.common.text.converters import to_text, to_bytes
260
```
261

262
[Module Utilities](./module-utils.md)
263

264
### Execution Engine
265

266
Task execution orchestration system managing task queues, parallel execution, result collection, callback processing, and strategy selection for efficient automation execution across multiple hosts with comprehensive result aggregation.
267

268
```python { .api }
269
class TaskQueueManager:
270
    def __init__(self, inventory, variable_manager, loader):
271
        """Initialize task queue manager"""
272
    
273
    def run(self, play):
274
        """Execute play tasks"""
275

276
class TaskExecutor:
277
    def __init__(self, host, task, variable_manager, loader):
278
        """Execute individual tasks"""
279
```
280

281
[Execution Engine](./execution.md)
282

283
## Types
284

285
### Common Data Structures
286

287
```python { .api }
288
# Context and CLI arguments
289
class CLIArgs:
290
    """Container for CLI arguments and options"""
291

292
# Version information  
293
__version__: str  # Current ansible-core version
294
__author__: str   # Author information
295

296
# Configuration constants
297
config: ConfigManager  # Global configuration manager
298
COLOR_CODES: dict      # ANSI color code mappings
299
BOOL_TRUE: list        # Boolean true value patterns
300
```
301

302
### Exception Hierarchy
303

304
```python { .api }
305
class ExitCode(enum.IntEnum):
306
    SUCCESS = 0
307
    GENERIC_ERROR = 1  
308
    HOST_FAILED = 2
309
    HOST_UNREACHABLE = 4
310
    PARSER_ERROR = 4
311
    INVALID_CLI_OPTION = 5
312
    KEYBOARD_INTERRUPT = 99
313
    UNKNOWN_ERROR = 250
314
```