Backport/2.10/73079 (#73165)

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

* Added changelog fragment

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)."

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 = '''