Implementing Asynchronous Tasks

1. Setting Async Tasks

Parameter	Description	Default Value	Notes
async	Maximum number of seconds to wait for the task to complete	0 (no timeout)	Set to 0 for no timeout, or a positive integer
poll	How often (in seconds) to check the status of an async task	15	Used in conjunction with `async`

Example: Running an async task with polling

- name: Run a long-running command asynchronously
  command: sleep 30
  async: 60
  poll: 5

Note: The async and poll parameters are used together to manage asynchronous tasks in Ansible. The async parameter sets the maximum time to wait for completion, while poll determines how frequently to check the task status.

2. Setting Poll Interval

Parameter	Description	Default Value	Notes
poll	Interval in seconds between polling for job completion	`10`	Used with `async:` tasks
delay	Initial delay before starting to poll	`0`	Can be used to stagger async tasks

Example: Setting Poll Interval

- name: Run async task with custom poll interval
  command: sleep 30
  async: 60
  poll: 5

Note: The poll interval determines how frequently Ansible checks for job completion. Lower values increase API calls but provide faster feedback.

3. Using Fire and Forget

Fire-and-forget tasks in Ansible are used when you want to initiate a task without waiting for its completion. This is particularly useful for long-running operations or when the result of a task is not required for subsequent tasks.

Parameter	Description	Default Value
async	Specifies the maximum time (in seconds) to wait for the task to complete. If not specified, the task runs indefinitely.	0 (infinite)
poll	Defines how often (in seconds) to check the status of the async task. Setting this to 0 makes it fire and forget.	15

Example: Fire and Forget Task

- name: Start a long-running process
  command: /bin/sleep 300
  async: 300
  poll: 0

Note: When poll: 0 is used, Ansible does not wait for the task to complete and immediately moves to the next task. The status of such tasks can be checked later using async_status.

Example: Checking Async Task Status

- name: Check status of async task
  async_status:
    jid: "{{ async_result.ansible_job_id }}"
  register: job_result
  until: job_result.finished
  retries: 5
  delay: 5

4. Checking Async Status

Property	Description	Values
ansible_async_dir	Directory where async job results are stored	`/tmp/ansible_async`
ansible_async_jid	Job ID returned by async task	`1234567890`
ansible_async_result	Result of the async task	`{"changed": true, "msg": "Task completed"}`

Example: Checking Async Status

- name: Start long running task
  command: sleep 30
  async: 60
  poll: 0
  register: async_result

- name: Check async status
  async_status:
    jid: "{{ async_result.ansible_async_jid }}"
  register: job_result
  until: job_result.finished
  retries: 5
  delay: 5

- name: Display result
  debug:
    msg: "Task completed with result: {{ job_result.ansible_async_result }}"

5. Registering Async Job ID

Property	Description	Value
async_job_id	Identifier for the asynchronous job	`string`
job_status	Current status of the async job	`running \| completed \| failed`

Example: Registering Async Job ID

- name: Start async task
  command: /bin/sleep 30
  async: 30
  poll: 0
  register: async_result

- name: Use registered job ID
  debug:
    msg: "Async job started with ID: {{ async_result.ansible_job_id }}"

6. Waiting for Completion

Parameter	Description	Default	Notes
async	Maximum number of seconds to wait for task completion	0 (no timeout)	Set to 0 for indefinite wait
poll	How often to check for task completion (in seconds)	10	Used with `async`

Example: Waiting for Async Task Completion

- name: Start async job
  command: sleep 30
  async: 60
  poll: 5
  register: async_result

- name: Wait for completion
  async_status:
    jid: "{{ async_result.ansible_job_id }}"
  register: job_result
  until: job_result.finished
  retries: 10
  delay: 5

Note: The until loop ensures the task waits until completion or timeout.

Key Points

async sets the maximum wait time in seconds
poll controls how frequently to check for completion
Use async_status module to query job status
until loop with job_result.finished ensures completion

7. Setting Async Timeout

Parameter	Description	Default Value	Notes
async	Maximum time (in seconds) to wait for the task to complete	0 (no timeout)	Set to 0 for no timeout, otherwise specify integer in seconds
poll	How often (in seconds) to check the task status	15 seconds	Used in conjunction with `async`

Example: Setting Async Timeout

- name: Run a long-running task with timeout
  command: /bin/sleep 300
  async: 120
  poll: 10

Note: The async parameter defines the maximum time to wait for a task to complete. If the task does not finish within this time, it will be marked as failed.

8. Using Async with Loops

Option	Values	Description
async	`30`	Maximum time in seconds to wait for the task to complete
poll	`1`	How often (in seconds) to check the task status

Example: Using async with loop

- name: Run async task in loop
  uri:
    url: https://httpbin.org/delay/2
    method: GET
  async: 30
  poll: 1
  register: result

- name: Wait for async task to complete
  async_status:
    jid: "{{ result.ansible_job_id }}"
  register: job_result
  until: job_result.finished
  retries: 5
  delay: 1

Note: The async and poll options are used to run tasks asynchronously. The async_status module is used to check the status of the async task.

Warning: Be cautious when using async with loops as it can lead to resource exhaustion if not managed properly.

9. Running Long Tasks

Parameter	Description	Default	Notes
async	Maximum time (in seconds) to wait for task completion	0	Set to 0 for infinite wait, or specify a number
poll	How often (in seconds) to check task status	10	Used with `async`
background	Run task in background (non-blocking)	false	Set to `true` to run asynchronously

Example: Running a long task asynchronously

- name: Run a long-running command
  command: sleep 30
  async: 60
  poll: 5

Example: Background task with status check

- name: Start a background task
  command: /bin/bash -c 'sleep 10 && echo "Done"'
  async: 30
  poll: 2
  background: true

- name: Wait for task completion
  async_status:
    jid: "{{ async_result.ansible_job_id }}"
  register: job_result
  until: job_result.finished
  retries: 10

Note: The async and poll parameters are used together to manage long-running tasks. The async parameter sets the maximum wait time, and poll determines how frequently to check for completion.

Warning: If a task exceeds the async timeout, it will be marked as failed. Ensure that your timeout values are sufficient for the task duration.

10. Handling Async Failures

Property	Description	Values
async	Specifies the async task timeout in seconds	`30`
poll	How often to check the task status (in seconds)	`1`
fail_on_non_zero_rc	Whether to fail if the task exits with non-zero return code	`true`

Example: Async Task with Failure Handling

- name: Run async command
  command: sleep 10 && exit 1
  async: 30
  poll: 2
  register: result
  ignore_errors: true

- name: Check if async task failed
  debug:
    msg: "Async task failed with rc {{ result.rc }}"
  when: result.failed

Note: Use ignore_errors: true to prevent playbook from failing on async task errors.

Async Failure Handling Best Practices

Always set ignore_errors: true when handling async failures
Use register to capture task results for error analysis
Implement custom error handling logic using when conditions

11. Cleaning Up Async Jobs

Property	Description	Default Value	Notes
async_status	Module to check the status of an async job	n/a	Used after starting an async task to check its status
async_dir	Directory where async job results are stored	`/tmp/ansible_async`	Can be customized for different storage locations

Example: Cleaning Up Async Jobs

- name: Start an async job
  command: sleep 300
  async: 360
  poll: 0
  register: async_result

- name: Check job status
  async_status:
    jid: "{{ async_result.ansible_job_id }}"
  register: job_status
  until: job_status.finished
  retries: 5
  delay: 5

- name: Clean up async job results
  file:
    path: "/tmp/ansible_async/{{ async_result.ansible_job_id }}"
    state: absent

Note: Async job results are automatically cleaned up after a period, but manual cleanup can be performed using the file module to remove job result directories.