Network Automation with Ansible

Two Ansible modules can add the same VLAN, and the difference between them is the spine of this whole page:

# Imperative: hand the device CLI lines
- cisco.ios.ios_config:
    parents: vlan 20
    lines: [name SERVERS]

# Declarative: hand the module the desired resource
- cisco.ios.ios_vlans:
    config: [{ vlan_id: 20, name: SERVERS }]
    state: merged

The ios_config^[1] version is imperative: you type CLI lines and the module sends them, exactly as you would at a console. The ios_vlans^[2] version is declarative: you describe the end state as structured data and the module makes the device match it. A resource module is that declarative kind, one per feature area (VLANs, ACLs, an OSPF process), and it runs the read-diff-push loop the diagram traces: it reads the running config off the device, computes the difference against your data, and pushes only that delta over a connection plugin (the transport, covered in "Reaching the device").

Two properties fall out of that loop. The module is declarative, so you state the goal rather than the ordered steps, and it is idempotent: applying the same input converges the device once and then reports no further change. Run ios_vlans with state: replaced and the running VLAN database is rewritten to match your list; run it again and it reports changed: false. That zero-change re-run is the signal the device already matches source control, which is why the guidance is one line: reach for the resource module when one models the feature, and keep ios_config for raw CLI that nothing else covers (network resource modules^[3]).

One keyword, state, decides how much of the device a resource module is allowed to change, and getting it wrong is the difference between fixing one ACL and wiping every ACL on the box. Read the four write states as an axis of increasing scope:

• merged (the default) adds or updates the attributes you list and removes nothing. Listing VLAN 10 with a new name changes that name and leaves every other VLAN alone.
• replaced rewrites each resource you name to match your definition exactly, but only the resources you name. state: replaced on one named ACL^[4] rewrites that ACL's entries and touches no other ACL.
• overridden rewrites the whole class and deletes anything you did not list. state: overridden on ios_vlans reconciles every VLAN on the device to your list and removes the VLANs absent from it.
• deleted removes the resources you name (or, with an empty config, the whole class).

The trap the exam leans on is replaced versus overridden. Both rewrite config, so they read as interchangeable, but replaced is per-resource and leaves unlisted resources alone, while overridden is device-wide and deletes them. To remove VLANs no longer in source control the answer is overridden; to fix one VLAN without disturbing the others it is replaced. The diagram draws these as nested boundaries: the inner box is the attributes merged touches, the middle box is the one resource replaced rewrites, and the outer box is the whole class overridden reconciles.

Read-only states never touch the device

Three more states transform config without changing anything. gathered returns the live config as structured facts (the read half of the loop), rendered turns your input into device CLI without connecting at all, and parsed converts a supplied running-config text into structured data for migration. Because rendered and parsed open no connection, they run in CI with no lab.

Choosing the right module

The naming rule is short: the modern declarative modules are plural, and the singular ones are their removed predecessors.

Module	Manages
cisco.ios.ios_vlans	The VLAN database (singular ios_vlan was removed)
cisco.ios.ios_acls	Named/numbered IPv4/IPv6 ACLs as structured ACEs
cisco.ios.ios_ospfv2[5]	The OSPFv2 process: areas, networks, redistribution, timers
cisco.ios.ios_ospf_interfaces	Per-interface OSPF settings
cisco.ios.ios_interfaces[6]	L1/L2 attributes: description, enabled, mtu, speed, duplex
cisco.ios.ios_l3_interfaces[7]	L3 addressing: IPv4/IPv6 on an interface

Two naming traps recur. The singular cisco.ios.ios_vlan was deprecated and removed from the cisco.ios collection after 2022-06-01, and even before removal it could only add VLANs, never declaratively replace the set, so the plural ios_vlans is always today's call. And the interface split is real: ios_interfaces owns L1/L2 attributes while ios_l3_interfaces owns IP addressing, so trying to set an address with ios_interfaces puts it nowhere. Routing splits the same way, ios_ospfv2 for the process and ios_ospf_interfaces per interface. A stem that says manage the OSPF process declaratively wants ios_ospfv2, not ios_config; return the current config as structured data with no change wants state: gathered, the one read that hits the live device.

ios_config is the right tool for raw CLI that no resource module models, banners, one-off global commands, service tweaks, and it earns three options worth knowing cold. A single task is CLI with a little structure around it:

- cisco.ios.ios_config:
    parents: interface GigabitEthernet1/0/1
    lines:
      - ip access-group ACL_IN in
      - description UPLINK-TO-CORE
    match: line
    save_when: changed

lines (alias commands) is the ordered CLI to send. parents is the ordered configuration-mode context the module enters first, so the two lines land inside interface GigabitEthernet1/0/1 rather than at the global level. That placement is what ios_config compares against show running-config, so the text must match what the device stores, including full non-abbreviated forms: int Gi1/0/1 will not match the stored interface GigabitEthernet1/0/1 and re-sends every run.

match decides whether the task is idempotent

Whether a second run reports ok or changed comes down to match, which defaults to line. The diagram splits on it. With match: line the module reads the running config, compares each candidate line, and sends only the missing ones, so a converged device receives nothing, that is idempotency, and it is on by default; strict and exact are the other diff-aware values (they tighten how ordering and completeness are compared) and behave the same way for this purpose, diffing against the running config and sending only what is missing. match: none alone skips the comparison and re-sends the full lines list on every run, reporting changed forever. This is the single most tested fact about the module: idempotent by default, but match: none throws idempotency away. Reserve it for a genuine unconditional replay, never as a way to "make sure it applies."

save_when persists to startup without churn

An ios_config change lands in running-config and stops there; save_when decides when it is copied to startup so it survives a reload. The default is never.

save_when	Copies running to startup when	Idempotent
never (default)	never	yes, but the change is not persisted
modified	running and startup differ	yes
changed	this task changed running-config	yes
always	every run	no, reports changed each time

The favourite detail is modified versus changed: modified looks at the device and saves whenever running and startup differ (including an out-of-band change someone else made), while changed looks at the task and saves only when this run altered config. Both keep a converged play green; a stem that mentions an out-of-band change points at modified. save_when: always is the usual reason a playbook never turns green, because it saves and reports changed on every run. When a structured feature (VLANs, OSPFv2, an ACL, an interface address) is in play, the maintainable answer is the matching resource module, not a hand-built ios_config block, and ios_command^[8] is a trap that only runs show/exec output and cannot change config at all.

A switch runs no on-box Python, so Ansible keeps the module on the control node, runs it locally, and reaches the device through a connection plugin that speaks the device's own protocol. Two inventory variables steer that: ansible_connection picks the transport, and ansible_network_os: cisco.ios.ios names the platform so the plugin loads the right command set and parser (set network_os wrong and you get a wall of parser errors). The three network transports live in the ansible.netcommon collection, and the diagram traces one task from the control node through whichever you pick.

Aspect	network_cli	netconf	httpapi
ansible_connection	ansible.netcommon.network_cli	ansible.netcommon.netconf	ansible.netcommon.httpapi
Transport / port	SSH, TCP 22	NETCONF over SSH, TCP 830	HTTP(S), TCP 443 with SSL
On the wire	CLI commands	NETCONF RPC (XML)	JSON over REST
Typical target	IOS/IOS-XE via cisco.ios	YANG config datastores	RESTCONF, Catalyst Center

network_cli^[9] is the SSH command line and the workhorse for ios_config and the resource modules. netconf^[10] exchanges XML RPCs on port 830 and needs the ncclient library on the control node, which is itself the tell that a scenario means NETCONF. httpapi^[11] carries RESTCONF and controller APIs such as Cisco Catalyst Center^[12] as JSON over HTTPS; turn on TLS with ansible_httpapi_use_ssl: true and the port defaults to 443. An API transport reads and writes structured data instead of screen-scraping a terminal.

Log in, then elevate with become: enable

On network_cli, authenticating and reaching config mode are two steps, and forgetting the second is the classic privilege error. ansible_user and ansible_password open the SSH session and land you at user EXEC (switch>); configuration lives behind privileged EXEC (switch#), so you elevate with become: true and become_method: enable (plus ansible_become_password when an enable secret is set). Read this carefully: become here is not sudo. The meaningful become_method on a network device is enable, which maps to the IOS enable command, so an answer using become_method: sudo is wrong by construction. A read-only ios_command running show stays at user EXEC and needs no elevation.

Scope variables with group_vars and host_vars

Credentials belong in inventory, not playbooks. Put settings shared by a class of devices in group_vars/<group>.yml and per-device exceptions in host_vars/<host>.yml; where both set the same variable, host_vars outranks group_vars^[13]. So set the norm once at the group and override only the exception per host. Two guardrails: group_vars/host_vars are plain YAML on disk, so any secret in them must be encrypted with Ansible Vault (next section), and a host in many groups inherits from all of them, which makes a value's origin hard to trace.

A network-automation repo fills with values you cannot commit as clear text: the enable secret, a Catalyst Center API token, a TACACS password. Ansible Vault^[14] keeps them in the same Git repo as your playbooks by storing them as ciphertext. The mental model is one sentence: ansible-vault applies symmetric AES256 encryption to content at rest, and the vault password is the only key. At rest is load-bearing, Vault protects files on disk, not the SSH or TLS session to the device, which is secured separately. Debunk the common confusion on sight: the ansible-vault CLI baked into Ansible and the HashiCorp Vault server (a network-reachable secrets manager) share a word and nothing else; an ansible-vault encrypt on a .yml file always means the Ansible tool.

The diagram follows one secret end to end. You run ansible-vault encrypt (or encrypt_string) once, turning plaintext into ciphertext; that ciphertext is what you commit, so the repo never holds the plaintext. At run time you supply the vault password, Ansible decrypts the value in memory for that run, and never writes plaintext back to disk.

Encrypt a whole file, or a single value

ansible-vault encrypt group_vars/all/vault.yml replaces a file's whole contents with one $ANSIBLE_VAULT;1.1;AES256 blob, unreadable in a diff, which suits a dedicated secrets file. You still work with it through ansible-vault edit, view, and rekey (which re-encrypts under a new password in one step, with no plaintext-on-disk window). ansible-vault encrypt_string instead encrypts one value^[15] and prints a !vault | YAML snippet you paste into an otherwise plaintext vars file, so variable names and structure stay readable in review while only the secret is opaque.

The password is the whole trust boundary

Because the AES key is derived from the vault password, protecting that password is the entire job. Supply it only at run time: --ask-vault-pass prompts interactively (fine for a human, useless in a pipeline that has no terminal to answer), and --vault-password-file ~/.vault_pass reads it from a file or an executable script, which is how a CI job injects it from its own protected store. When one play mixes secrets under different passwords, --vault-id label@source^[16] names each (--vault-id prod@prompt --vault-id lab@lab-pass.txt) and is also the supported bridge to an external secrets manager through a client script.

The headline anti-pattern the exam tests: encrypting a vars file but committing its vault password file next to it gives no real protection, because anyone who clones the repo then holds both halves. The password must reach the run from outside source control, a prompt, a CI secret variable, or a secrets manager, so repository access alone never yields plaintext. And "commit it in a private repo" is not the fix: private is access control, not encryption.

Run a fully converged playbook a second time and the recap reads changed=0 on every host, that zero is the whole point. Idempotency (introduced in "Two ways to configure IOS") shows up operationally in the PLAY RECAP^[17]: a task reports changed only when it actually altered the device, so a green changed=0 run tells you the running config still matches source control, and a surprise changed=2 on a play you did not edit tells you something drifted. The crucial caveat is that idempotency is a property of the module, not of Ansible: a resource module diffs and converges, but a raw command module (ios_command, shell, raw) cannot know its effect was already present and reports changed every run, so a changed=0 recap means nothing for a play built out of those.

Preview safely with check mode and diff

ansible-playbook --check --diff is the dry run before production. Check mode^[18] has each module compute the change it would make and report changed/ok without sending anything, and --diff prints the exact configuration delta line by line. Check mode is per-module, the network resource modules support it while a raw command module cannot predict its own effect, and --diff also works on a real apply, turning an ordinary run into an audit log of what moved.

Roles package automation; handlers fire once

A role^[19] gives reusable automation a fixed layout, tasks/ handlers/ templates/ vars/ defaults/ meta/, and Ansible auto-loads main.yml from each. The defaults/ versus vars/ split is the part exams probe: defaults/main.yml holds the lowest-precedence variables a caller is meant to override, while vars/main.yml holds high-precedence values that an ordinary playbook variable will not. A handler^[20] is a task that runs only when another task notifys it, and only if that task reported changed; all notified handlers run once, at the end of the play, in definition order, exactly the semantics for a single save config after a batch of changes and never on a converged run.

One template for a fleet

Jinja2^[21] is how one playbook fits devices that are not identical. Ansible evaluates {{ ... }} from inventory, host_vars, and group_vars; the template module renders a .j2 file per host; loop (the modern replacement for with_items) repeats a task once per list element for a variable-length set of VLANs or ACLs; and when gates a task on an expression such as a device fact, so a single play branches across a heterogeneous fleet. Inventory data plus one template equals per-device config.

Failure handling and rollback

Internalize the rule first: Ansible does not roll back. When a task fails the play stops for that host, but earlier changes stay applied, so rollback is something you write, using the block^[22] construct the diagram traces. block groups the change tasks; rescue runs only if a block task fails (put undo/restore steps here); always runs on both paths for cleanup or a final notify. Two task keywords decide whether the rescue path is reached, and they are the pair the exam most often swaps: failed_when^[23] redefines what counts as a failure (a command can exit 0 yet be a failure because its output contains Invalid), while ignore_errors: true changes what happens after a failure by letting the play continue. They are not interchangeable, and an answer that uses ignore_errors to mean redefine-failure is wrong.

SSH into a switch and run show version: it prints the model, chassis serial, and running image. Open show running-config and none of those three appear. That gap is this section. A managed device holds two kinds of data. Configuration is the intended settings you push, interfaces, routing, ACLs, VLANs, what show running-config returns and NETCONF calls a configuration datastore (RFC 6241^[10]). Operational state is the live, read-only data the device computes about itself: model, serial number, software version, oper-status and counters, neighbor and route tables, uptime. You cannot set operational state; the device reports it.

Device facts and asset inventory are operational state, so a task that says "build a CMDB keyed on serial number" is asking for state, never configuration. The diagram fixes that split, and every tool below exposes a config-read beside a state-read; every trap in this area is a config-read offered where the goal needs the state-read.

The three surfaces, one split

• Ansible. cisco.ios.ios_facts^[24] gathers a device into ansible_net_* variables (ansible_net_model, ansible_net_serialnum, ansible_net_version, ansible_net_hostname), the standard asset feed; gather_subset (all, min, hardware, interfaces, config) tunes cost, and hardware is usually right for inventory. The trap: a resource module's state: gathered returns that one feature's structured configuration, not a serial or model, so when the stem asks for hardware/software inventory, ios_facts is the answer and gathered is the distractor.
• RESTCONF turns the split into a query knob: GET with content=nonconfig returns operational state only, content=config returns configuration only, and omitting content returns both (the default is all) (RFC 8040 §4.8.1^[11]). So the common misread, that a plain RESTCONF GET returns just configuration, is wrong; read state alone with content=nonconfig.
• NETCONF makes it two operations: get-config returns configuration only from a named datastore, while get returns configuration and operational state together. To read counters or neighbor state over NETCONF you issue get, never get-config.

RESTCONF content=config lines up with NETCONF get-config, and RESTCONF's default all with NETCONF get; the one asymmetry is that NETCONF has no single state-only verb.

Python: retrieve, then parse

In Python you read live state with a purpose-built call, then parse the reply, never regex raw text. ncclient^[25] issues the same RPCs, m.get(...) for config-plus-state and m.get_config(source='running', ...) for config only, returning XML you parse with xmltodict or lxml. netmiko runs send_command("show version") and returns raw text whose column positions shift between releases, so scraping it with regular expressions is brittle. Turn the reply into a dictionary instead: Cisco pyATS/Genie^[26] parses hundreds of show commands (device.parse("show version")["version"]["chassis_sn"]), and netmiko can apply a TextFSM template with use_textfsm=True. Either way you key on named fields, so a cosmetic output change does not break the collector. One rule collapses the whole section: choose the read whose result set includes operational state, and treat every config-only read (gathered, content=config, get-config) as the trap whenever the question asks for device facts or asset inventory.