Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page: - [AGENTS.md](https://github.com/Alonso-pixel/ansible/blob/HEAD/AGENTS.md) - [README.md](https://github.com/Alonso-pixel/ansible/blob/HEAD/README.md) - [lib/ansible/cli/doc.py](https://github.com/Alonso-pixel/ansible/blob/HEAD/lib/ansible/cli/doc.py) - [lib/ansible/modules/apt.py](https://github.com/Alonso-pixel/ansible/blob/HEAD/lib/ansible/modules/apt.py) - [lib/ansible/modules/blockinfile.py](https://github.com/Alonso-pixel/ansible/blob/HEAD/lib/ansible/modules/blockinfile.py) - [lib/ansible/modules/replace.py](https://github.com/Alonso-pixel/ansible/blob/HEAD/lib/ansible/modules/replace.py) - [pyproject.toml](https://github.com/Alonso-pixel/ansible/blob/HEAD/pyproject.toml) - [test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py](https://github.com/Alonso-pixel/ansible/blob/HEAD/test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py)

Ansible is an IT automation system designed for configuration management, application deployment, cloud provisioning, and multi-node orchestration. Its architecture is founded on principles of simplicity, agentless operation, and human-readable automation. By leveraging existing protocols like SSH, it avoids the need for custom agents on managed nodes, allowing for immediate management of remote machines.

The system is composed of a core engine, a set of command-line tools, an extensible plugin system, and a vast library of modules that represent the units of work. This document provides a high-level overview of the key architectural components, their interactions, and the design principles that guide the project's development.

Sources: README.md:14-18, AGENTS.md:126-132

Design Principles

The core design of Ansible is guided by a set of principles that prioritize simplicity, security, and ease of use.

• Simplicity: Extremely simple setup process with a minimal learning curve.
• Parallelism: Manage machines quickly and in parallel.
• Agentless: Avoid custom agents and additional open ports by leveraging existing SSH daemons.
• Human and Machine Friendly: Describe infrastructure in a language that is both machine and human-readable.
• Security and Auditability: Focus on security and easy review of content.
• Instant Management: Manage new remote machines instantly without bootstrapping software.
• Language Agnostic Modules: Allow module development in any dynamic language, not just Python.
• Non-Root Usability: Be usable as a non-root user.
• Ease of Use: Strive to be the easiest IT automation system to use.

Sources: README.md:20-36

Core Components and Repository Structure

The Ansible codebase is organized into several key directories within the lib/ansible/ path. Each directory serves a distinct purpose within the overall architecture.

Directory	Description
cli/	Implementations for command-line interfaces (e.g., ansible-playbook, ansible-doc).
executor/	The core task execution engine and strategies.
inventory/	Code for inventory management and parsing.
modules/	Core modules, which are the fundamental units of work executed on remote nodes.
module_utils/	Shared utility code that can be used by modules.
plugins/	The plugin framework, providing extensibility for filters, tests, lookups, and more.
collections/	The framework for Ansible Collections, a modern packaging format for content.
config/	Configuration handling.
vars/	Variable management.

Sources: AGENTS.md:126-138

The following diagram illustrates the high-level structure of the repository.

Command Line Interface (CLI)

The primary user interaction with Ansible is through its command-line tools. These tools serve as the entry points for executing ad-hoc commands, running playbooks, managing inventory, and accessing documentation.

Entry Points

The script entry points are defined in pyproject.toml. Each script maps to a main function within a specific module in the lib/ansible/cli/ directory.

Script Name	Entry Point
ansible	ansible.cli.adhoc:main
ansible-config	ansible.cli.config:main
ansible-console	ansible.cli.console:main
ansible-doc	ansible.cli.doc:main
ansible-galaxy	ansible.cli.galaxy:main
ansible-inventory	ansible.cli.inventory:main
ansible-playbook	ansible.cli.playbook:main
ansible-pull	ansible.cli.pull:main
ansible-vault	ansible.cli.vault:main
ansible-test	ansible_test._util.target.cli.ansible_test_cli_stub:main

Sources: pyproject.toml:90-99

Implementation

Each CLI tool is implemented as a class that inherits from ansible.cli.CLI. For example, the ansible-doc command is implemented by the DocCLI class. This class is responsible for parsing command-line arguments, processing the request, and displaying the output.

The following sequence diagram shows the execution flow for a command like ansible-doc -l.

Module System

Modules are the core building blocks of Ansible, representing the individual units of work that are executed on managed nodes. They are designed to be standalone scripts that can be written in any language, though most are Python.

Sources: README.md:32, AGENTS.md:130

Module Structure

A standard Python-based Ansible module must contain several key components:

1. DOCUMENTATION: A static YAML string that defines the module's metadata, description, options, and author information. This is parsed via AST for documentation generation and cannot be dynamically generated.
2. EXAMPLES: A static YAML string providing usage examples.
3. RETURN: A static YAML string describing the structure and content of the data returned by the module on success.
4. main() function: The primary entry point for the module's logic.
5. AnsibleModule instantiation: The module must import and instantiate the AnsibleModule class from ansible.module_utils.basic to handle argument parsing, execution, and returning results.

The following diagram shows the typical structure of a module file.

For example, the replace module defines its parameters within the DOCUMENTATION block.

# lib/ansible/modules/replace.py:19-25
DOCUMENTATION = r"""
---
module: replace
author: Evan Kaufman (@EvanK)
...
short_description: Replace all instances of a particular string in a
                   file using a back-referenced regular expression
...
"""

Sources: lib/ansible/modules/replace.py:19-25

Module Validation

The validate-modules sanity test enforces the structural and documentation standards for all modules. This process involves:

1. Parsing the module file using Python's ast library.
2. Extracting the DOCUMENTATION, EXAMPLES, and RETURN string variables.
3. Parsing these strings as YAML.
4. Validating the parsed data against a predefined schema (doc_schema, return_schema).
5. Checking for GPLv3 license headers.
6. Ensuring imports are placed correctly after the documentation blocks.
7. Introspecting the AnsibleModule instantiation to compare the argument_spec with the documented options.

This rigorous validation ensures consistency and quality across all modules.

Module Dependencies

Modules are designed to be self-contained for remote execution.

• They can only import from Python's standard library and from lib/ansible/module_utils/.
• The lib/ansible/module_utils/ directory itself cannot import from outside of itself.

This restriction ensures that when a module is transferred to a remote host, all its dependencies are available.

Sources: AGENTS.md:120-122

Testing and CI

The project maintains a robust testing infrastructure to ensure code quality and stability. The primary tool for this is ansible-test.

• Sanity Tests: These are static analysis and linting checks (e.g., pylint, mypy) that enforce code style and standards. They are run using ansible-test sanity.
• Unit Tests: Located in test/units/, these tests focus on individual components in isolation. They are run using ansible-test units.
• Integration Tests: Located in test/integration/targets/, these tests verify the functionality of plugins and modules in a more realistic environment. They are run using ansible-test integration.

Tests are typically executed within isolated Docker containers to ensure a consistent and clean environment.

Sources: AGENTS.md:41-71