Chapter 6: Ansible for Device-Level Network Automation

Architecture: Control Node and Managed Nodes

Ansible uses an agentless push model. The control node (workstation or CI server) holds all playbooks, inventory, and modules. Managed nodes (IOS XE devices) require only SSH — no Python or agents. Ansible connects, executes, and disconnects, leaving no persistent footprint.

Connection Plugins

The cisco.ios Collection and FQCNs

Install the collection with ansible-galaxy collection install cisco.ios. Always reference modules using Fully Qualified Collection Names (FQCNs):

cisco.ios.ios_interfaces
cisco.ios.ios_vlans
cisco.ios.ios_bgp_global

Inventory Design

Use YAML inventory with group_vars to separate connection variables from host definitions. Credentials should always reference Vault-encrypted variables, never be hardcoded.

# group_vars/ios_devices/vars.yml
ansible_connection: ansible.netcommon.network_cli
ansible_network_os: cisco.ios.ios
ansible_user: admin
ansible_password: "{{ vault_password }}"
ansible_become: true
ansible_become_method: enable
ansible_become_password: "{{ vault_enable_password }}"

Two Module Philosophies

Imperative modules (ios_config, ios_command) tell Ansible what commands to run. Declarative resource modules (ios_interfaces, ios_vlans, etc.) tell Ansible what the device should look like — the module figures out the commands.

ios_command — Running Show Commands

- name: Check interface status
  cisco.ios.ios_command:
    commands:
      - show ip interface brief
      - show version
  register: show_output

Use ios_command for reads and verification. It is not idempotent for writes — use resource modules or ios_config for configuration changes.

ios_config — Imperative Configuration Push

- name: Configure OSPF
  cisco.ios.ios_config:
    lines:
      - router ospf 1
      - router-id 10.0.0.1
      - passive-interface default
    save_when: modified

Idempotency is achieved via text comparison. Always use full, unabbreviated IOS syntax — abbreviated commands break idempotency because the running-config stores the expanded form.

ios_facts — Gathering Device Information

Call ios_facts explicitly for network plays (never rely on default fact gathering). Common facts: ansible_net_hostname, ansible_net_version, ansible_net_interfaces, ansible_net_neighbors.

Network Resource Modules and the state Parameter

Three-Phase Playbook Structure

Best practice is to separate playbooks into audit, configure, and verify phases. This improves readability and enables targeted tag-based execution.

Tags for Selective Execution

# Run only NTP tasks
ansible-playbook site.yml --tags ntp

# Run all routing tasks (BGP + OSPF)
ansible-playbook site.yml --tags routing

# Skip baseline tasks
ansible-playbook site.yml --skip-tags baseline

Variable Precedence (Lowest to Highest)

1. Role defaults (roles/name/defaults/main.yml)
2. Inventory group_vars
3. Inventory host_vars
4. Play vars:
5. Extra vars (-e key=value) — always wins

register, when, and loop

# Verification workflow with register + when
- name: Fail if BGP not established
  ansible.builtin.fail:
    msg: "BGP not up on {{ inventory_hostname }}"
  when: "'Established' not in bgp_summary.stdout[0]"

# Loop over a list
- name: Check routes
  cisco.ios.ios_command:
    commands:
      - "show ip route {{ item }}"
  loop:
    - "10.0.1.0"
    - "10.0.2.0"

Roles: Reusable Automation Units

Roles bundle tasks, handlers, variables, and templates into a standardized directory structure. Always prefix role variables with the role name to prevent namespace collisions across roles.

roles/
└── ios_base_config/
    ├── tasks/main.yml        # Entry point
    ├── handlers/main.yml
    ├── defaults/main.yml     # Lowest precedence — easily overridden
    ├── vars/main.yml         # High precedence
    └── templates/banner.j2

Ansible Vault: Securing Credentials

The two-file vault pattern: vault.yml (AES-256 encrypted, safe to commit) holds actual secrets; vars.yml (plaintext) references them with Jinja2 variables.

Error Handling: block / rescue / always

tasks:
  - block:
      - name: Apply routing configuration
        cisco.ios.ios_ospfv2:
          config:
            processes:
              - process_id: 1
                router_id: "{{ ospf_router_id }}"
          state: merged

      - name: Verify OSPF neighbors formed
        cisco.ios.ios_command:
          commands:
            - show ip ospf neighbor
        register: ospf_verify
        failed_when: "'FULL' not in ospf_verify.stdout[0]"

    rescue:
      - name: Collect diagnostics on failure
        cisco.ios.ios_command:
          commands:
            - show ip ospf
            - show logging | last 20
        register: diagnostics

    always:
      - name: Record task completion
        ansible.builtin.debug:
          msg: "Finished for {{ inventory_hostname }}"

retries and until — Waiting for Convergence

- name: Wait for BGP to converge
  cisco.ios.ios_command:
    commands:
      - show bgp summary
  register: bgp_state
  retries: 6
  delay: 10
  until: "'Established' in bgp_state.stdout[0]"

Handler Guard in Check Mode

handlers:
  - name: save ios config
    cisco.ios.ios_command:
      commands:
        - write memory
    when: not ansible_check_mode  # Prevents save during --check runs