Ansible Async and Poll: Handle Long Running Tasks

Managing long running tasks in Ansible is often challenging due to default timeout limitations. With async and poll, Ansible provides the flexibility to run tasks asynchronously, monitor their progress, and ensure efficient playbook execution.

In this guide, we’ll delve into how to use async and poll in Ansible effectively.

What Are Async and Poll?

The async parameter allows you to specify the maximum time (in seconds) that a task can run in the background. By using async, tasks that would normally exceed Ansible’s timeout (usually 10 minutes) can complete without causing errors.

The poll parameter determines how often Ansible checks the status of the task. Setting poll: 0 tells Ansible to initiate the task and immediately move to the next task, effectively running the task in the background.

By combining these parameters, you can achieve non-blocking automation while monitoring tasks on your terms.

Basic Syntax

The syntax for using async and poll is simple:

- name: Run a long-running task
  command: command_to_run
  async: timeout_in_seconds
  poll: poll_interval
  register: task_result

Explanation:

• The async parameter specifies the maximum time (in seconds) the task is allowed to run.
• The poll parameter controls how often Ansible checks for the task’s status. A value of poll: 0 tells Ansible not to wait for the task to complete. Instead, Ansible starts the task and immediately moves on.
• The register directive stores the output of the task in a variable (task_result).

Example 1: Run a Task in the Background

In this example, we’ll run a task that sleeps for 300 seconds in the background. Ansible won’t wait for the task to finish and will immediately proceed to the next task.

Here is the example playbook:

- name: Run a background task
  hosts: localhost
  tasks:
    - name: Run a background task
      command: sleep 300
      async: 600
      poll: 0
      register: background_task

    - name: Display async task ID
      debug:
        msg: "The async task ID is {{ background_task.ansible_job_id }}"

Example 2: Check the Status of an Async Task

After running a task in the background, you can check its status using the async_status module.

In this example, the status output shows whether the task is finished and includes additional details such as return code (rc) and output (stdout and stderr).

- name: Check async task status
  hosts: localhost
  tasks:
    - name: Run a background task
      command: sleep 300
      async: 600
      poll: 0
      register: background_task

    - name: Check the status of the background task
      async_status:
        jid: "{{ background_task.ansible_job_id }}"
      register: task_status
      until: task_status.finished
      retries: 10
      delay: 30

    - name: Display task result
      debug:
        var: task_status

Example 3: Run and Poll Long-Running Tasks

This example demonstrates running a task with a polling interval, where Ansible checks the status every 10 seconds.

- name: Run a long-running task with polling
  hosts: localhost
  tasks:
    - name: Run a long task
      command: sleep 180
      async: 300
      poll: 10
      register: long_task_result

    - name: Display the result of the long-running task
      debug:
        var: long_task_result

Here, Ansible ensures the task is completed, captures the result, and displays it using the debug module.

Example 4: Execute Multiple Async Tasks

You can execute multiple long-running tasks asynchronously using a loop.

- name: Start multiple async tasks
  hosts: localhost
  tasks:
    - name: Run async tasks in parallel
      command: sleep 120
      async: 300
      poll: 0
      register: async_results
      with_items:
        - task1
        - task2
        - task3

    - name: Display async task IDs
      debug:
        var: async_results

This playbook runs multiple asynchronous tasks in parallel, each with a sleep 120 command, and registers their results (including task IDs) to display them using the debug module.

Conclusion

The combination of async and poll in Ansible empowers you to handle long-running tasks efficiently. By understanding and applying these features, you can streamline your playbooks, avoid unnecessary delays, and gain better control over task execution. Experiment with the examples provided and adapt them to suit your automation workflows.

FAQs