From 2f3e9a38b6f9483a4ae65a9b5197f4b52dc485f3 Mon Sep 17 00:00:00 2001
From: "Jon \"The Nice Guy\" Spriggs" <jon@sprig.gs>
Date: Fri, 8 Jan 2021 22:38:44 +0000
Subject: [PATCH] Backport/2.10/73079 (#73165)

* Update apt.py, add an example that references the suggested workaround in #25414
(cherry picked from commit 1e1b8e7acae7b2322a004a563a86548e78a20216)
(cherry picked from commit 180bbfed6a8fc2ca0ba5614db2b27391350a200d)

* Added changelog fragment
---
 .../73079-update-documentation-around-apt-lock.yml    |  2 ++
 lib/ansible/modules/apt.py                            | 11 +++++++++++
 2 files changed, 13 insertions(+)
 create mode 100644 changelogs/fragments/73079-update-documentation-around-apt-lock.yml

diff --git a/changelogs/fragments/73079-update-documentation-around-apt-lock.yml b/changelogs/fragments/73079-update-documentation-around-apt-lock.yml
new file mode 100644
index 00000000000..8593b7a9ea6
--- /dev/null
+++ b/changelogs/fragments/73079-update-documentation-around-apt-lock.yml
@@ -0,0 +1,2 @@
+bugfixes:
+- "Documentation change to the apt module to reference lock files (https://github.com/ansible/ansible/issues/73079)."
diff --git a/lib/ansible/modules/apt.py b/lib/ansible/modules/apt.py
index 7e9fed6e10d..144a27d2ba5 100644
--- a/lib/ansible/modules/apt.py
+++ b/lib/ansible/modules/apt.py
@@ -245,6 +245,17 @@ EXAMPLES = '''
   apt:
     autoremove: yes
 
+# Sometimes apt tasks fail because apt is locked by an autoupdate or by a race condition on a thread.
+# To check for a lock file before executing, and keep trying until the lock file is released:
+- name: Install packages only when the apt process is not locked
+  apt:
+    name: foo
+    state: present
+  register: apt_action
+  retries: 100
+  until: apt_action is success or ('Failed to lock apt for exclusive operation' not in apt_action.msg and '/var/lib/dpkg/lock' not in apt_action.msg)
+
+
 '''
 
 RETURN = '''