cisco.ios.ios_interfaces module – Resource module to configure interfaces.
Note
This module is part of the cisco.ios collection (version 3.3.2).
You might already have this collection installed if you are using the ansible
package.
It is not included in ansible-core
.
To check whether it is installed, run ansible-galaxy collection list
.
To install it, use: ansible-galaxy collection install cisco.ios
.
To use it in a playbook, specify: cisco.ios.ios_interfaces
.
New in cisco.ios 1.0.0
Synopsis
This module manages the interface attributes of Cisco IOS network devices.
Parameters
Parameter |
Comments |
---|---|
A dictionary of interface options |
|
Interface description. |
|
Interface link status. Applicable for Ethernet interfaces only, either in half duplex, full duplex or in automatic state which negotiates the duplex automatically. Choices:
|
|
Administrative state of the interface. Set the value to Choices:
|
|
MTU for a specific interface. Applicable for Ethernet interfaces only. Refer to vendor documentation for valid values. |
|
Full name of interface, e.g. GigabitEthernet0/2, loopback999. |
|
Interface link speed. Applicable for Ethernet interfaces only. |
|
This option is used only with state parsed. The value of this option should be the output received from the IOS device by executing the command show running-config | section ^interface. The state parsed reads the configuration from |
|
The state the configuration should be left in The states rendered, gathered and parsed does not perform any change on the device. The state rendered will transform the configuration in The state gathered will fetch the running configuration from device and transform it into structured data in the format as per the resource module argspec and the value is returned in the gathered key within the result. The state parsed reads the configuration from The state purged negates virtual/logical interfaces that are specified in task from running-config. Choices:
|
Notes
Note
Tested against Cisco IOSv Version 15.2 on VIRL
This module works with connection
network_cli
. See https://docs.ansible.com/ansible/latest/network/user_guide/platform_ios.html
Examples
# Using merged
# Before state:
# -------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
# description Configured by Ansible
# no ip address
# duplex auto
# speed auto
# interface GigabitEthernet0/2
# description This is test
# no ip address
# duplex auto
# speed 1000
# interface GigabitEthernet0/3
# no ip address
# duplex auto
# speed auto
- name: Merge provided configuration with device configuration
cisco.ios.ios_interfaces:
config:
- name: GigabitEthernet0/2
description: Configured and Merged by Ansible Network
enabled: true
- name: GigabitEthernet0/3
description: Configured and Merged by Ansible Network
mtu: 2800
enabled: false
speed: 100
duplex: full
state: merged
# Commands Fired:
# ---------------
# "commands": [
# "interface GigabitEthernet0/2",
# "description Configured and Merged by Ansible Network",
# "no shutdown",
# "interface GigabitEthernet0/3",
# "description Configured and Merged by Ansible Network",
# "mtu 2800",
# "duplex full",
# "shutdown",
# ],
# After state:
# ------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
# description Configured by Ansible
# no ip address
# duplex auto
# speed auto
# interface GigabitEthernet0/2
# description Configured and Merged by Ansible Network
# no ip address
# duplex auto
# speed 1000
# interface GigabitEthernet0/3
# description Configured and Merged by Ansible Network
# mtu 2800
# no ip address
# shutdown
# duplex full
# speed 100
# Using replaced
# Before state:
# -------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
# no ip address
# duplex auto
# speed auto
# interface GigabitEthernet0/2
# description Configured by Ansible Network
# no ip address
# duplex auto
# speed 1000
# interface GigabitEthernet0/3
# mtu 2000
# no ip address
# shutdown
# duplex full
# speed 100
- name: Replaces device configuration of listed interfaces with provided configuration
cisco.ios.ios_interfaces:
config:
- name: GigabitEthernet0/3
description: Configured and Replaced by Ansible Network
enabled: false
duplex: auto
mtu: 2500
speed: 1000
state: replaced
# Commands Fired:
# ---------------
# "commands": [
# "interface GigabitEthernet0/3",
# "description Configured and Replaced by Ansible Network",
# "mtu 2500",
# "duplex auto",
# "speed 1000",
# ],
# After state:
# -------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
# no ip address
# duplex auto
# speed auto
# interface GigabitEthernet0/2
# description Configured by Ansible Network
# no ip address
# duplex auto
# speed 1000
# interface GigabitEthernet0/3
# description Configured and Replaced by Ansible Network
# mtu 2500
# no ip address
# shutdown
# duplex auto
# speed 1000
# Using overridden
# Before state:
# -------------
#
# vios#show running-config | section ^interface#
# interface GigabitEthernet0/1
# description Configured by Ansible
# no ip address
# duplex auto
# speed auto
# interface GigabitEthernet0/2
# description This is test
# no ip address
# duplex auto
# speed 1000
# interface GigabitEthernet0/3
# description Configured by Ansible
# mtu 2800
# no ip address
# shutdown
# duplex full
# speed 100
- name: Override device configuration of all interfaces with provided configuration
cisco.ios.ios_interfaces:
config:
- name: GigabitEthernet0/2
description: Configured and Overridden by Ansible Network
speed: 1000
- name: GigabitEthernet0/3
description: Configured and Overridden by Ansible Network
enabled: false
duplex: full
mtu: 2000
state: overridden
# "commands": [
# "interface GigabitEthernet0/1",
# "no description description Configured by Ansible",
# "no duplex auto",
# "no speed auto",
# "interface GigabitEthernet0/2",
# "description Configured and Overridden by Ansible Network",
# "interface GigabitEthernet0/3",
# "description Configured and Overridden by Ansible Network",
# "mtu 2000",
# ],
# After state:
# -------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
# no ip address
# duplex auto
# speed auto
# interface GigabitEthernet0/2
# description Configured and Overridden by Ansible Network
# no ip address
# duplex auto
# speed 1000
# interface GigabitEthernet0/3
# description Configured and Overridden by Ansible Network
# mtu 2000
# no ip address
# shutdown
# duplex full
# speed auto
# Using Deleted
# Before state:
# -------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
# no ip address
# duplex auto
# speed auto
# interface GigabitEthernet0/2
# description Configured by Ansible Network
# no ip address
# duplex auto
# speed 1000
# interface GigabitEthernet0/3
# description Configured by Ansible Network
# mtu 2500
# no ip address
# shutdown
# duplex full
# speed 1000
- name: "Delete module attributes of given interfaces (Note: This won't delete the interface itself)"
cisco.ios.ios_interfaces:
config:
- name: GigabitEthernet0/2
state: deleted
# "commands": [
# "interface GigabitEthernet0/2",
# "no description description Configured by Ansible Network",
# "no duplex auto",
# "no speed 1000",
# ],
# After state:
# -------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
# no ip address
# duplex auto
# speed auto
# interface GigabitEthernet0/2
# no ip address
# duplex auto
# speed auto
# interface GigabitEthernet0/3
# description Configured by Ansible Network
# mtu 2500
# no ip address
# shutdown
# duplex full
# speed 1000
# Using Purged
# Before state:
# -------------
#
# vios#show running-config | section ^interface
# interface Loopback888
# interface Port-channel10
# interface GigabitEthernet0/1
# no ip address
# duplex auto
# speed auto
# interface GigabitEthernet0/2
# description Configured by Ansible Network
# no ip address
# duplex auto
# speed 1000
# interface GigabitEthernet0/3
# description Configured by Ansible Network
# mtu 2500
# no ip address
# shutdown
# duplex full
# speed 1000
- name: "Purge given interfaces (Note: This will delete the interface itself)"
cisco.ios.ios_interfaces:
config:
- name: Loopback888
- name: Port-channel10
state: purged
# "commands": [
# "no interface Loopback888",
# "no interface Port-channel10",
# ],
# After state:
# -------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
# no ip address
# duplex auto
# speed auto
# interface GigabitEthernet0/2
# description Configured by Ansible Network
# no ip address
# duplex auto
# speed 1000
# interface GigabitEthernet0/3
# description Configured by Ansible Network
# mtu 2500
# no ip address
# shutdown
# duplex full
# speed 1000
# Using Gathered
# Before state:
# -------------
#
# vios#sh running-config | section ^interface
# interface GigabitEthernet0/1
# description this is interface1
# mtu 65
# duplex auto
# speed 10
# interface GigabitEthernet0/2
# description this is interface2
# mtu 110
# shutdown
# duplex auto
# speed 100
- name: Gather listed interfaces with provided configurations
cisco.ios.ios_interfaces:
config:
state: gathered
# Module Execution Result:
# ------------------------
#
# "gathered": [
# {
# "description": "this is interface1",
# "duplex": "auto",
# "enabled": true,
# "mtu": 65,
# "name": "GigabitEthernet0/1",
# "speed": "10"
# },
# {
# "description": "this is interface2",
# "duplex": "auto",
# "enabled": false,
# "mtu": 110,
# "name": "GigabitEthernet0/2",
# "speed": "100"
# }
# ]
# After state:
# ------------
#
# vios#sh running-config | section ^interface
# interface GigabitEthernet0/1
# description this is interface1
# mtu 65
# duplex auto
# speed 10
# interface GigabitEthernet0/2
# description this is interface2
# mtu 110
# shutdown
# duplex auto
# speed 100
# Using Rendered
- name: Render the commands for provided configuration
cisco.ios.ios_interfaces:
config:
- name: GigabitEthernet0/1
description: Configured by Ansible-Network
mtu: 110
enabled: true
duplex: half
- name: GigabitEthernet0/2
description: Configured by Ansible-Network
mtu: 2800
enabled: false
speed: 100
duplex: full
state: rendered
# Module Execution Result:
# ------------------------
#
# "rendered": [
# "interface GigabitEthernet0/1",
# "description Configured by Ansible-Network",
# "mtu 110",
# "duplex half",
# "no shutdown",
# "interface GigabitEthernet0/2",
# "description Configured by Ansible-Network",
# "mtu 2800",
# "speed 100",
# "duplex full",
# "shutdown"
# ]
# Using Parsed
# File: parsed.cfg
# ----------------
#
# interface GigabitEthernet0/1
# description interfaces 0/1
# mtu 110
# duplex half
# no shutdown
# interface GigabitEthernet0/2
# description interfaces 0/2
# mtu 2800
# speed 100
# duplex full
# shutdown
- name: Parse the commands for provided configuration
cisco.ios.ios_interfaces:
running_config: "{{ lookup('file', 'parsed.cfg') }}"
state: parsed
# Module Execution Result:
# ------------------------
#
# "parsed": [
# {
# "description": "interfaces 0/1",
# "duplex": "half",
# "enabled": true,
# "mtu": 110,
# "name": "GigabitEthernet0/1"
# },
# {
# "description": "interfaces 0/2",
# "duplex": "full",
# "enabled": true,
# "mtu": 2800,
# "name": "GigabitEthernet0/2",
# "speed": "100"
# }
# ]
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
---|---|
The resulting configuration after module execution. Returned: when changed Sample: |
|
The configuration prior to the module execution. Returned: when state is Sample: |
|
The set of commands pushed to the remote device. Returned: when state is Sample: |
|
Facts about the network resource gathered from the remote device as structured data. Returned: when state is Sample: |
|
The device native config provided in running_config option parsed into structured data as per module argspec. Returned: when state is Sample: |
|
The provided configuration in the task rendered in device-native format (offline). Returned: when state is Sample: |