Serial : Limit the number of Parallel processing

By default, Ansible will try to manage all of the machines referenced in a play in parallel. For a rolling updates use case, you can define how many hosts Ansible should manage at a single time by using the ‘’serial’’ keyword:

- name: test play

  hosts: webservers

  serial: 3

In the above example, if we had 100 hosts, 3 hosts in the group ‘webservers’ would complete the play completely before moving on to the next 3 hosts.

The ‘’serial’’ keyword can also be specified as a percentage in Ansible 1.8 and later, which will be applied to the total number of hosts in a play, in order to determine the number of hosts per pass:

- name: test play

  hosts: webservers

  serial: "30%"

If the number of hosts does not divide equally into the number of passes, the final pass will contain the remainder.

As of Ansible 2.2, the batch sizes can be specified as a list, as follows:

- name: test play

  hosts: webservers

  serial:

  - 1

  - 5

  - 10

In the above example, the first batch would contain a single host, the next would contain 5 hosts, and (if there are any hosts left), every following batch would contain 10 hosts until all available hosts are used.

It is also possible to list multiple batche sizes as percentages:

- name: test play

  hosts: webservers

  serial:

  - "10%"

  - "20%"

  - "100%"

You can also mix and match the values:

- name: test play

  hosts: webservers

  serial:

  - 1

  - 5

  - "20%"

Maximum Failure Percentage

By default, Ansible will continue executing actions as long as there are hosts in the group that have not yet failed. In some situations, such as with the rolling updates described above, it may be desirable to abort the play when a certain threshold of failures have been reached. To achieve this, as of version 1.3 you can set a maximum failure percentage on a play as follows:

- hosts: webservers

  max_fail_percentage: 30

  serial: 10

In the above example, if more than 3 of the 10 servers in the group were to fail, the rest of the play would be aborted.

Note : The percentage set must be exceeded, not equaled. For example, if serial were set to 4 and you wanted the task to abort when 2 of the systems failed, the percentage should be set at 49 rather than 50.

Difference between Serial and Forks

playbooks run in a number of hosts in paralel, but the tasks are in lockstep, all hosts complete task #1 before going to task #2, but each task is run in parallel in a number of hosts == number of forks defined (default 5). So with forks = 5 each task will be done in parallel on 5 hosts at a time until all hosts are done.

serial controls how many hosts go in each batch for the full play, so if you do serial = 5, 5 hosts will do each task in lockstep until end of the play, then next 5 hosts start the play.

The output is serialized to make the console readable. In 2.0 we introduce strategies that control play executions, so the default (linear) behaves as per above, a new one called 'free' allows for each parallel host to run to the end of play w/o waiting for the other hosts to complete the same task.

Serial overrides the forks setting.