ios_interfaces – Manages interface attributes of Cisco IOS network devices

New in version 2.9.

Synopsis

  • This module manages the interface attributes of Cisco IOS network devices.

Parameters

Parameter Choices/Defaults Comments
config
list
A dictionary of interface options
description
string
Interface description.
duplex
string
    Choices:
  • full
  • half
  • auto
Interface link status. Applicable for Ethernet interfaces only, either in half duplex, full duplex or in automatic state which negotiates the duplex automatically.
enabled
boolean
    Choices:
  • no
  • yes ←
Administrative state of the interface.
Set the value to true to administratively enable the interface or false to disable it.
mtu
integer
MTU for a specific interface. Applicable for Ethernet interfaces only.
Refer to vendor documentation for valid values.
name
string / required
Full name of interface, e.g. GigabitEthernet0/2, loopback999.
speed
string
Interface link speed. Applicable for Ethernet interfaces only.
state
string
    Choices:
  • merged ←
  • replaced
  • overridden
  • deleted
The state of the configuration after module completion

Notes

Note

  • Tested against Cisco IOSv Version 15.2 on VIRL
  • This module works with connection network_cli. See IOS Platform Options.

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
  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

# 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
  ios_interfaces:
    config:
      - name: GigabitEthernet0/3
        description: 'Configured and Replaced by Ansible Network'
        enabled: False
        duplex: auto
        mtu: 2500
        speed: 1000
    state: replaced

# 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 full
#  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
  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

# 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 100

# 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)"
  ios_interfaces:
    config:
      - name: GigabitEthernet0/2
    state: deleted

# 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 Deleted without any config passed
#"(NOTE: This will delete all of configured resource module attributes from each configured interface)"

# 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 all interfaces (Note: This won't delete the interface itself)"
  ios_interfaces:
    state: deleted

# 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
#  no ip address
#  duplex auto
#  speed auto

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
after
list
when changed
The configuration as structured data after module completion.

Sample:
The configuration returned will always be in the same format of the parameters above.
before
list
always
The configuration as structured data prior to module invocation.

Sample:
The configuration returned will always be in the same format of the parameters above.
commands
list
always
The set of commands pushed to the remote device

Sample:
['interface GigabitEthernet 0/1', 'description This is test', 'speed 100']


Status

Red Hat Support

More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.

Authors

  • Sumit Jaiswal (@justjais)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.