Ansible on IOS XE: changes you can read before they run

The loop script is not wrong — it is the wrong abstraction. It describes keystrokes, not state. Whether VLAN 30 exists everywhere afterwards, whether it already existed somewhere under a different name, whether one device quietly keeps a VLAN 99 alive: the script does not know, and neither does its log. Running auditable changes on that basis means reading forty terminal transcripts afterwards.

The cisco.ios collection (currently version 11.5) resolves this on two levels. For the transition there is ios_config — the docs describe it as working with IOS configuration sections “in a deterministic way”, including a backup option that saves the device's complete running-config before any change. And for the target way of working there are the resource modules: ios_vlans, ios_interfaces, ios_l2_interfaces, ios_l3_interfaces, plus ios_ospfv2, ios_acls, ios_ntp_global and more — declarative management instead of a command list.

Merged, replaced, overridden: three verbs, three contracts

Every resource module accepts the same parameter: state. It defines the contract the run makes with the device — and this is precisely where automation parts ways with scripting:

Idempotency is not an add-on here but the consequence: describe state, and you can start the same run twice — the second one simply reports no change. Which, incidentally, is the easiest quality check for a playbook: a second run straight after the first has to come back empty.

No run without a dry run

Ansible ships the operating mode for it: in check mode it executes nothing on the target systems — modules that support it report the changes they would have made. Diff mode adds the before-and-after view, and both combine: read first, execute second.

In practice that diff is more than a precaution: it is the document you can discuss before the maintenance window — with the colleague, the customer, the auditor. The change stops being an announcement (“we are adjusting the VLANs”) and becomes a readable difference. Why we consider this artefact discipline the core of any network automation is covered in NetBox as the source of truth — that is where the intent comes from that the diff here is made against.

Testable without the production network: the offline states

The underrated part of the resource modules are the states that change no device: rendered produces the configuration from the intent data without touching a device; parsed turns existing configuration text into structured data; gathered reads the current state in as data. The module docs explicitly list rendered and parsed as offline variants.

• rendered in the pipeline: every change to the intent produces the target configuration in CI — reviewable before anything sees a device.
• gathered as the drift watch: a recurring, read-only run compares actual against intended state and turns “that should really be the case” into a result list.
• parsed for the legacy estate: existing configurations become data — the most honest way to move a grown network into the intent world.
• Backup before every write: the ios_config backup option saves the running-config before anything changes — the safety net costs one line.

From playbook to an accepted change

The Ansible NTP pilot template separates inputs, diff and actual time synchronisation. NetDevOps and a failed lab acceptance test then show why a successful configuration task does not prove a working service.

The chain, complete

Put together, this is the flow we describe as our way of working under network automation: the inventory comes from NetBox (dynamic, with groups from sites and roles), the intent comes from the source of truth, rendered and the check diff make it readable, the resource modules enforce it — and gathered watches the drift afterwards. Which IOS XE release belongs on the devices in the first place is its own decision with its own article: IOS XE release strategy.