diff --git a/knowledge base/ansible.md b/knowledge base/ansible.md
index 38ae1dd..557c387 100644
--- a/knowledge base/ansible.md
+++ b/knowledge base/ansible.md
@@ -10,14 +10,16 @@
1. [Loops](#loops)
1. [Validation](#validation)
1. [Assertions](#assertions)
+1. [Asynchronous actions](#asynchronous-actions)
+ 1. [Run tasks in parallel](#run-tasks-in-parallel)
1. [Error handling](#error-handling)
1. [Using blocks](#using-blocks)
1. [Output formatting](#output-formatting)
1. [Handlers](#handlers)
1. [Roles](#roles)
- 1. [Get roles](#get-roles)
- 1. [Assign roles](#assign-roles)
- 1. [Role dependencies](#role-dependencies)
+ 1. [Get roles](#get-roles)
+ 1. [Assign roles](#assign-roles)
+ 1. [Role dependencies](#role-dependencies)
1. [Create custom filter plugins](#create-custom-filter-plugins)
1. [Execution environments](#execution-environments)
1. [Secrets management](#secrets-management)
@@ -450,6 +452,86 @@ Return a boolean result.
success_msg: What to say if all of the above conditions succeed
```
+## Asynchronous actions
+
+Refer [Asynchronous actions and polling].
+
+Executing tasks in the background will return a Job ID that can be polled for information about that task.
+Polling keeps the connection to the remote node open between polls.
+
+Use the `async` keyword in playbook tasks.
+Leaving it off makes tasks run synchronously, which is Ansible's default.
+
+> As of Ansible 2.3, `async` does **not** support check mode and tasks using it **will fail** when run in check mode.
+
+Asynchronous tasks will create temporary async job cache file (in `~/.ansible_async/` by default).
+When asynchronous tasks complete **with** polling enabled, the related temporary async job cache file is automatically
+removed. This does **not** happen for tasks that do **not** use polling.
+
+```sh
+# Execute long running operations asynchronously in the background.
+ansible 'all' -B '3600' -P '0' -a '/usr/bin/long_running_operation --do-stuff' # no polling
+ansible 'all' -B '1800' -P '60' -a '/usr/bin/long_running_operation --do-stuff' # with polling
+
+# Check on background jobs' status.
+ansible 'web1.example.com' -m 'async_status' -a 'jid=488359678239.2844'
+```
+
+```yaml
+---
+- tasks:
+ - name: Simulate long running op (15 sec), wait for up to 45 sec, poll every 5 sec
+ ansible.builtin.command: /bin/sleep 15
+ async: 45
+ poll: 5
+```
+
+The default poll value is set by the `DEFAULT_POLL_INTERVAL` setting.
+There is **no** default for `async`'s time limit.
+
+Asynchronous playbook tasks **always** return changed.
+
+### Run tasks in parallel
+
+Use `async` with `poll` set to _0_.
+When `poll` is _0_, Ansible starts the task and immediately moves on to the next one with**out** waiting for a result
+from the first.
+Each asynchronous task runs until it either completes, fails or times out (running longer than the value set for its
+`async`). Playbook runs end with**out** checking back on asynchronous tasks.
+
+```yaml
+---
+- tasks:
+ - name: Simulate long running op (15 sec), allow to run for 45 sec, fire and forget
+ ansible.builtin.command: /bin/sleep 15
+ async: 45
+ poll: 0
+```
+
+Operations requiring exclusive locks, such as YUM transactions, will make successive operations that require those files
+wait or fail.
+
+Synchronize asynchronous tasks by registering them to obtain their job ID and using it with the `async_status` module in
+later tasks:
+
+```yaml
+- tasks:
+ - name: Run an async task
+ ansible.builtin.yum:
+ name: docker-io
+ state: present
+ async: 1000
+ poll: 0
+ register: yum_sleeper
+ - name: Check on an async task
+ async_status:
+ jid: "{{ yum_sleeper.ansible_job_id }}"
+ register: job_result
+ until: job_result.finished
+ retries: 100
+ delay: 10
+```
+
## Error handling
### Using blocks
@@ -624,6 +706,8 @@ In playbooks:
message: some message
```
+Role assignments can**not** be parallelized at the time of writing.
+
### Role dependencies
Set them up in `role/meta/main.yml`:
@@ -1346,6 +1430,7 @@ Solution: use a version of `ansible-core` lower than 2.17.
- [Protecting sensitive data with Ansible vault]
- [Ansible Vault tutorial]
- [Ansible Vault with AWX]
+- [Asynchronous actions and polling]
[8 ways to speed up your ansible playbooks]: https://www.redhat.com/sysadmin/faster-ansible-playbook-execution
[ansible galaxy user guide]: https://docs.ansible.com/ansible/latest/galaxy/user_guide.html
+[asynchronous actions and polling]: https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_async.html
[automating helm using ansible]: https://www.ansible.com/blog/automating-helm-using-ansible
[blocks]: https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_blocks.html
[collections index]: https://docs.ansible.com/ansible/latest/collections/index.html