From 446027341a2811b4f602e5c4c458ca535e416d6f Mon Sep 17 00:00:00 2001 From: Lucian Maly Date: Wed, 19 Jun 2019 06:52:01 +1000 Subject: [PATCH] Update playbooks_strategies.rst (#57784) * Update playbooks_strategies.rst ##### SUMMARY This page is very confusing and may suggest, that there is still a `serial` strategy (like it used to), but now it is just a directive of `linear` strategy. Multiple people reported this to me and it needs change. ##### ISSUE TYPE - Docs Pull Request +label: docsite_pr * Update docs/docsite/rst/user_guide/playbooks_strategies.rst Co-Authored-By: Sam Doran * Update docs/docsite/rst/user_guide/playbooks_strategies.rst Co-Authored-By: Sam Doran * Updates strategies page more broadly * incorporate samdoran feedback * fixes broken link * new page title, focus on user intent * more sdoran feedback * adds details on setting the number of forks --- .../rst/user_guide/playbooks_strategies.rst | 45 ++++++++++++------- 1 file changed, 29 insertions(+), 16 deletions(-) diff --git a/docs/docsite/rst/user_guide/playbooks_strategies.rst b/docs/docsite/rst/user_guide/playbooks_strategies.rst index f1afd52bb0e..c053dbefb01 100644 --- a/docs/docsite/rst/user_guide/playbooks_strategies.rst +++ b/docs/docsite/rst/user_guide/playbooks_strategies.rst @@ -1,39 +1,52 @@ .. _playbooks_strategies: -Strategies -=========== +Controlling playbook execution: strategies and more +=================================================== -Strategies are a way to control play execution. By default, plays run with a ``linear`` strategy, in which all hosts will run each task before any host starts the next task, using the number of forks (default 5) to parallelize. +By default, Ansible runs each task on all hosts affected by a play before starting the next task on any host, using 5 forks. If you want to change this default behavior, you can use a different strategy plugin, change the number of forks, or apply one of several play-level keywords like ``serial``. -The ``serial`` directive can 'batch' this behaviour to a subset of the hosts, which then run to -completion of the play before the next 'batch' starts. +.. contents:: + :local: -A second ``strategy`` ships with Ansible - ``free`` - which allows each host to run until the end of -the play as fast as it can.:: +Selecting a strategy +-------------------- +The default behavior described above is the :ref:`linear strategy`. Ansible offers other strategies, including the :ref:`debug strategy` (see also :ref:`playbook_debugger`) and the :ref:`free strategy`, which allows +each host to run until the end of the play as fast as it can:: - hosts: all strategy: free tasks: ... +You can select a different strategy for each play as shown above, or set your preferred strategy globally in ``ansible.cfg``, under the ``defaults`` stanza:: -Strategy Plugins -````````````````` + [defaults] + strategy = free -The strategies are implemented as plugins. In the future, new -execution strategies can be added, either locally by users or to Ansible itself by -a code contribution. +All strategies are implemented as :ref:`strategy plugins`. Please review the documentation for each strategy plugin for details on how it works. -One example is ``debug`` strategy. See :doc:`playbooks_debugger` for details. +Setting the number of forks +--------------------------- +If you have the processing power available and want to use more forks, you can set the number in ``ansible.cfg``:: + + [defaults] + forks = 30 + +or pass it on the command line: `ansible-playbook -f 30 my_playbook.yml`. + +Using keywords to control execution +----------------------------------- +Several play-level :ref:`keyword` also affect play execution. The most common one is ``serial``, which sets a number, a percentage, or a list of numbers of hosts you want to manage at a time. Setting ``serial`` with any strategy directs Ansible to 'batch' the hosts, completing the play on the specified number or percentage of hosts before starting the next 'batch'. This is especially useful for :ref:`rolling updates`. + +Other keywords that affect play execution include ``ignore_errors``, ``ignore_unreachable``, and ``any_errors_fatal``. Please note that these keywords are not strategies. They are play-level directives or options. .. seealso:: - :doc:`playbooks` + :ref:`about_playbooks` An introduction to playbooks - :doc:`playbooks_reuse_roles` + :ref:`playbooks_reuse_roles` Playbook organization by roles `User Mailing List `_ Have a question? Stop by the google group! `irc.freenode.net `_ #ansible IRC chat channel -