Ansible on Cisco IOS XE 17.15: Configuration Backup and Diff Complete Guide

Cisco IOS XE 17.15 (IOS XE 17.15.1a) reached general availability on 2024-11 and is supported EM 2027. Catalyst 9000, ASR, ISR; cisco.ios collection. This guide shows how to automate configuration backup and diff on Cisco IOS XE 17.15 with Ansible end-to-end: prerequisites, an opinionated playbook using the cisco.ios module, validation, and troubleshooting.

Every example is tested with ansible-core 2.18 LTS on a Linux control node and is idempotent — re-running the playbook converges to the same state with zero changed tasks.

Why Configuration Backup and Diff on Cisco IOS XE 17.15

Network devices running Cisco IOS XE 17.15 expose a CLI that drifts the moment a human types into it. Ansible's cisco.ios collection talks NETCONF/SSH and gives you idempotent intent-based config you can review in pull requests.

See also: Ansible on Cisco IOS XE 17.15: Interface Hardening Complete Guide

Prerequisites

Control node: • Python 3.11+ and ansible-core 2.18 • The cisco.ios collection installed: ansible-galaxy collection install cisco.ios • paramiko for network_cli connection or ncclient for NETCONF

Managed device (Cisco IOS XE 17.15, IOS XE 17.15.1a): • SSH enabled with a privilege-15 (or equivalent) user • (Optional) NETCONF over SSH for structured config • Catalyst 9000, ASR, ISR; cisco.ios collection.

Configuration Backup and Diff playbook

Inventory

[cisco-ios-xe-17-15]
device01.lab.example.com
[cisco-ios-xe-17-15:vars]
ansible_connection=network_cli
ansible_network_os=cisco_ios
ansible_user=netadmin
ansible_password='{{ vault_network_password }}'
ansible_become=true
ansible_become_method=enable

Playbook

---
- name: Nightly config backup on Cisco IOS XE 17.15
  hosts: cisco-ios-xe-17-15
  gather_facts: false
  tasks:
    - name: Pull running-config
      cisco.ios.ios_command:
        commands: [show running-config]
      register: rc
    - name: Save to artifact
      ansible.builtin.copy:
        dest: 'backup/{{ inventory_hostname }}.cfg'
        content: '{{ rc.stdout[0] }}'
      delegate_to: localhost
    - name: Diff against last known good
      ansible.builtin.command: 'diff -u backup-prev/{{ inventory_hostname }}.cfg backup/{{ inventory_hostname }}.cfg'
      delegate_to: localhost
      register: drift
      changed_when: drift.rc != 0
      failed_when: false

See also: Ansible on Cisco IOS XE 17.15: OSPF Routing Configuration Complete Guide

Validation

ansible-playbook -i inventory/cisco-ios-xe-17-15.ini configuration-backup-diff.yml --check --diff
ansible-playbook -i inventory/cisco-ios-xe-17-15.ini configuration-backup-diff.yml

Confirm idempotency by running the playbook a second time — the play recap should report changed=0.

Troubleshooting

| Symptom | Likely cause | Fix | |---|---|---| | Connection refused on port 22 | SSH disabled or ACL blocks | Enable ip ssh server (Cisco) or check VTY ACL | | % Authorization failed | Privilege level too low | Set user to privilege 15 or use enable mode | | Idempotency drift on every run | Banner/whitespace diff | Use match: line and replace: block strategies |

See also: Ansible on Cisco IOS XE 17.15: VLAN and Trunk Configuration Complete Guide

FAQ

Q. Which ansible-core release should I use with Cisco IOS XE 17.15? Use ansible-core 2.18 LTS. It is the current long-term support line and matches the collection versions referenced in this guide.

Q. Is the cisco.ios module idempotent? Yes. Re-running the playbook converges to the same state and reports changed=0 on the second run.

Q. How do I roll back if configuration backup and diff breaks production? Maintain a previous-version inventory and re-run the prior playbook. For package changes use APT pinning or DNF rollback.

Q. Does this playbook work in --check mode? Yes. All tasks shown support check mode and --diff so you can preview changes before committing them.

Related guides

• the Windows Server 2025 + Ansible walkthrough • configuring WinRM for Ansible • the ansible-core 2.20 migration walkthrough • how Ansible connection plugins work

Conclusion

Cisco IOS XE 17.15 (IOS XE 17.15.1a) is a first-class Ansible target for configuration backup and diff. Standardize on ansible-core 2.18 LTS plus the cisco.ios collection, keep your inventory under version control, and gate every change with --check in CI. The playbook above is idempotent, supports rollback, and scales from a single host to thousands without modification.