Mastering Network Automation with Ansible and Cisco IOS

The integration of Ansible into the management of Cisco IOS devices represents a paradigm shift from traditional, manual Command Line Interface (CLI) interactions to a structured, programmable infrastructure model. Cisco IOS stands as the most widely deployed network operating system globally, serving as the foundational software for a vast array of hardware, ranging from small-scale branch office routers to massive campus switches. Because these devices form the backbone of enterprise connectivity, the ability to manage them at scale is critical. By utilizing Ansible, network engineers can transition from executing individual commands on a per-device basis to pushing configuration changes, gathering operational telemetry, enforcing global compliance standards, and performing configuration backups across an entire fleet of infrastructure in minutes rather than hours. This automation removes the human-error component associated with manual typing and ensures that the state of the network is consistent, repeatable, and fully auditable.

Architectural Foundations and Collection Setup

To initiate automation for Cisco IOS, the environment must be prepared with the specific tools required to communicate with network hardware. The primary vehicle for this is the cisco.ios collection, which houses purpose-built modules designed specifically for the idiosyncrasies of the IOS operating system.

Installation and Collection Management

The initial step in the deployment process is the installation of the required collection via the Ansible Galaxy CLI. The command ansible-galaxy collection install cisco.ios fetches the necessary modules from the Ansible Galaxy repository, providing the library needed to interact with IOS-specific features.

Inventory Configuration and Variable Mapping

The inventory file is the central directory where the network topology is defined. A structured inventory allows for the grouping of devices by their role, such as routers and switches, ensuring that specific playbooks are only applied to the relevant hardware.

For effective communication, a set of global variables must be defined within the inventory or a group variables file. These variables instruct Ansible on how to authenticate and communicate with the device:

• ansiblenetworkos=cisco.ios.ios: This defines the network operating system, ensuring Ansible uses the correct driver and module logic for Cisco IOS.
• ansibleconnection=ansible.netcommon.networkcli: This specifies the connection plugin. The network_cli driver is optimized for network devices, handling the transition between user EXEC mode and privileged EXEC mode.
• ansible_user=admin: The administrative username used for SSH authentication.
• ansiblepassword={{ vaultios_password }}: The password for the user, typically stored in an Ansible Vault to maintain security.
• ansible_become=yes: This tells Ansible that the device requires a privilege escalation step to enter the privileged EXEC mode.
• ansiblebecomemethod=enable: This specifies that the 'enable' command is the method used to achieve higher privileges.
• ansiblebecomepassword={{ vaultenablepassword }}: The password required to enter the enable mode, also secured via Vault.

The technical necessity of the ansible_become settings stems from the Cisco IOS security model. Most configuration commands cannot be executed from the standard user prompt; they require the privileged EXEC mode. By configuring the become method as enable, Ansible automatically handles the transition to this mode, allowing the automation scripts to execute administrative commands without manual intervention.

Data Acquisition and Device Fact Gathering

The cisco.ios.ios_facts module is the primary tool for operational intelligence. It allows an engineer to extract structured data from the device, converting the unstructured text of a 'show' command into a JSON-like format that Ansible can manipulate.

Fact Gathering Implementation

When using the iosfacts module, the gathersubset parameter can be set to 'all' to collect a comprehensive dataset including hardware specifications, software versions, and interface statuses.

The resulting data allows for the creation of dynamic reports and summaries. Key facts gathered include: - ansiblenethostname: The configured hostname of the device. - ansiblenetmodel: The hardware model of the chassis. - ansiblenetversion: The current version of the IOS software. - ansiblenetserialnum: The unique hardware serial number. - ansiblenetimage: The specific software image currently running.

Interface Analysis

Beyond general device facts, the module can extract detailed information regarding the interface state. By mapping the ansiblenetinterfaces dictionary, administrators can generate a complete list of all physical and logical interfaces on the device, which is essential for auditing port density and connectivity.

Configuration Management with ios_config

The cisco.ios.ios_config module serves as the primary mechanism for pushing raw configuration changes. It abstracts the process of entering and exiting the configuration terminal.

Operational Workflow

When the ios_config module is invoked, it automatically handles the 'configure terminal' command to enter global configuration mode and the 'end' command to return to the privileged EXEC prompt.

A critical feature of this module is the ability to handle hierarchical configurations using the parents parameter. For example, if an engineer needs to configure the virtual teletype (VTY) lines, they can specify parents: line vty 0 15. Ansible will enter that specific configuration context before applying the subsequent lines of configuration, ensuring the commands are applied to the correct object.

Practical Application Example

A common use case for the ios_config module is the deployment of the Message of the Day (MOTD) banner. The module can send a line such as banner motd ^C Authorized access only. All activity is monitored, ensuring that legal notices are consistently applied across the fleet.

Reliability and Persistence

A major challenge in IOS automation is ensuring that changes survive a power cycle. If changes are only applied to the running-config, they are lost upon reboot. The ios_config module should be configured to save the running configuration to the startup configuration. This is a critical step to ensure the persistence of the network state.

Resource-Based Automation and Declarative State

While the ios_config module is powerful for raw commands, Cisco provides resource modules for a more structured, declarative approach. Resource modules allow the user to define the desired state of a feature (e.g., "this interface should be enabled") rather than sending the specific command to enable it.

Interface Management

The cisco.ios.ios_interfaces module allows for the management of physical port attributes. This removes the need to manually track whether a port is already set to a certain speed or duplex.

Configuration attributes manageable via this module include: - name: The interface identifier (e.g., GigabitEthernet0/1). - description: The administrative label for the port. - enabled: A boolean value to administratively shut down or enable the port. - speed: The operational speed of the interface (e.g., 1000). - duplex: The duplex setting (full or half). - state: The desired state, such as 'merged', which adds the configuration to the existing settings without overwriting other unrelated parameters.

Virtual LAN (VLAN) Configuration

The cisco.ios.ios_vlans module is used to define the VLAN database on a switch. By passing a list of VLAN IDs and names, the network state can be maintained consistently.

For example, a standard enterprise VLAN structure can be deployed as follows: - VLAN 10: SERVERS - VLAN 20: WORKSTATIONS - VLAN 30: VOICE - VLAN 40: MANAGEMENT - VLAN 99: NATIVE

Once the VLANs are created, the cisco.ios.iosl2interfaces module is used to assign these VLANs to specific ports. This involves setting the mode to 'access' and specifying the corresponding VLAN ID, which isolates traffic at Layer 2.

Advanced Troubleshooting and Integration Challenges

Automating Cisco IOS is not without its technical hurdles. Different versions of IOS and different hardware models can introduce inconsistencies in how commands are parsed or executed.

Handling Interactive Prompts

Certain IOS commands, such as crypto key generate rsa, trigger confirmation prompts that can hang an Ansible playbook. To resolve this, the ios_command module provides a prompt parameter. This allows the engineer to define the expected prompt and the response required to proceed, ensuring the automation flow is not interrupted.

The L3 Subinterface Gap and Jinja2 Templating

A known limitation in the current cisco.ios collection is the absence of a dedicated resource module for Layer 3 802.1q subinterfaces. To overcome this, engineers can utilize Jinja2 templates to generate the necessary configuration dynamically.

A template can be created to loop through a list of interfaces and apply the encapsulation settings: {% for i in ios_interfaces %} interface {{ i.name }} encapsulation dot1q {{ i.tag }} {% endfor %}

This approach uses the Jinja2 looping mechanism where the ios_interfaces variable (a dictionary) is passed from the playbook. While this method provides the necessary configuration, it is important to note that it is no longer idempotent; Ansible may report a change even if the configuration on the device already matches the template.

Testing and Validation

To mitigate the risk of catastrophic network failure, the use of the --check and --diff flags is mandatory during the testing phase. - The --check flag performs a "dry run," simulating the execution without actually applying changes. - The --diff flag displays the exact lines of configuration that would be added or removed. This level of visibility is essential for reviewing changes before they are pushed to production environments.

Collection Versioning and Compatibility

Maintaining the correct version of the cisco.ios collection is vital for stability, as updates often introduce new resource modules or fix critical bugs in parsing logic.

Version 11.3.0 Enhancements

The latest releases have expanded the capabilities of the collection by adding new resource modules specifically for Bidirectional Forwarding Detection (BFD). These include: - iosbfdinterfaces: Used for the direct configuration of BFD on a per-interface basis. - iosbfdtemplates: Allows for the configuration of BFD using standardized templates for consistency across the network.

Version 10.1.1 Bugfixes and Improvements

Previous versions addressed several critical failures in the interaction between Ansible and IOS: - iosacls: Resolved an issue where default access control lists were being unintentionally updated or removed. - ioshsrpinterfaces: Fixed errors related to the preempt attributes and the specific order in which commands were sent to the device. - iosl3interfaces: Added support for the Helper Address command, which is critical for DHCP relay configurations. - iosospfv2: Fixed the administrative distance parameter and made other distance attributes optional to prevent module failure. - iosvlans: Solved issues during VLAN overrides where primary VLANs had private VLAN associations referencing non-existent or higher VLAN IDs. - iosbgpaddressfamily: Improved the parsing of address-families to correctly distinguish between unicast and multicast types and refined the 'replaced' and 'overridden' state handling. - iosstaticroutes: Added missing interface names into the parser to ensure route accuracy. - iosvrfaddress_family: Enhanced the gathering of facts to include support for the 'stitching' attribute under route targets.

Dependency Management

There is a strict relationship between the version of ansible-core and the supporting collections. For users running ansible-core <= 2.18.x, the compatible versions are ansible.netcommon v8.0.1 and cisco.ios v10.1.1.

With the release of ansible-core >= 2.19, dependencies for ansible.netcommon were bumped to >= 8.1.0. This change was necessary because previous versions of the dependency suffered from compatibility issues with the newer core, which could lead to unstable connection behavior or module failures.

Comprehensive Technical Specifications Summary

The following table summarizes the core components and their roles within the Cisco IOS automation ecosystem.

Conclusion: The Impact of Programmable Infrastructure

The transition from manual configuration to Ansible-driven automation for Cisco IOS transforms the network from a series of individual "snowflakes"—devices with unique, undocumented configurations—into a standardized, programmable fabric. By leveraging the cisco.ios collection, organizations achieve a level of rigor and repeatability typically reserved for server orchestration.

The ability to use resource modules like iosinterfaces and iosvlans allows for a declarative state, meaning the engineer defines "what" the network should look like, and Ansible handles the "how" of the execution. This reduces the risk of configuration drift and ensures that compliance is maintained across the entire infrastructure. When combined with the safety mechanisms of the --check and --diff flags, and the security of Ansible Vault for credential management, network automation becomes a sustainable practice. The move toward this model allows for faster deployment cycles, reduced downtime caused by human error, and a comprehensive audit trail of every change made to the network backbone. As the ecosystem evolves with new modules for BFD and improved VRF parsing, the depth of control an engineer has over their Cisco environment continues to expand, paving the way for fully autonomous network operations.

Sources

1. OneUptime Blog
2. Ansible Collections GitHub - cisco.ios
3. Dev.to - Automate Cisco IOS/IOS-XE