Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• lib/ansible/config/base.yml
• test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py
• pyproject.toml
• lib/ansible/modules/uri.py
• lib/ansible/modules/apt.py
• lib/ansible/modules/lineinfile.py
• lib/ansible/plugins/doc_fragments/template_common.py

Ansible's configuration system is a multi-layered framework that provides flexibility for users and developers. It governs the behavior of the Ansible controller, connection plugins, and execution of modules. Configuration can be specified through ansible.cfg files, environment variables, command-line arguments, and playbook keywords.

At its core, the system relies on a central definition of all possible settings. Individual modules and plugins further define their own parameters through structured documentation blocks. A robust validation system ensures that module configurations are consistent, correctly documented, and adhere to project standards. Project-level settings, such as dependencies and supported Python versions, are managed separately in the pyproject.toml file.

Core Configuration

The primary source of truth for all global Ansible settings is lib/ansible/config/base.yml. This file defines every configurable parameter that can be set in ansible.cfg, an environment variable, or a vars plugin. Each entry specifies the parameter's name, description, default value, type, and how it maps to environment variables and INI file settings.

Sources: lib/ansible/config/base.yml

Configuration Entry Structure

Each configuration item in base.yml is a YAML dictionary with a consistent structure. This structure dictates how the setting is processed, its default value, and where it can be defined.

The diagram below illustrates the structure of a typical configuration entry.

An example entry for DEFAULT_FORKS from base.yml:

DEFAULT_FORKS:
  name: Number of task forks
  default: 5
  description: Maximum number of forks Ansible will use to execute tasks on target hosts.
  env: [{name: ANSIBLE_FORKS}]
  ini:
  - {key: forks, section: defaults}
  type: integer

Sources: lib/ansible/config/base.yml:256-262

Key Global Settings

The base.yml file contains numerous settings that control fundamental Ansible behaviors. The following table summarizes a few key examples.

Setting	Description	Default Value	Type
DEFAULT_FORKS	Maximum number of forks Ansible will use to execute tasks on target hosts.	5	integer
ANSIBLE_PIPELINING	Reduces network operations by executing modules without file transfer, but can conflict with privilege escalation.	False	boolean
COLLECTIONS_PATHS	Colon-separated paths where Ansible will search for collections content.	~/.ansible/collections:/usr/share/ansible/collections	pathspec
DEFAULT_LOG_PATH	File to which Ansible will log on the controller. Logging is disabled if not set.	~ (null)	path
HOST_KEY_CHECKING	If False, avoids host key checking by the underlying connection plugin.	True	boolean
DEFAULT_STDOUT_CALLBACK	Sets the main callback plugin used to display Ansible output.	default	string

Sources: lib/ansible/config/base.yml

Module & Plugin Configuration

Individual modules and plugins define their own parameters within a DOCUMENTATION string variable inside the Python source file. This structured YAML string is parsed by ansible-doc to generate documentation and by the validation system to ensure correctness.

Documentation Block

The DOCUMENTATION block contains metadata about the module, including its short_description, version_added, and most importantly, the options it accepts.

The diagram below shows the typical structure of a module's DOCUMENTATION.

Module Options

The options dictionary is the core of a module's configuration. Each key is a parameter the module accepts, and its value is a dictionary describing its attributes.

Example from lib/ansible/modules/uri.py:

DOCUMENTATION = r"""
---
module: uri
short_description: Interacts with webservices
...
options:
  url:
    description:
      - HTTP or HTTPS URL in the form (http|https)://host.domain[:port]/path.
    type: str
    required: true
  method:
    description:
      - The HTTP method of the request or response.
    type: str
    default: GET
  validate_certs:
    description:
      - If V(false), SSL certificates will not be validated.
    type: bool
    default: true
    version_added: '1.9.2'
...
"""

Sources: lib/ansible/modules/uri.py:12-140

The following table details some options from the ansible.builtin.uri module.

Parameter	Description	Type	Required	Default
url	HTTP or HTTPS URL to interact with.	str	Yes	N/A
dest	Path to download the file to.	path	No	N/A
method	The HTTP method of the request.	str	No	GET
body_format	Serialization format of the body.	str	No	raw
return_content	Whether to return the body of the response.	bool	No	no
validate_certs	If false, SSL certificates will not be validated.	bool	No	true

Sources: lib/ansible/modules/uri.py:23-140

Documentation Fragments

To reduce duplication, common sets of options can be defined in documentation fragments and included in modules. The template_common fragment, for example, provides standard options for Jinja2 templating.

# lib/ansible/plugins/doc_fragments/template_common.py
class ModuleDocFragment(object):
    DOCUMENTATION = r"""
options:
  src:
    description:
    - Path of a Jinja2 formatted template on the Ansible controller.
    type: path
    required: yes
  dest:
    description:
    - Location to render the template to on the remote machine.
    type: path
    required: yes
...
"""

Sources: lib/ansible/plugins/doc_fragments/template_common.py:10-41

A module like lineinfile can then extend this fragment.

# lib/ansible/modules/lineinfile.py
...
extends_documentation_fragment:
    - action_common_attributes
    - action_common_attributes.files
    - files
    - validate
...

Sources: lib/ansible/modules/lineinfile.py:110-115

Configuration Validation

Ansible uses a sanity test named validate-modules to enforce configuration standards and consistency. This test is crucial for maintaining the quality of modules and plugins.

Sources: test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py

Validation Process

The validation process is handled by the ModuleValidator class, which performs several checks. The following diagram shows the high-level workflow.

Key Validation Checks

The ModuleValidator performs several critical checks:

1. Schema Validation: It uses voluptuous schemas (doc_schema, return_schema) to validate the structure and types of the DOCUMENTATION and RETURN blocks.
   Sources: test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py:100-111, 804-826
2. Argument Spec Consistency: It introspects the argument_spec dictionary defined in the module's code and compares it against the options defined in the DOCUMENTATION block. This ensures that the code and documentation are synchronized.
   Sources: test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py:1288-1309
3. Deprecation and version_added: It checks that version_added tags are present and correct for new modules and options. It also verifies that deprecation notices are consistent between the code, documentation, and meta/runtime.yml.
   Sources: test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py:1232-1250, 1618-1640
4. Code Standards: It scans for the use of forbidden imports (e.g., sys.exit), ensures module_utils are imported correctly, and verifies the presence of a GPLv3 license header.
   Sources: test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py:461-471, 532-556, 488-500

Project-Level Configuration

The pyproject.toml file defines project-level configuration, including build-time dependencies and metadata, adhering to modern Python packaging standards (PEP 621).

Sources: pyproject.toml

Build and Dependency Management

This file specifies the build system and dynamically determines the project's version and dependencies.

[build-system]
requires = ["setuptools >= 77.0.3, <= 80.3.1"]
build-backend = "setuptools.build_meta"

[project]
requires-python = ">=3.12"
name = "ansible-core"
...
dynamic = ["version", "dependencies"]

[tool.setuptools.dynamic]
version = {attr = "ansible.release.__version__"}
dependencies = {file = "requirements.txt"}

Sources: pyproject.toml:1-17, 29-31

Key Project Settings

Setting	Value	Description
requires-python	>=3.12	Specifies the minimum required Python version to run ansible-core.
dynamic = ["version"]	ansible.release.__version__	The project version is dynamically sourced from the __version__ attribute in ansible.release.
dynamic = ["dependencies"]	requirements.txt	Runtime dependencies are read from the requirements.txt file.

Sources: pyproject.toml:5, 15, 29-31

Conclusion

Ansible's configuration system is comprehensive, covering global runtime behavior, module-specific parameters, and project build settings. The definitions are stored in structured YAML (base.yml) and in-line DOCUMENTATION blocks, providing a single source of truth for both the application and its documentation. This is enforced by a validate-modules sanity test, which ensures consistency between code and documentation, contributing to the project's overall stability and maintainability. This layered and validated approach allows Ansible to be highly configurable for users while remaining manageable for developers.