Restart, reload, and doing it to everyone at once · Ansible

The handler mechanism has now been established as a change gate: the right hosts, at the right time, for the right reason. This lesson is about the two questions the mechanism does not answer for you.

What does the handler do to the service? A reload and a restart are different operations with different costs, and the module makes both look like a one-word argument.

How many hosts does it do it to, simultaneously? A handler that fires on every host in a 400-host play is a 400-host service event. The handler is correct. The blast radius is not.

`reloaded` versus `restarted`

The Linux course covers what systemd actually does for each — unit states, ExecReload, what happens to an open socket. This lesson assumes that and asks the operational question on top of it: which one should the handler ask for?

Service impact possiblethe two handlers— Same module, same service, materially different consequences for anything currently connected.

handlers:
- name: Reload nginx
  ansible.builtin.systemd_service:
    name: nginx
    state: reloaded

- name: Restart nginx
  ansible.builtin.systemd_service:
    name: nginx
    state: restarted

The distinction that matters operationally:

	`reloaded`	`restarted`
In-flight requests	Generally survive	Dropped
Listening socket	Kept open	Closed and reopened
Process identity	Same main PID, or a controlled handover	New process
Warm caches, pools, JIT state	Preserved	Lost
Applies unit-file changes	No	Yes
Applies changes to startup arguments	No	Yes
Recovers a wedged process	No	Yes

Prefer reloaded when the service supports it and the change is a configuration change. That is the majority of what a config-management handler does, and the reason to prefer it is not elegance — it is that a reload does not appear in your error budget.

Service impact possibleunit file changes need their own path— Two topics, two handlers. The config task and the unit-file task notify different things because they need different operations.

- name: Deploy the unit file
ansible.builtin.template:
  src: billing.service.j2
  dest: /etc/systemd/system/billing.service
  mode: '0644'
notify: billing unit changed

- name: Deploy the application configuration
ansible.builtin.template:
  src: billing.conf.j2
  dest: /etc/billing/billing.conf
  mode: '0640'
notify: billing config changed

handlers:
- name: Reload systemd and restart billing
  ansible.builtin.systemd_service:
    name: billing
    state: restarted
    daemon_reload: true
  listen: billing unit changed

- name: Reload billing
  ansible.builtin.systemd_service:
    name: billing
    state: reloaded
  listen: billing config changed

The other question: how many hosts?

Here is a play that is entirely correct by everything this part has taught.

Service impact possiblecorrect, and dangerous— Accurate change detection, a graceful reload, a single well-named handler. And a variable change in group_vars makes every host in the group notify it at once.

- name: Manage the reverse proxy fleet
hosts: webservers
become: true
tasks:
  - name: Deploy the site configuration
    ansible.builtin.template:
      src: site.conf.j2
      dest: /etc/nginx/conf.d/site.conf
      mode: '0644'
    notify: Reload nginx

handlers:
  - name: Reload nginx
    ansible.builtin.systemd_service:
      name: nginx
      state: reloaded

On most runs this does nothing. On the run where somebody changes a value in group_vars/webservers.yml, every host in the group reports changed and every host notifies the handler.

With the default linear strategy and the default forks of 5, the controller works through the flush five hosts at a time as fast as SSH allows. On 400 hosts that is not a rolling reload. It is a fleet-wide reload compressed into however long 400 SSH round trips take, with no gap for anything to be noticed in.

If the handler is restarted rather than reloaded, that is a fleet-wide simultaneous outage.

Knowing the number before you run

The count is knowable before the play runs, and checking it is cheap.

Read-only / Safehow many hosts could this handler act on— --list-hosts resolves the play's host pattern against the inventory and prints the effective list without connecting to anything.

$ ansible-playbook -i inventories/prod site.yml --list-hosts

playbook: site.yml

play #1 (webservers): Manage the reverse proxy fleet	TAGS: []
  pattern: ['webservers']
  hosts (412):
    web001.example.com
    web002.example.com
    web003.example.com
    ...

hosts (412) is the upper bound on the handler’s blast radius for this run. Every one of those hosts will reload nginx if the template renders differently for it.

The follow-up question — will it render differently for all of them — is answered by --check --diff, which shows the rendered difference per host without writing anything. A change to a value in group_vars that appears in the diff for all 412 hosts is a 412-host reload; a change affecting one host’s host_vars is a one-host reload. Those are very different changes and they look identical in the Git diff of the template.

Under the hood

The flush is executed by the same strategy plugin that executes tasks, with the same forks limit. With linear, the handler is run against all notified hosts as one task in lockstep, forks hosts in flight at a time; the strategy waits for the batch before starting the next one.

That is genuinely simultaneous from the service’s point of view. Reloading 400 hosts at forks: 20 means twenty reloads in flight continuously until all 400 are done — bounded by the controller’s concurrency, not by anything about the fleet’s capacity to absorb it.

Raising forks to make the run faster therefore also makes the service event sharper. That is worth stating plainly, because forks is usually discussed as a performance setting: on a play with a restart handler, it is also a blast-radius setting.

serial is the control that actually applies, because it changes the play’s structure rather than its concurrency. Under serial, each batch is a complete play execution with its own flush points, so batch one’s handlers run and complete before batch two’s tasks begin. That gives a real gap between groups of restarts — which is what makes a health check between batches meaningful, and what makes max_fail_percentage able to stop a rollout before it becomes an outage.

What happens if the service fails to come back after a restart?

The handler task fails, that host is marked failed, and — with default settings — the play continues on every other host.

That is the shape of the incident that turns a bad configuration change into a fleet-wide outage. Host one restarts, fails to start because the new configuration is rejected at load time, and reports failed. Then hosts two through 400 do exactly the same thing, because nothing about one host failing stops the others.

Three defences, each covered in its own part later, and worth knowing the names of now:

validate: on the template task, so a configuration that will not parse never reaches the destination and the handler is never notified. That is the whole subject of the next part.
serial with max_fail_percentage, so a first batch that fails stops the run instead of proceeding to the second.
A health check after the handler, so “the service restarted” is distinguished from “the service is serving”.

A validate that catches the error is the cheapest of the three by a wide margin, because it fails on the controller-rendered file before anything is activated anywhere.

Knowledge check

Why this matters

This is where the handler mechanism runs out of protection and hands the problem to you.

Everything up to here has been Ansible doing something genuinely useful on your behalf: restarting only the hosts that changed, only when they changed, deduplicated, in a predictable order. All of that is real, and it eliminates a whole category of unnecessary service disruption.

What it does not do is ask how many hosts are about to be touched at once. A single edit to a group variable turns a precise, well-designed handler into a simultaneous fleet-wide event, and there is no warning because there is nothing wrong.

So the two habits worth taking from this part: reload rather than restart wherever the service genuinely supports it, and know the host count before you run. The parts on targeting, serial execution and rolling deployments are where the second habit becomes a mechanism.

reloaded versus restarted

The other question: how many hosts?

Knowing the number before you run

Knowledge check

`reloaded` versus `restarted`