The Execution Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Ansible execution engine is the core component responsible for orchestrating the execution of tasks and plays defined in a playbook. It manages inventory, variables, and the flow of execution, dispatching tasks to target hosts and handling the results. The engine is designed to be extensible, primarily through strategy plugins that define the logic for how tasks are run across the inventory.
The main components of the execution engine are located in the lib/ansible/executor/ directory. This includes the PlaybookExecutor for managing playbook runs, the TaskQueueManager for handling task dispatch, and the TaskExecutor for running individual tasks. These components work together with strategy plugins, like the default linear strategy, to provide a flexible and powerful automation framework.
Sources: AGENTS.md
Core Components
The execution engine is composed of several key classes that collaborate to run a playbook.
| Class | File | Description |
|---|---|---|
PlaybookExecutor | playbook_executor.py | The main entry point for running an entire playbook. It parses the playbook and iterates through the plays, using a TaskQueueManager to execute the tasks within each play. |
TaskQueueManager | task_queue_manager.py | Manages the execution of tasks for a given play. It uses a strategy plugin to determine the order and parallelism of task execution against the inventory. |
TaskExecutor | task_executor.py | Responsible for executing a single task on a single host. It handles the connection, module execution, and result processing. |
StrategyBase / LinearStrategy | linear.py | Defines the execution strategy. LinearStrategy is the default, executing tasks on hosts in a sequential manner, respecting the serial keyword. |
Sources: lib/ansible/executor/playbook_executor.py, lib/ansible/executor/task_queue_manager.py, lib/ansible/executor/task_executor.py, lib/ansible/plugins/strategy/linear.py
Component Relationships
The following diagram illustrates the primary relationships between the core classes of the execution engine.
This class diagram shows that PlaybookExecutor uses a TaskQueueManager to run plays. The TaskQueueManager in turn uses a Strategy plugin (like LinearStrategy) and creates TaskExecutor workers to run individual tasks.
Sources: lib/ansible/executor/playbook_executor.py, lib/ansible/executor/task_queue_manager.py, lib/ansible/plugins/strategy/linear.py
Execution Flow
The execution of an Ansible playbook follows a well-defined sequence, managed by the core components of the execution engine.
High-Level Playbook Execution
The process begins when the PlaybookExecutor's run method is called. It iterates through each play in the playbook, setting up a TaskQueueManager for each one. The TaskQueueManager then uses the configured strategy to execute the tasks of the play.
The following sequence diagram shows the high-level interaction.
This diagram shows the PlaybookExecutor initiating a play run via the TaskQueueManager, which delegates the execution logic to a Strategy plugin. The strategy queues tasks, and the TaskQueueManager uses TaskExecutor workers to run them.
Sources: lib/ansible/executor/playbook_executor.py:163-210, lib/ansible/executor/task_queue_manager.py:289-299, lib/ansible/plugins/strategy/linear.py:279-291
Task Execution
The TaskExecutor is the final stage, responsible for executing a single task on a target host.
- Connection Setup: It establishes a connection to the target host using the appropriate connection plugin.
- Module Preparation: The module and its arguments are transferred to the target host.
- Module Execution: The module is executed on the remote host.
- Result Handling: The results (stdout, stderr, rc, JSON output) are collected from the remote host.
- Cleanup: The connection is closed, and any temporary files are removed.
Sources: lib/ansible/executor/task_executor.py:145-161
Strategy Plugins
Strategy plugins define the logic for how tasks are executed across the inventory. The linear strategy is the default.
Linear Strategy
The linear strategy, defined in lib/ansible/plugins/strategy/linear.py, executes tasks in a sequential order.
- It iterates through each task in the play.
- For each task, it runs it on a batch of hosts, determined by the
serialkeyword. - It waits for the current batch of hosts to complete the task before moving to the next batch.
- It handles failures and can trigger a rescue or always section of a block.
- It also manages running handlers at the end of a play.
The run method within the LinearStrategy class is the main entry point that orchestrates this flow. It uses an Iterator to get the next task and a WorkerProcess to manage the execution on hosts.
Sources: lib/ansible/plugins/strategy/linear.py:279-411
Meta Actions
The meta module provides a way to directly influence the execution flow from within a playbook. These are not regular tasks that execute on a remote host but are special actions processed by the execution engine itself.
| Action | Description | Version Added |
|---|---|---|
flush_handlers | Forces all notified handlers to run immediately. | 1.2 |
refresh_inventory | Forces a reload of the inventory, re-executing dynamic inventory scripts. | 2.0 |
clear_facts | Clears gathered facts for the targeted hosts. | 2.1 |
clear_host_errors | Clears the failed state from targeted hosts, making them available for subsequent plays. | 2.1 |
end_play | Ends the current play for all hosts without failing. | 2.2 |
reset_connection | Interrupts a persistent connection (e.g., SSH with ControlPersist). | 2.3 |
end_host | Ends the play for the current host without failing it. | 2.8 |
end_batch | Ends the current batch of hosts (defined by serial) without failing. | 2.12 |
end_role | Ends the execution of the current role. | 2.18 |
These actions provide fine-grained control over the playbook execution lifecycle. For example, refresh_inventory is useful when a play creates new hosts that need to be managed in later tasks.
Sources: lib/ansible/modules/meta.py:21-65
Summary
The Ansible Execution Engine is a sophisticated system that translates a playbook into a series of actions on remote hosts. It is built around the core concepts of PlaybookExecutor, TaskQueueManager, and TaskExecutor, with Strategy plugins providing the flexibility to control the execution flow. The engine's design allows for complex orchestration, error handling, and dynamic control through meta-actions, making it a powerful tool for IT automation.
Sources: lib/ansible/executor/playbook_executor.py, lib/ansible/executor/task_queue_manager.py, lib/ansible/plugins/strategy/linear.py