Add run_once task key

This caused the task to act like  bypass host loop plugin and
execute only on a single host. Can be used with delegate_to

1 files changed, 34 insertions, 0 deletions

diff --git a/docsite/rst/playbooks_delegation.rst b/docsite/rst/playbooks_delegation.rst
index e298ebd690..7fa49733a7 100644
--- a/docsite/rst/playbooks_delegation.rst
+++ b/docsite/rst/playbooks_delegation.rst
@@ -118,6 +118,40 @@ Here is an example::
 Note that you must have passphrase-less SSH keys or an ssh-agent configured for this to work, otherwise rsync
 will need to ask for a passphrase.
 
+.. _run_once:
+
+Run Once
+````````
+
+In some cases there may be a need to only run a task one time and only on one host. This can be achieved
+by configuring "run_once" on a task::
+
+    ---
+    # ...
+
+      tasks:
+
+        # ...
+
+        - command: /opt/application/upgrade_db.py
+          run_once: true
+
+        # ...
+
+This can be optionally paired with "delegate_to" to specify an individual host to execute on::
+
+        - command: /opt/application/upgrade_db.py
+          run_once: true
+          delegate_to: web01.example.org
+
+When "run_once" is not used with "delegate_to" it will execute on the first host, as defined by inventory,
+in the group(s) of hosts targeted by the play. e.g. webservers[0] if the play targeted "hosts: webservers".
+
+This aproach is similar, although more concise and cleaner than applying a conditional to a task such as::
+
+        - command: /opt/application/upgrade_db.py
+          when: inventory_hostname == webservers[0]
+
 .. _local_playbooks:
 
 Local Playbooks