ansible.builtin.async_status module – Obtain status of asynchronous task

Note

This module is part of ansible-core and included in all Ansible installations. In most cases, you can use the short module name async_status even without specifying the collections keyword. However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.async_status for easy linking to the module documentation and to avoid conflicting with other collections that may have the same module name.

Synopsis
Parameters
Attributes
See Also
Examples
Return Values

Synopsis

This module gets the status of an asynchronous task.
This module is also supported for Windows targets.

Note

This module has a corresponding action plugin.

Parameters

Parameter	Comments
jid string / required	Job or task identifier
mode string	If `status`, obtain the status. If `cleanup`, clean up the async job cache (by default in `~/.ansible_async/`) for the specified job `jid`, without waiting for it to finish. Choices: `"cleanup"` `"status"` ← (default)

Attributes

Attribute	Support	Description
action	Support: full	Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller
async	Support: none	Supports being used with the `async` keyword
bypass_host_loop	Support: none	Forces a ‘global’ task that does not execute per host, this bypasses per host templating and serial, throttle and other loop considerations Conditionals will work as if `run_once` is being used, variables used will be from the first available host This action will not work normally outside of lockstep strategies
check_mode	Support: full added in ansible-core 2.17	Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped.
diff_mode	Support: none	Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode
platform	Platforms: posix, windows	Target OS/families that can be operated against

Examples

---
- name: Asynchronous dnf task
  ansible.builtin.dnf:
    name: docker-io
    state: present
  async: 1000
  poll: 0
  register: dnf_sleeper

- name: Wait for asynchronous job to end
  ansible.builtin.async_status:
    jid: '{{ dnf_sleeper.ansible_job_id }}'
  register: job_result
  until: job_result.finished
  retries: 100
  delay: 10

- name: Clean up async file
  ansible.builtin.async_status:
    jid: '{{ dnf_sleeper.ansible_job_id }}'
    mode: cleanup

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
ansible_job_id string	The asynchronous job id Returned: success Sample: `"360874038559.4169"`
erased string	Path to erased job file Returned: when file is erased
finished integer	Whether the asynchronous job has finished (`1`) or not (`0`) Returned: always Sample: `1`
started integer	Whether the asynchronous job has started (`1`) or not (`0`) Returned: always Sample: `1`
stderr string	Any errors returned by async_wrapper Returned: always
stdout string	Any output returned by async_wrapper Returned: always

Authors

Ansible Core Team
Michael DeHaan

Collection links

© 2012–2018 Michael DeHaan
© 2018–2024 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/ansible/builtin/async_status_module.html