Home
Relevant source files
The following files were used as context for generating this wiki page:- README.md
- COPYING
- AGENTS.md
- lib/ansible/cli/doc.py
- test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py
- lib/ansible/galaxy/data/default/role/README.md
- test/integration/targets/ansible-galaxy-collection-cli/files/expected.txt
- lib/ansible/modules/copy.py
- hacking/ticket_stubs/bug_wrong_repo.md
Ansible is a simple IT automation system that handles configuration management, application deployment, cloud provisioning, ad-hoc task execution, network automation, and multi-node orchestration. It is designed to be minimal in nature, consistent, secure, and highly reliable, with an extremely low learning curve for administrators, developers, and IT managers.
Ansible manages nodes in an agentless manner, typically leveraging the SSH daemon. It describes infrastructure in a language that is both machine and human-friendly. The project is sponsored by Red Hat, Inc. and is licensed under the GNU General Public License v3.0 or later.
Sources: README.md:10-14, README.md:19-22, README.md:82-84
Design Principles
The core design of Ansible is guided by the following principles:
- Simplicity: An 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-Friendly: Describe infrastructure in a language that is both machine and human-friendly.
- Security and Auditability: Focus on security and easy review of content.
- Instant Management: Manage new remote machines instantly without bootstrapping software.
- Language Agnostic: Allow module development in any dynamic language, not just Python.
- Non-Root Usability: Be usable as a non-root user.
- Ease of Use: Be the easiest IT automation system to use.
Sources: README.md:16-29
Core Concepts and Structure
Ansible's architecture is composed of a control node where Ansible is run, and managed nodes that are automated. The core components include the CLI, the execution engine, and various forms of content like modules, plugins, roles, and collections.
This diagram shows the high-level flow where the Ansible Engine uses inventory and playbooks, which contain various content types, to configure managed nodes.
Sources: AGENTS.md:213-225
Code Structure
The repository is organized into several key directories under lib/ansible/:
| Directory | Description |
|---|---|
cli/ | Command-line interface implementations (e.g., ansible, ansible-playbook). |
executor/ | The core task execution engine and strategies. |
inventory/ | Inventory management and parsing logic. |
modules/ | Core modules, which are the units of work executed on remote nodes. |
module_utils/ | Shared utility code for modules. |
plugins/ | The plugin framework for filters, tests, lookups, etc. |
collections/ | The Ansible Collections framework for packaging and distributing content. |
The testing infrastructure resides in test/, with unit tests in test/units/ and integration tests in test/integration/.
Sources: AGENTS.md:213-233
Modules
Modules are the fundamental units of work in Ansible. They are standalone scripts that are transferred to and executed on remote nodes. Each module must contain specific documentation blocks for ansible-doc to parse.
A typical module file includes:
DOCUMENTATION: A YAML string containing metadata, description, options, and author information.EXAMPLES: A YAML string showing usage examples.RETURN: A YAML string describing the return values.- The Python code to execute the module's logic, typically using
AnsibleModulefromansible.module_utils.basic.
The validate-modules sanity test enforces the presence and correctness of these sections.
Sources: lib/ansible/modules/copy.py:10-210, test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py:612-629
Roles
Roles are a way to organize and reuse Ansible content (tasks, handlers, variables, templates) in a structured format. A role is a directory with a defined structure.
This diagram illustrates the standard directory structure of an Ansible role.
Sources: lib/ansible/galaxy/data/default/role/README.md
Collections
Collections are the standard format for distributing, sharing, and consuming Ansible content. They can contain modules, plugins, roles, and playbooks. A collection has a specific directory structure that is recognized by Ansible.
This diagram shows a simplified structure of an Ansible Collection.
Sources: test/integration/targets/ansible-galaxy-collection-cli/files/expected.txt
Development and Contribution
The project follows a structured development and contribution process, primarily managed through GitHub pull requests targeting the devel branch.
Sources: README.md:58-61, AGENTS.md:199-200
Contribution Workflow
The general workflow for contributing to Ansible is as follows:
This diagram outlines the steps for contributing code, from forking the repository to getting a pull request merged.
Sources: AGENTS.md:112-140, README.md:58-61
Testing
Ansible uses a comprehensive testing suite run via the ansible-test command. All contributions are expected to include appropriate tests.
| Test Type | Command Example | Description |
|---|---|---|
| Sanity | ansible-test sanity -v --docker default | Static analysis, linting (pylint, mypy), and style checks. |
| Units | ansible-test units -v --docker default | Unit tests for individual components, typically using pytest. |
| Integration | ansible-test integration -v --docker ubuntu2204 <target> | End-to-end tests that run playbooks against specific targets. |
Tests are run in isolated Docker containers to ensure a consistent environment.
Sources: AGENTS.md:41-84
Documentation and Code Standards
Licensing
All code contributed to ansible-core must be GPLv3 compatible. Code within lib/ansible/module_utils/ defaults to the more permissive BSD-2-Clause license. This is a non-negotiable requirement.
Sources: AGENTS.md:15-26, COPYING
Module Documentation
All plugins and modules require static documentation blocks (DOCUMENTATION, EXAMPLES, RETURN) that are parsable by ansible-doc. These blocks cannot be dynamically generated. The validate-modules sanity test enforces this structure and checks for schema validity, including correct option types, required fields, and versioning information.
Sources: lib/ansible/cli/doc.py:532-550, test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py:612-629
Changelogs
All user-facing changes require a changelog fragment in changelogs/fragments/. The fragment is a YAML file named {issue_number}-{description}.yml and contains a structured description of the change.
Sources: AGENTS.md:183-191
License
Ansible is licensed under the GNU General Public License v3.0 or later. The full text of the license is available in the COPYING file in the repository root.
Sources: README.md:82-84, COPYING