elway: add handler blocks (tier 3 idempotency) #3

New Issue

2026-04-24T10:40:42-07:00

vh commented

2026-04-24 10:40:42 -07:00

Follow-up to elway's tier 1 + tier 2 idempotency. A common Ansible pattern not yet supported:

steps:
  - name: Upload nginx config
    upload: { src: nginx.conf, dest: /etc/nginx/nginx.conf, mode: "0644" }
    sudo: true
    notify: restart nginx

  - name: Upload other config
    upload: { src: sites.conf, dest: /etc/nginx/conf.d/sites.conf, mode: "0644" }
    sudo: true
    notify: restart nginx   # same notification, only triggers handler once

handlers:
  - name: restart nginx
    shell: systemctl restart nginx
    sudo: true

Semantics

A step carries notify: <handler_name> (or a list). A handler with that name must exist.
After the steps: phase completes, for each handler that was notified by a step that ended in state changed, run it exactly once.
Handlers with states: ok / changed / failed / skipped — same reporting as regular steps.
Run before verify: so verification sees the final state.
If a step is skipped or ok, no notification fires even if the notify: field is set.

LOE

~50-80 LOC: playbook loader gets a handlers section; Step gains notify: list[str]; run_phase flags notifications; main driver adds a handlers phase after steps if any notifications accumulated.

Why file separately

Not urgent — tier 1+2 covers the homelab deploy patterns we hit most. Handler semantics matter when multiple config changes should coalesce into one service restart; for a small fleet that's a rare pattern, but not non-zero.

Follow-up to elway's tier 1 + tier 2 idempotency. A common Ansible pattern not yet supported: ```yaml steps: - name: Upload nginx config upload: { src: nginx.conf, dest: /etc/nginx/nginx.conf, mode: "0644" } sudo: true notify: restart nginx - name: Upload other config upload: { src: sites.conf, dest: /etc/nginx/conf.d/sites.conf, mode: "0644" } sudo: true notify: restart nginx # same notification, only triggers handler once handlers: - name: restart nginx shell: systemctl restart nginx sudo: true ``` ### Semantics - A step carries `notify: <handler_name>` (or a list). A handler with that name must exist. - After the `steps:` phase completes, for each handler that was notified by a step that ended in state `changed`, run it exactly once. - Handlers with states: `ok` / `changed` / `failed` / `skipped` — same reporting as regular steps. - Run before `verify:` so verification sees the final state. - If a step is `skipped` or `ok`, no notification fires even if the `notify:` field is set. ### LOE ~50-80 LOC: playbook loader gets a `handlers` section; `Step` gains `notify: list[str]`; `run_phase` flags notifications; main driver adds a `handlers` phase after `steps` if any notifications accumulated. ### Why file separately Not urgent — tier 1+2 covers the homelab deploy patterns we hit most. Handler semantics matter when multiple config changes should coalesce into one service restart; for a small fleet that's a rare pattern, but not non-zero.

vh added the enhancement label 2026-04-24 10:40:42 -07:00

vh referenced this issue

2026-04-24 10:40:43 -07:00

elway: add `register:` to capture step output into playbook vars #4

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: vh/esh-pfi-infrastructure#3