online posts 16
ansible 101 for networking

Ansible Handlers, Tags and block/rescue on Network Devices (Ansible 101 for Networking, Lesson 5)

Save the config only when something actually changed with handlers, run just part of a playbook with tags, and recover when a change fails halfway with block, rescue and always. Lesson 5 of Ansible 101 for networking, with a hands-on lab.

A playbook with a handler firing once at the end, tags selecting tasks, and a rescue rolling back a failed change
lesson 5 of 8 · course Ansible 101 for networking
  1. 1Hello, Ansible
  2. 2Your first playbook
  3. 3Variables and facts
  4. 4Loops, conditionals, templates
  5. 5Handlers, tags, errors
  6. 6Roles and collections
  7. 7Secrets
  8. 8Run it like production
course overview →

By the end of lesson 4 the playbooks configure every port on every switch from data. They’re also missing three things every network engineer cares about the moment the automation touches production:

  • The config isn’t saved. Reboot a switch and the changes are gone.
  • You can’t run part of a playbook. Fixing one port description means re-running everything.
  • Nothing handles a change that fails halfway, which is the one that actually ruins your night.

This lesson fixes all three.


Handlers: do it once, only if something changed

On these switches, as on most classic CLIs, your playbooks change the running-config. Reboot and the switch loads the startup-config, so anything nobody saved with write memory is gone. Saving the config after every task is wasteful, and saving it when nothing changed is worse: it rewrites the startup config for no reason, and on some platforms it’s slow. What you want is “if anything changed, save once, at the end”. That’s a handler.

- name: Base config
  hosts: fabric
  gather_facts: false

  tasks:
    - name: NTP servers, from group_vars
      cisco.ios.ios_ntp_global:
        config:
          servers: "{{ ntp_servers }}"
      notify: Save the running config

    - name: Where the switch lives, from host_vars
      cisco.ios.ios_config:
        lines:
          - "snmp-server location {{ location }}"
      notify: Save the running config

  handlers:
    - name: Save the running config
      cisco.ios.ios_command:
        commands:
          - write memory

A handler is a task that only runs when another task notifies it, and only if that task reported changed. Both tasks above notify the same handler, but it runs once, after all the tasks have finished, as a RUNNING HANDLER [Save the running config] section at the end of the output. If only leaf1’s NTP had drifted, only leaf1 would change, and only leaf1 would save.

Run it again: both tasks report ok, nothing notifies, and the handler doesn’t run at all. That’s exactly right. Two details are worth a second look:

  • The handler reports ok, not changed. ios_command can’t know whether write memory changed anything; it only knows the command ran. (Remember lesson 2: changed is only as honest as the module.)
  • The handler is matched by name. Typo the name in notify and Ansible stops with an error saying the requested handler wasn’t found, which is the behavior you want.

Here’s a trap I walked into building the lab: if your switches already have the config, adding a handler and running the playbook does nothing at all, because nothing changes, so nothing notifies. That’s correct behavior, and it confuses everyone the first time. To see a handler fire, you need a change for it to react to.

(Some modules offer a shortcut: cisco.ios.ios_config has save_when: changed. It’s handy. Handlers are the general tool; they work for any module, on any platform, and for things other than saving.)


Tags: run part of a playbook

Tag your tasks, and you can run just the ones you need:

    - name: Description and no shutdown, one port at a time
      cisco.ios.ios_interfaces:
        ...
      tags: [descriptions]

    - name: Jumbo MTU on uplinks only
      cisco.ios.ios_interfaces:
        ...
      tags: [mtu]

--tags descriptions on the command line runs only the tasks tagged descriptions; --skip-tags mtu runs everything except the MTU task. Add --list-tasks and Ansible prints the tasks a run would include and touches nothing, which is how you check what a tag selects before you trust it:

playbook: playbooks/interfaces.yml

  play #1 (fabric): Interfaces	TAGS: []
    tasks:
      Description and no shutdown, one port at a time	TAGS: [descriptions]

Tags are great for speed and for scoping a change (“only the NTP part tonight”). They’re also easy to abuse. Tag by what the task configures (ntp, descriptions, mtu), not by when you run it (tuesday, quick). And remember that a tag filter can skip a task another task depends on; --list-tasks is how you catch that before it catches you.


When a change fails halfway

This is the one that matters. A change with two steps, where the second one fails, leaves the device in a state nobody designed: not the old config, not the new one. Ansible’s answer is block, rescue and always, which work like try, except and finally:

    - name: Change the uplinks, then roll back if anything fails
      block:
        - name: Step 1 · lower the uplink MTU (this works)
          cisco.ios.ios_interfaces:
            config:
              - name: GigabitEthernet1
                mtu: 1500

        - name: Step 2 · an MTU no switch supports (this fails)
          cisco.ios.ios_interfaces:
            config:
              - name: GigabitEthernet1
                mtu: 99999

      rescue:
        - name: Roll back to the known-good MTU
          cisco.ios.ios_interfaces:
            config:
              - name: GigabitEthernet1
                mtu: 9100

      always:
        - name: Read the port's config back
          cisco.ios.ios_command:
            commands:
              - show running-config interface GigabitEthernet1
          register: uplink_config

Step 1 works: the uplink’s MTU drops to 1500. Step 2 fails, because the switch rejects the value with % Invalid input detected, exactly as it would if you typed it. Without a rescue, that’s where Ansible stops for that host, and the uplink stays at 1500: not the old config, not the new one.

With the rescue, Ansible runs the rescue tasks for that host instead, which put the MTU back to 9100. The always tasks run either way and read the port’s config back from the switch, so every run ends with proof of the state it left behind. (register keeps the show command’s output, as promised in lesson 3.) Inside a rescue, ansible_failed_task is the task that failed, which makes for an honest log message.

The recap tells the story: failed=0, rescued=1. Something went wrong, and it was handled. That distinction matters in a pipeline: a rescued play is a success with a story, not a red build.

A classic CLI applies each line the moment it’s accepted. The switch refused step 2’s line, so nothing from step 2 took, but step 1 was already live. That’s why the rescue matters.

Rollback is a design decision, not a keyword

rescue doesn’t magically undo anything. It runs whatever you wrote. In the lab, the rescue re-applies a known-good value, which is simple and honest. Real options, from simplest to strongest:

  1. Re-apply the known-good values (this post). Easy; you have to know what “good” was.
  2. Re-run the whole playbook from Git. If your playbooks describe the full intended state, the last good commit is your rollback.
  3. Let the device do it. Platforms with a candidate config often support a confirmed commit: apply the change, and if it isn’t confirmed within N seconds, the device reverts on its own. A CLI that applies lines as you type them, like the lab’s, has no commit to confirm, so this one depends on your platform. Where it exists, it’s the one that saves you when the change cuts off your own management access.

Where people get it wrong

1. ignore_errors: true as a lifestyle

It turns every failure into a shrug, and the play carries on as if the change worked. If a failure is expected and safe, handle it with rescue or failed_when and say why in the task name. If it isn’t, let it fail.

2. Saving config in every task

A save after every change is slow, noisy in the recap, and leaves you no way to tell “saved because something changed” from “saved because it always does”. Notify a handler.

3. Handlers that never run

A play that fails before the end doesn’t run its handlers by default, so a change that applied before the failure is never saved. If that matters, use force_handlers: true on the play, or meta: flush_handlers at the point where you want pending handlers to run.

4. Tags as a substitute for structure

If every run uses --tags, the playbook is really three playbooks. Split it. That’s lesson 6.


Try it

Chapter 5 of the lab adds the save handler to the base playbook, tags the interface tasks, and has you finish the rescue and always sections so a failed change leaves the uplinks the way it found them.

Next, in lesson 6, the playbooks become roles: reusable units with their own defaults, handlers and tasks, and the precedence rule that makes role defaults so useful.