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

  • 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

See Also

See also

Asynchronous actions and polling

Detailed information on how to use asynchronous actions and polling.

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