listen topics as a handler interface · Ansible

notify: Reload nginx names an implementation. The task says which handler to run, which means the task knows how the service is restarted, what the handler is called, and — implicitly — that there is exactly one of it.

listen inverts that. A handler declares which topic it subscribes to, and a task notifies the topic. The task now says what needs to happen and stays silent on how many handlers implement it or what they are called.

The mechanism

Read-only / Safeone notification, two handlers— Verified on ansible-core 2.21.3 with debug handlers so nothing is modified.

- name: Listen topics and handler chaining
hosts: local
gather_facts: false
tasks:
  - name: Notify a topic rather than a name
    ansible.builtin.debug:
      msg: t
    changed_when: true
    notify: restart web stack

handlers:
  - name: Reload the cache layer
    ansible.builtin.debug:
      msg: cache reloaded
    listen: restart web stack

  - name: Reload the web server
    ansible.builtin.debug:
      msg: web reloaded
    listen: restart web stack

Read-only / Safeexecuted on ansible-core 2.21.3— One notify, two RUNNING HANDLER lines, in the order the handlers are defined.

$ ansible-playbook -i inv.ini listen.yml

TASK [Notify a topic rather than a name] ***************************************
changed: [localhost]

RUNNING HANDLER [Reload the cache layer] ***************************************
ok: [localhost]

RUNNING HANDLER [Reload the web server] ****************************************
ok: [localhost]

The handler names still appear in the output — that is what identifies them for a reader of the run log. Only the notification uses the topic.

A handler may carry both a name and a listen, and can then be notified either way. It may also listen to more than one topic:

Service impact possiblea handler on two topics— Notifying either topic runs this handler. Both notified in the same flush still run it once.

handlers:
- name: Reload nginx
  ansible.builtin.systemd_service:
    name: nginx
    state: reloaded
  listen:
    - restart web stack
    - tls material changed

Why a topic is a stabler contract

The operational argument is about who owns which side of the boundary.

Consider a webserver role with a handler called Reload nginx, and a separate play or role whose tasks deploy TLS certificates and notify it. The certificate tasks now depend on a string defined inside somebody else’s role. When that role is refactored — nginx replaced with Caddy, the handler renamed to Reload the reverse proxy, the reload split into two steps — every notifier breaks.

And it breaks in the worst available way. A notify naming a handler that no longer exists aborts the run:

Read-only / Safea notify that names nothing— Verified on ansible-core 2.21.3. The playbook passes --syntax-check with exit 0 and then aborts at the first notifying task with exit 1.

$ ansible-playbook -i inv.ini typo.yml

PLAY [A notify that names no handler] ******************************************

TASK [Deploy the configuration] ************************************************
[ERROR]: The requested handler 'Reload the sevrice' was not found in either the main handlers list nor in the listening handlers list

An immediate abort is at least visible. But it happens at run time on whichever host reaches that task first, potentially mid-rollout, with part of the fleet already changed.

With a topic, the role publishes restart web stack as its interface and is free to rename, split or replace the handlers behind it. The notifiers keep working because they never referred to an implementation in the first place.

The fan-out is the point, and also the risk

One notification running four handlers is convenient. It is also four things happening on the host from one line of YAML that does not say so.

Service impact possiblewhat one notify can be worth— A single notify: tls material changed on a certificate task. Read the handlers section to know what that costs.

handlers:
- name: Reload nginx
  ansible.builtin.systemd_service:
    name: nginx
    state: reloaded
  listen: tls material changed

- name: Restart the API service
  ansible.builtin.systemd_service:
    name: billing-api
    state: restarted
  listen: tls material changed

- name: Restart the message broker
  ansible.builtin.systemd_service:
    name: broker
    state: restarted
  listen: tls material changed

nginx reloads without dropping connections. billing-api and broker are full restarts. A certificate renewal that renders every 60 days has just become a three-service restart across every host that renewed — and the task that triggered it says only notify: tls material changed.

The rule that follows: the blast radius of a notify is the handlers section, not the notify line. When reviewing a change that adds a notify, read the subscribers.

Under the hood

Ansible keeps two lookup structures for a play: handlers by name, and handlers by topic. The error text names both — “not found in either the main handlers list nor in the listening handlers list” — because resolution consults them in that order.

Both resolve to entries in the same ordered handler list, which is why listen changes nothing about execution order. Two handlers on one topic run in the order they were defined, and a topic that fans out to three handlers interleaves with any name-notified handlers according to the same single list. There is no separate schedule for topic subscribers.

Resolution into that shared list happens at play assembly time, before any host is contacted, which is why a topic cannot depend on a host variable and why an unresolvable notify aborts the run rather than failing one host.

It is also why name collisions behave the way they do. Two handlers defined with the same name in one play are two entries in the list and one name in the lookup: notifying that name on 2.21.3 ran the first definition, once, with no warning that the second existed. The next lesson is about how two roles produce exactly that situation.

What happens if nothing subscribes to a topic?

The run aborts with the same error as a misspelled handler name.

There is no “topic with no subscribers is a no-op” behaviour, and there is no warning. This is a reasonable design — a topic nobody implements almost always means a role was removed, a rename went half-finished, or a play was assembled without the role that provides the handler — but it means a topic is not a safe optional hook.

If a notify must be tolerant of a missing implementation, the honest way to express that is a handler that always exists in the play and does nothing meaningful when the relevant variable is unset, guarded with when. A topic with no subscriber will stop the run.

Note also that --syntax-check does not detect either case. Verified on 2.21.3: a playbook whose notify names a handler that does not exist passes --syntax-check with exit 0, then aborts at the first notifying task on a real run. Syntax checking parses structure; it does not resolve notifications.

The practical consequence is that an unresolvable notify is only found by running the play. A CI job that executes the play against a disposable test host is the cheap detection; static checking alone will not find it.

The mechanism

Why a topic is a stabler contract

The fan-out is the point, and also the risk

Knowledge check