004-task.md

Task

Tasks are divided into single-layer and multi-layer types:

• Single-layer task: Contains module-related fields, does not contain block. A task can only use one module.
• Multi-layer task: Does not contain module fields, contains block (with optional rescue, always).

Tasks execute on each host of the play separately (unless run_once: true).

File Definition

- include_tasks: other/task.yaml
  tags: ["always"]
  when: true
  run_once: false
  ignore_errors: false
  vars: { a: b }

- name: Block Name
  tags: ["always"]
  when: true
  run_once: false
  ignore_errors: false
  vars: { a: b }
  block:
    - name: Task Name
      [module]
  rescue:
    - name: Task Name
      [module]
  always:
    - name: Task Name
      [module]

- name: Task Name
  tags: ["always"]
  when: true
  loop: [""]
  [module]

Field	Description
include_tasks	Reference other task files.
name	Task name, optional.
tags	Tags, optional. Only applies to this task, does not inherit play/role tags.
when	Execution condition, optional. Can be a string or array, using template syntax, evaluated separately for each host.
failed_when	Failure condition, optional. Considered failed when met, supports template syntax.
run_once	Whether to execute only once, optional, default false. Executes on the first host.
ignore_errors	Whether to ignore failures, optional, default false.
vars	Variables for this task, optional, YAML format.
loop	Execute module in a loop, passing current value as item each iteration. Can be a string or array, using template syntax.
retries	Number of retries on failure, optional.
register	Write execution result to variable for subsequent tasks. Contains sub-fields like stderr, stdout.
register_type	Parse format for register: string (default), json, yaml.
block	Task list. Required when no module is defined, executes in normal flow.
rescue	Task list. Executes when any sibling task in block fails.
always	Task list. Executes after block (and rescue if present) regardless of success or failure.
module	Specific operation, corresponding to registered modules. Required when not using block.

Registered Modules

Module	Description
add_hostvars	Inject variables into specified hosts
assert	Conditional assertion
command	Execute commands
copy	Copy files/directories to target hosts
debug	Print variables
fetch	Fetch files from remote hosts to local
gen_cert	Validate or generate certificates
image	Pull/push/copy images
include_vars	Load variables from YAML files
prometheus	Query Prometheus metrics
result	Write to playbook status detail
set_fact	Set variables on the current host
setup	Gather host information
template	Render templates and copy to target hosts