
Serial sets the number or percentage of target systems that tasks in a playbook will be run against.
Let's say you have the following playbook, which contains 2 tasks using ansible.builtin.file.
---
- hosts: all
tasks:
- name: create /tmp/foo.txt
ansible.builtin.file:
path: /tmp/foo.txt
state: touch
- name: remove /tmp/foo.txt
ansible.builtin.file:
path: /tmp/foo.txt
state: absent
...
Let's also say you have 2 target servers defined in your default hosts file or your own inventory file.
all:
hosts:
server1.example.com:
server2.example.com:
Without defining serial, the first task will run against both servers, and then the second task will run against both servers. The play recap should look something like this.
PLAY [all]
TASK [create /tmp/foo.txt]
changed: [server1.example.com]
changed: [server2.example.com]
TASK [remove /tmp/foo.txt]
changed: [server1.example.com]
changed: [server2.example.com]
PLAY RECAP
server1.example.com : ok=2 changed=2 unreachable=0 failed=0
server2.example.com : ok=2 changed=2 unreachable=0 failed=0
Now let's include serial: 1 in the playbook, to tell Ansible to run all of the plays against one target server at a time.
---
- hosts: all
serial: 1
tasks:
- name: create /tmp/foo.txt
file:
path: /tmp/foo.txt
state: touch
- name: remove /tmp/foo.txt
file:
path: /tmp/foo.txt
state: absent
...
The play recap should look something like this. Now, all of the tasks in the play were run against server1 first, and then all of the tasks in the play were run against server 2.
PLAY [all]
TASK [create /tmp/foo.txt]
changed: [server1.example.com]
TASK [create /tmp/foo.txt]
changed: [server1.example.com]
PLAY [all]
TASK [remove /tmp/foo.txt]
changed: [server2.example.com]
TASK [remove /tmp/foo.txt]
changed: [server2.example.com]
PLAY RECAP
server1.example.com : ok=2 changed=2 unreachable=0 failed=0
server2.example.com : ok=2 changed=2 unreachable=0 failed=0
Additionally, serial can also take a percentage.
---
- hosts: all
serial: 25%
It is also noteworthy that the ansible_play_batch variable will contain the target servers in each "batch".
---
- hosts: all
serial: 2
tasks:
- debug:
var: ansible_play_batch
...
Which should return something like this.
PLAY [all]
ok: [server1.example.com] => {
"ansible_play_batch": [
"server1.example.com"
]
}
ok: [server1.example.com] => {
"ansible_play_batch": [
"server1.example.com"
]
}
PLAY [all]
ok: [server2.example.com] => {
"ansible_play_batch": [
"server2.example.com"
]
}
ok: [server2.example.com] => {
"ansible_play_batch": [
"server2.example.com"
]
}
PLAY RECAP
server1.example.com : ok=2 changed=0 unreachable=0 failed=0
server2.example.com : ok=2 changed=0 unreachable=0 failed=0
Did you find this article helpful?
If so, consider buying me a coffee over at