From 68e7045a3835a0e510aa0dcd5d0871d22c961b34 Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Thu, 22 Mar 2018 09:37:14 -0400 Subject: [PATCH] try to clarify run_once and forall! (#37754) * try to clarify run_once and forall! * fixed hidden tls middle man * make when note * Minor edit * Typo fix --- docs/docsite/keyword_desc.yml | 2 +- .../rst/user_guide/playbooks_delegation.rst | 24 ++++++++++++------- 2 files changed, 16 insertions(+), 10 deletions(-) diff --git a/docs/docsite/keyword_desc.yml b/docs/docsite/keyword_desc.yml index 583ffb2e690..769be8ecc79 100644 --- a/docs/docsite/keyword_desc.yml +++ b/docs/docsite/keyword_desc.yml @@ -57,7 +57,7 @@ register: Name of variable that will contain task status and module return data. rescue: List of tasks in a :term:`block` that run if there is a task error in the main :term:`block` list. retries: "Number of retries before giving up in a :term:`until` loop. This setting is only used in combination with :term:`until`." roles: List of roles to be imported into the play -run_once: Boolean that will bypass the host loop, forcing the task to execute on the first host available and will also apply any facts to all active hosts. +run_once: Boolean that will bypass the host loop, forcing the task to attempt to execute on the first host available and afterwards apply any results and facts to all active hosts in the same batch. serial: | Explicitly define how Ansible batches the execution of the current play on the play's target diff --git a/docs/docsite/rst/user_guide/playbooks_delegation.rst b/docs/docsite/rst/user_guide/playbooks_delegation.rst index b1dd0cb26f2..60b5d2b4ed9 100644 --- a/docs/docsite/rst/user_guide/playbooks_delegation.rst +++ b/docs/docsite/rst/user_guide/playbooks_delegation.rst @@ -203,8 +203,8 @@ This way you can lookup `hostvars['dbhost1']['default_ipv4']['address']` even th 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:: +In some cases there may be a need to only run a task one time for a batch of hosts. +This can be achieved by configuring "run_once" on a task:: --- # ... @@ -218,25 +218,31 @@ by configuring "run_once" on a task:: # ... -This can be optionally paired with "delegate_to" to specify an individual host to execute on:: +This directive forces the task to attempt execution on the first host in the current batch and then applies all results and facts to all the hosts in the same batch. + +This approach is similar to applying a conditional to a task such as:: - command: /opt/application/upgrade_db.py - run_once: true - delegate_to: web01.example.org + when: inventory_hostname == webservers[0] -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". +But the results are applied to all the hosts. -This approach is similar to applying a conditional to a task such as:: +Like most tasks, this can be optionally paired with "delegate_to" to specify an individual host to execute on:: - command: /opt/application/upgrade_db.py - when: inventory_hostname == webservers[0] + run_once: true + delegate_to: web01.example.org + +As always with delegation, the action will be executed on the delegated host, but the information is still that of the original host in the task. .. note:: When used together with "serial", tasks marked as "run_once" will be run on one host in *each* serial batch. If it's crucial that the task is run only once regardless of "serial" mode, use :code:`when: inventory_hostname == ansible_play_hosts[0]` construct. +.. note:: + Any conditional (i.e `when:`) will use the variables of the 'first host' to decide if the task runs or not, no other hosts will be tested. + .. _local_playbooks: Local Playbooks