Glossary

Project-specific vocabulary. Where a term has a deeper page in this wiki, it is linked.

A

Action plugin. The controller-side half of a module call. Lives under lib/ansible/plugins/action/. An action plugin runs in the controller's Python process and decides what to do with a task — typically it builds an AnsiBallZ wrapper and ships it to the remote host, but some actions (e.g., set_fact, debug, add_host) never touch a remote host. See Plugins → Action.

AnsiBallZ. Ansible's name for the self-contained Python archive shipped to a remote target for each task. Built by lib/ansible/executor/module_common.py, it bundles the module's lib/ansible/modules/*.py source, any imported module_utils/, and a small __main__ shim that unpacks and runs the module. See Systems → Module execution and AnsiBallZ.

ansible-core. The PyPI distribution containing the engine, the CLIs, the plugin framework, and ~73 essential modules. Distinct from "Ansible the package", which is ansible-core plus a curated set of collections.

Argument spec. The schema declared in a module's argument_spec that drives parameter validation. See lib/ansible/module_utils/common/parameters.py and lib/ansible/module_utils/common/arg_spec.py.

B

Block. A grouping of tasks with shared error handling. A block can have rescue: (run on failure) and always: (run regardless). Implemented in lib/ansible/playbook/block.py. See Primitives → Task and block.

Become. Privilege escalation. The BecomeBase plugin family in lib/ansible/plugins/become/ (sudo, su, runas) wraps the remote command with the appropriate escalation prompt-handling. See Plugins → Become.

C

Callback plugin. Receives event notifications from the executor (task start, task result, play start, etc.) for display or external integration. Implementations live in lib/ansible/plugins/callback/ (default, minimal, oneline, junit, tree). See Plugins → Callback.

Collection. Modern packaging format for distributing Ansible content (modules, plugins, roles, playbooks). Resolved by the collection loader and managed by ansible-galaxy collection. See Features → Collections.

Connection plugin. Talks to a remote target — ssh, local, winrm, psrp. Lives in lib/ansible/plugins/connection/. See Plugins → Connection.

D

DataLoader. The object that reads YAML/JSON files from disk and runs them through the YAML loader and the Vault. Implemented in lib/ansible/parsing/dataloader.py.

Datatag. Metadata attached to YAML scalars and Python primitives via AnsibleTagHelper (lib/ansible/module_utils/_internal/_datatag.py). Tags include Origin (source location), TrustedAsTemplate (eligible for {{ ... }} rendering), and VaultedValue (encrypted at rest). The trust mechanism in particular is central to the 2.19+ template-injection hardening.

F

Fact. A piece of data discovered about a host by the setup module (or another fact-collecting module). Stored under the ansible_facts key in host vars. Collectors live in lib/ansible/module_utils/facts/. See Features → Fact gathering.

FQCN. Fully-qualified collection name: <namespace>.<collection>.<plugin> (e.g., ansible.builtin.copy, community.general.archive). The plugin loader prefers FQCNs and falls back to the legacy short-name aliases in lib/ansible/config/ansible_builtin_runtime.yml.

H

Handler. A task that runs only when notified by another task's notify:. Subclass of Task in lib/ansible/playbook/handler.py. Handlers run after the play's regular tasks finish. See Primitives → Role and handler.

I

Include vs. import. Both pull tasks/roles into a play, but with different semantics: include_* is dynamic (resolved at task time), import_* is static (resolved at parse time). Implementation in lib/ansible/playbook/included_file.py and the include_role, include_tasks, import_role, import_tasks modules.

Inventory plugin. Resolves a source (a file, a script, a cloud API) to a set of hosts and groups. Implementations: host_list, script, auto, yaml, ini, toml, constructed, advanced_host_list, generator. See Plugins → Inventory.

J

Jinja2. The templating language Ansible uses for variable interpolation. ansible-core uses a hardened wrapper around upstream Jinja2 in lib/ansible/_internal/_templating/, with custom tag and trust handling.

L

Lookup plugin. A controller-side function returning data into the variable namespace, callable as {{ lookup('name', ...) }} or via the shorthand {{ q('name', ...) }}. Implementations in lib/ansible/plugins/lookup/. See Plugins → Lookup.

M

Module. A single unit of automation that runs on a remote target. Modules in this repo live under lib/ansible/modules/ and only import from lib/ansible/module_utils/ because they are bundled and shipped as standalone scripts. See Features → Modules and actions.

module_utils. Shared helper code that is also packaged and shipped along with modules. Cannot import from outside itself. Lives at lib/ansible/module_utils/.

P

Play. One element of a playbook: a hosts pattern, options (vars, become, gather_facts), and a list of tasks (and optionally roles, pre_tasks, post_tasks, handlers). Implementation in lib/ansible/playbook/play.py.

Playbook. A YAML file containing a list of plays. Optionally includes other playbooks via import_playbook. Implementation in lib/ansible/playbook/__init__.py.

PlayContext. Per-task connection settings (host, user, port, become, password, env). Built fresh for each (host, task) pair from the play's options + variables. See lib/ansible/playbook/play_context.py.

PlayIterator. State machine that walks a play's task list per host, threading through blocks, loops, includes, and rescue/always paths. See lib/ansible/executor/play_iterator.py.

Plugin loader. The PluginLoader class in lib/ansible/plugins/loader.py resolves plugin names to classes across built-in, collection, and user paths. One instance per plugin type (e.g., action_loader, connection_loader).

R

Role. A reusable bundle of tasks, handlers, vars, defaults, files, templates, and meta. On disk it's a directory tree; in code it's lib/ansible/playbook/role/__init__.py. See Primitives → Role and handler.

Runtime.yml / ansible_builtin_runtime.yml. The redirect map at lib/ansible/config/ansible_builtin_runtime.yml from legacy short module names (ec2, mysql_user, azure_rm_*) to their new FQCNs in collections. Loaded by the plugin loader during name resolution.

S

Strategy plugin. Controls task scheduling within a play — linear (default), free (each host runs as fast as it can), host_pinned (one task per host on a worker), debug (interactive). See Plugins → Strategy.

T

Task. A leaf node in a play: an action, its arguments, and modifiers (when, loop, register, tags, become, delegate_to). Implementation in lib/ansible/playbook/task.py.

TaskExecutor. The worker-process class that runs a single (host, task) pair: resolves the action plugin, evaluates conditionals, runs the loop, and ships the AnsiBallZ payload. Implementation in lib/ansible/executor/task_executor.py.

TaskQueueManager (TQM). The controller-side scheduler. Forks worker processes, runs the strategy, drains the result queue, and emits callback events. Implementation in lib/ansible/executor/task_queue_manager.py.

Templar / TemplateEngine. Jinja2 wrapper. The legacy Templar (lib/ansible/template/__init__.py) and the modern TemplateEngine (lib/ansible/_internal/_templating/_engine.py) both render {{ ... }} against a variable scope, with Ansible's filter/test/lookup plugins bound in.

TrustedAsTemplate. A datatag (lib/ansible/_internal/_datatag/_tags.py) marking a string as eligible for Jinja evaluation. Strings that come from facts, registered task results, or arbitrary user input are not trusted by default — preventing template-injection.

V

Vault. Symmetric AES-256-CTR (or older AES-128-CTR) encryption for variables, files, or arbitrary strings. Implementation in lib/ansible/parsing/vault/__init__.py. Identified by a vault id and optionally a label, e.g., dev@~/.vault-pass-dev.

Variable manager. Coordinates the precedence-ordered merge of variables from inventory, host_vars, group_vars, role defaults, play vars, set_fact, registered results, and 18 other sources. See lib/ansible/vars/manager.py:VariableManager.get_vars.

W

WorkerProcess. A forked child of the controller that runs TaskExecutor for one task at a time. Implementation in lib/ansible/executor/process/worker.py.

Symbols

{{ }}. Jinja expression block. Evaluated by TemplateEngine against the current variable scope.

{% %}. Jinja statement block (for/if/set). Less common in playbooks but valid in template files.

!unsafe, !vault. YAML tags handled by the custom loader in lib/ansible/parsing/yaml/loader.py. !unsafe marks a string as not eligible for templating; !vault marks an inline Vault-encrypted value.