Complete Ansible Task Parameter List (Core, Advanced, Rare & Edge-Case Keywords)

Ansible cheat book
Understanding Ansible task parameters is essential for writing predictable, maintainable, and production-ready automation. This guide provides a comprehensive list of every Ansible task parameter, including core options, advanced controls, error-handling, loops, asynchronous features, privilege escalation, and rarely used parameters that even experienced engineers miss.

Use this as a reference when building playbooks for Linux, Windows, cloud, containers, or AAP automation.

1. Core Task Parameters

These are the parameters most commonly used in everyday tasks.

name — Human-readable description of the task.
tags — Labels that allow selective execution using --tags or --skip-tags.
vars — Task-level variables, visible only to that task.
vars_files — Load extra variables from external files.
environment — Environment variables to pass to the task or module.
delegate_to — Execute the task on a different host.
delegate_facts — Store gathered facts on the delegated host.
register — Capture the result of a task for later use.
when — Conditional statement to control task execution.
loop — Repeat a task over a list of items.
loop_control — Additional controls for loops (index, pause, label).
with_items — Legacy looping method over lists.
with_dict — Legacy loop over dictionary items.
with_sequence — Legacy loop to generate number sequences.
with_together — Legacy loop to iterate multiple lists simultaneously.
with_subelements — Iterate nested lists or objects.
with_file / with_fileglob — Iterate lines or matching file patterns.
with_indexed_items — Loop with index and item.

2. Retry, Error, and Result Handling

These parameters control how tasks retry, fail, and record results.

retries — Number of retry attempts when using until.
delay — Pause between retries.
until — Retry until a condition becomes true.
ignore_errors — Continue execution even if the task fails.
failed_when — Custom logic to mark the task as failed.
changed_when — Custom logic to mark the task as changed.
any_errors_fatal — Stop the full play if any host encounters an error.
ignore_unreachable — Avoid failure when a host is unreachable.
no_log — Hide output for sensitive tasks.
run_once — Execute the task once, even with multiple hosts.
max_fail_percentage — Stop play if failures exceed this percentage.

3. Privilege Escalation & Connection Control

Control the connection, remote user, and privilege escalation.

become — Enable privilege escalation.
become_user — Target user for privilege escalation.
become_method — Method used for escalation (sudo, su, runas).
become_exe — Custom escalation executable.
become_flags — Extra flags passed to the escalation tool.
connection — Force connection type (ssh, winrm, local).
remote_user — Remote user for connecting.
delegate_to — Execute the task on another host.
run_once — Run only once during a play.
throttle — Limit number of hosts executing the task concurrently.

🔵 4. Block-Level Error Handling

Blocks group tasks together with shared error recovery.

block: — Group of tasks.
rescue: — Tasks to run when the block fails.
always: — Tasks that always run whether the block succeeds or fails.

5. Notifications & Handlers

Used for triggering handlers after a task completes.

notify — Trigger one or more handlers after task completion.
listen — Alias for handlers to group multiple notifications.

6. Async & Parallel Execution

Improve performance and allow long-running operations.

async — Run tasks asynchronously (timeout in seconds).
poll — Poll interval when waiting on async tasks.
throttle — Limit parallel execution of tasks.
serial — Restrict the number of hosts processed in each batch.

7. Include, Import & File Loading

Reusable blocks and modular playbook structure.

include_tasks — Dynamically include task files at runtime.
import_tasks — Statically import tasks when the playbook is parsed.
include_vars — Load variables from a file.
include_role — Dynamically include a role.
import_role — Import role statically at parse time.
import_playbook — Import full playbooks.
add_host — Add hosts to inventory dynamically.
group_by — Group hosts dynamically based on conditions.

8. Pause & Operator Interaction

Useful for interactive workflows or scheduled pauses.

pause — Wait or prompt the operator.
prompt — Request user input during play execution.
debug — Show variables or custom messages.
assert — Validate conditions and stop execution on failure.

9. Result, Fact & Data Handling

Store and manage data generated during a play.

set_fact — Create dynamic variables for later tasks.
add_host — Add host entries with variables.
group_by — Group hosts by criteria.
debug — Display variables.
msg — Custom message text.
ansible.builtin.assert — Ensure a condition is met.

10. Rare or Advanced Parameters

These parameters are powerful but less commonly used.

args — Pass additional arguments to modules.
command — Free-form command execution.
free_form — Properties used by modules that only need single arguments.
delegate_facts — Store facts on delegated hosts.
module_defaults — Define default settings for modules.
async_dir — Async job metadata directory.
notify_group — Batch handler notifications.
notify_handlers_in_batch — Execute handlers in groups.
loop_var — Rename the loop variable (item).
loop_control.index_var — Index variable for loops.
loop_control.label — Display label for loop iterations.
loop_control.pause — Delay between loop iterations.
loop_control.extended — Provide extended metadata.

11. Playbook-Level Parameters (Often Confused as Task-Level)

Included here for clarity.

strategy — How tasks are executed (linear, free, host_pinned).
gather_facts — Enable or disable fact gathering.
gather_subset — Control what facts are collected.
gather_timeout — Timeout for fact collection.
collections — Collections to load modules from.
roles — Apply roles in the play.
force_handlers — Force handlers to run on failure.
order — Execution order for hosts.
hosts — Target machines for the play.

Bonus: Obscure & Underused Parameters

These parameters are rarely used but extremely powerful.

check_mode — Control task execution during dry-run.
diff — Show configuration diffs for supported modules.
vars_prompt — Prompt user for variables at play start.
any_errors_fatal — Abort play on first failure.
ignore_unreachable — Keep running even if hosts go offline.
no_log — Hide logs for sensitive operations.
loop_control.pause / label / index_var — Extended loop controls.

Conclusion

This list covers every important Ansible task parameter, including core options, advanced controls, error-handling mechanisms, and lesser-known features. Whether you are creating automation for Linux, Windows, cloud, or AAP, understanding these parameters helps you write clean, predictable, and reusable playbooks.