/ home / cisco / cisco.ios / 8.0.0 / module / ios_interfaces

cisco.ios.ios_interfaces (8.0.0) — module

Resource module to configure interfaces.

| "added in version" 1.0.0 of cisco.ios"

Authors: Sumit Jaiswal (@justjais), Sagar Paul (@KB-perByte)

Install collection

Install with ansible-galaxy collection install cisco.ios:==8.0.0

Add to requirements.yml

  collections:
    - name: cisco.ios
      version: 8.0.0

Description

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

Usage examples

Scanned by Steampunk Spotter

# Using merged

# Before state:
# -------------
#
# Router#sh running-config | section interface
# interface Loopback888
#  no ip address
# interface Loopback999
#  no ip address
# interface GigabitEthernet1
#  ip address dhcp
#  negotiation auto
# interface GigabitEthernet2
#  description Configured and Merged by Ansible Network
#  ip address dhcp
#  speed 1000
#  no negotiation auto
# interface GigabitEthernet3
#  no ip address
#  speed 1000
#  no negotiation auto
# interface GigabitEthernet4
#  no ip address
#  shutdown
#  negotiation auto

- name: Merge provided configuration with device configuration
  cisco.ios.ios_interfaces:
    config:
      - name: GigabitEthernet2
        description: Configured and Merged by Ansible Network
        enabled: true
      - name: GigabitEthernet3
        description: Configured and Merged by Ansible Network
        mtu: 3800
        enabled: false
        speed: 100
        duplex: full
    state: merged

Scanned by Steampunk Spotter

# Task Output
# -----------
#
# before:
# - enabled: true
#   name: GigabitEthernet1
# - description: Configured and Merged by Ansible Network
#   enabled: true
#   name: GigabitEthernet2
#   speed: '1000'
# - description: Configured and Merged by Ansible Network
#   enabled: false
#   mtu: 3800
#   name: GigabitEthernet3
#   speed: '1000'
# - enabled: false
#   name: GigabitEthernet4
# - enabled: true
#   name: Loopback888
# - enabled: true
#   name: Loopback999
# commands:
# - interface GigabitEthernet3
# - description Configured and Merged by Ansible Network
# - speed 100
# - mtu 3800
# - duplex full
# - shutdown
# after:
# - enabled: true
#   name: GigabitEthernet1
# - description: Configured and Merged by Ansible Network
#   enabled: true
#   name: GigabitEthernet2
#   speed: '1000'
# - description: Configured and Merged by Ansible Network
#   enabled: true
#   mtu: 2800
#   name: GigabitEthernet3
#   speed: '1000'
# - enabled: false
#   name: GigabitEthernet4
# - enabled: true
#   name: Loopback888
# - enabled: true
#   name: Loopback999

# After state:
# ------------
#
# Router#show running-config | section ^interface
# interface Loopback888
#  no ip address
# interface Loopback999
#  no ip address
# interface GigabitEthernet1
#  ip address dhcp
#  negotiation auto
# interface GigabitEthernet2
#  description Configured and Merged by Ansible Network
#  ip address dhcp
#  speed 1000
#  no negotiation auto
# interface GigabitEthernet3
#  description Configured and Merged by Ansible Network
#  mtu 3800
#  no ip address
#  shutdown
#  speed 1000
#  no negotiation auto
# interface GigabitEthernet4
#  no ip address
#  shutdown
#  negotiation auto

# Using merged - with mode attribute

# Before state:
# -------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet1
#  description Configured by Ansible
# interface GigabitEthernet2
#  description This is test
# interface GigabitEthernet3
#  description This is test
#  no switchport

- name: Merge provided configuration with device configuration
  cisco.ios.ios_interfaces:
    config:
      - name: GigabitEthernet2
        description: Configured and Merged by Ansible Network
        enabled: true
        mode: layer2
      - name: GigabitEthernet3
        description: Configured and Merged by Ansible Network
        mode: layer3
    state: merged

Scanned by Steampunk Spotter

# Task Output
# -----------
#
# before:
# - enabled: true
#   name: GigabitEthernet1
# - description: Configured and Merged by Ansible Network
#   name: GigabitEthernet2
# - description: Configured and Merged by Ansible Network
#   name: GigabitEthernet3
# commands:
# - interface GigabitEthernet2
# - description Configured and Merged by Ansible Network
# - switchport
# - interface GigabitEthernet3
# - description Configured and Merged by Ansible Network
# after:
# - enabled: true
#   name: GigabitEthernet1
# - description: Configured and Merged by Ansible Network
#   enabled: true
#   name: GigabitEthernet2
# - description: Configured and Merged by Ansible Network
#   name: GigabitEthernet3
#   mode: layer3

# After state:
# ------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet1
#  description Configured by Ansible
# interface GigabitEthernet2
#  description Configured and Merged by Ansible Network
# interface GigabitEthernet3
#  description Configured and Merged by Ansible Network
#  no switchport

# Using replaced

# Before state:
# -------------
#
# vios#show running-config | section ^interface
# interface Loopback888
#  no ip address
# interface Loopback999
#  no ip address
# interface GigabitEthernet1
#  description Management interface do not change
#  ip address dhcp
#  negotiation auto
# interface GigabitEthernet2
#  ip address dhcp
#  speed 1000
#  no negotiation auto
# interface GigabitEthernet3
#  no ip address
#  speed 1000
#  no negotiation auto
# interface GigabitEthernet4
#  no ip address
#  shutdown
#  negotiation auto
# interface Vlan50
#  ip address dhcp hostname testHostname

- name: Replaces device configuration of listed interfaces with provided configuration
  cisco.ios.ios_interfaces:
    config:
      - name: GigabitEthernet3
        description: Configured and Replaced by Ansible Network
        enabled: false
        speed: 1000
    state: replaced

Scanned by Steampunk Spotter

# Task Output
# -----------
#
# before:
# - description: Management interface do not change
#   enabled: true
#   name: GigabitEthernet1
# - enabled: true
#   name: GigabitEthernet2
#   speed: '1000'
# - enabled: true
#   name: GigabitEthernet3
#   speed: '1000'
# - enabled: false
#   name: GigabitEthernet4
# - enabled: true
#   name: Loopback888
# - enabled: true
#   name: Loopback999
# - enabled: true
#   name: Vlan50
# commands:
# - interface GigabitEthernet3
# - description Configured and Replaced by Ansible Network
# - shutdown
# after:
# - description: Management interface do not change
#   enabled: true
#   name: GigabitEthernet1
# - enabled: true
#   name: GigabitEthernet2
#   speed: '1000'
# - description: Configured and Replaced by Ansible Network
#   enabled: false
#   name: GigabitEthernet3
#   speed: '1000'
# - enabled: false
#   name: GigabitEthernet4
# - enabled: true
#   name: Loopback888
# - enabled: true
#   name: Loopback999
# - enabled: true
#   name: Vlan50

# After state:
# -------------
#
# vios#show running-config | section ^interface
# interface Loopback888
#  no ip address
# interface Loopback999
#  no ip address
# interface GigabitEthernet1
#  description Management interface do not change
#  ip address dhcp
#  negotiation auto
# interface GigabitEthernet2
#  ip address dhcp
#  speed 1000
#  no negotiation auto
# interface GigabitEthernet3
#  description Configured and Replaced by Ansible Network
#  no ip address
#  shutdown
#  speed 1000
#  no negotiation auto
# interface GigabitEthernet4
#  no ip address
#  shutdown
#  negotiation auto
# interface Vlan50
#  ip address dhcp hostname testHostname

# Using overridden

# Before state:
# -------------
#
# vios#show running-config | section ^interface
# interface Loopback888
#  no ip address
# interface Loopback999
#  no ip address
# interface GigabitEthernet1
#  description Management interface do not change
#  ip address dhcp
#  negotiation auto
# interface GigabitEthernet2
#  ip address dhcp
#  speed 1000
#  no negotiation auto
# interface GigabitEthernet3
#  description Configured and Replaced by Ansible Network
#  no ip address
#  shutdown
#  speed 1000
#  no negotiation auto
# interface GigabitEthernet4
#  no ip address
#  shutdown
#  negotiation auto
# interface Vlan50
#  ip address dhcp hostname testHostname

- name: Override device configuration of all interfaces with provided configuration
  cisco.ios.ios_interfaces:
    config:
      - description: Management interface do not change
        enabled: true
        name: GigabitEthernet1
      - name: GigabitEthernet2
        description: Configured and Overridden by Ansible Network
        speed: 10000
      - name: GigabitEthernet3
        description: Configured and Overridden by Ansible Network
        enabled: false
    state: overridden

Scanned by Steampunk Spotter

# Task Output
# -----------
#
# before:
# - description: Management interface do not change
#   enabled: true
#   name: GigabitEthernet1
# - enabled: true
#   name: GigabitEthernet2
#   speed: '1000'
# - description: Configured and Replaced by Ansible Network
#   enabled: false
#   name: GigabitEthernet3
#   speed: '1000'
# - enabled: false
#   name: GigabitEthernet4
# - enabled: true
#   name: Loopback888
# - enabled: true
#   name: Loopback999
# - enabled: true
#   name: Vlan50
# commands:
# - interface loopback888
# - shutdown
# - interface loopback999
# - shutdown
# - interface Vlan50
# - shutdown
# - interface GigabitEthernet2
# - description Configured and Overridden by Ansible Network
# - speed 10000
# - interface GigabitEthernet3
# - description Configured and Overridden by Ansible Network
# - no speed 1000
# after:
# - description: Management interface do not change
#   enabled: true
#   name: GigabitEthernet1
# - description: Configured and Overridden by Ansible Network
#   enabled: true
#   name: GigabitEthernet2
#   speed: '10000'
# - description: Configured and Overridden by Ansible Network
#   enabled: false
#   name: GigabitEthernet3
#   speed: '1000'
# - enabled: false
#   name: GigabitEthernet4
# - enabled: false
#   name: Loopback888
# - enabled: false
#   name: Loopback999
# - enabled: false
#   name: Vlan50

# After state:
# -------------
#
# vios#show running-config | section ^interface
# interface Loopback888
#  no ip address
#  shutdown
# interface Loopback999
#  no ip address
#  shutdown
# interface GigabitEthernet1
#  description Management interface do not change
#  ip address dhcp
#  negotiation auto
# interface GigabitEthernet2
#  description Configured and Overridden by Ansible Network
#  ip address dhcp
#  speed 10000
#  no negotiation auto
# interface GigabitEthernet3
#  description Configured and Overridden by Ansible Network
#  no ip address
#  shutdown
#  speed 1000
#  no negotiation auto
# interface GigabitEthernet4
#  no ip address
#  shutdown
#  negotiation auto
# interface Vlan50
#  ip address dhcp hostname testHostname
#  shutdown

# Using Deleted

# Before state:
# -------------
#
# vios#show running-config | section ^interface
# interface Loopback888
#  no ip address
#  shutdown
# interface Loopback999
#  no ip address
#  shutdown
# interface GigabitEthernet1
#  description Management interface do not change
#  ip address dhcp
#  negotiation auto
# interface GigabitEthernet2
#  description Configured and Overridden by Ansible Network
#  ip address dhcp
#  speed 10000
#  no negotiation auto
# interface GigabitEthernet3
#  description Configured and Overridden by Ansible Network
#  no ip address
#  shutdown
#  speed 1000
#  no negotiation auto
# interface GigabitEthernet4
#  no ip address
#  shutdown
#  negotiation auto
# interface Vlan50
#  ip address dhcp hostname testHostname
#  shutdown

- name: "Delete interface attributes (Note: This won't delete the interface itself)"
  cisco.ios.ios_interfaces:
    config:
      - name: GigabitEthernet2
    state: deleted

Scanned by Steampunk Spotter

# Task Output
# -----------
#
# before:
# - description: Management interface do not change
#   enabled: true
#   name: GigabitEthernet1
# - description: Configured and Overridden by Ansible Network
#   enabled: true
#   name: GigabitEthernet2
#   speed: '10000'
# - description: Configured and Overridden by Ansible Network
#   enabled: false
#   name: GigabitEthernet3
#   speed: '1000'
# - enabled: false
#   name: GigabitEthernet4
# - enabled: false
#   name: Loopback888
# - enabled: false
#   name: Loopback999
# - enabled: false
#   name: Vlan50
# commands:
# - interface GigabitEthernet2
# - no description Configured and Overridden by Ansible Network
# - no speed 10000
# - shutdown
# after:
# - description: Management interface do not change
#   enabled: true
#   name: GigabitEthernet1
# - enabled: false
#   name: GigabitEthernet2
#   speed: '1000'
# - description: Configured and Overridden by Ansible Network
#   enabled: false
#   name: GigabitEthernet3
#   speed: '1000'
# - enabled: false
#   name: GigabitEthernet4
# - enabled: false
#   name: Loopback888
# - enabled: false
#   name: Loopback999
# - enabled: false
#   name: Vlan50

# After state:
# -------------
#
# vios#show running-config | section ^interface
# interface Loopback888
#  no ip address
#  shutdown
# interface Loopback999
#  no ip address
#  shutdown
# interface GigabitEthernet1
#  description Management interface do not change
#  ip address dhcp
#  negotiation auto
# interface GigabitEthernet2
#  ip address dhcp
#  shutdown
#  speed 1000
#  no negotiation auto
# interface GigabitEthernet3
#  description Configured and Overridden by Ansible Network
#  no ip address
#  shutdown
#  speed 1000
#  no negotiation auto
# interface GigabitEthernet4
#  no ip address
#  shutdown
#  negotiation auto
# interface Vlan50
#  ip address dhcp hostname testHostname
#  shutdown

# Using Purged

# Before state:
# -------------
#
# vios#show running-config | section ^interface
# interface Loopback888
#  no ip address
#  shutdown
# interface Loopback999
#  no ip address
#  shutdown
# interface GigabitEthernet1
#  description Management interface do not change
#  ip address dhcp
#  negotiation auto
# interface GigabitEthernet2
#  ip address dhcp
#  shutdown
#  speed 1000
#  no negotiation auto
# interface GigabitEthernet3
#  description Configured and Overridden by Ansible Network
#  no ip address
#  shutdown
#  speed 1000
#  no negotiation auto
# interface GigabitEthernet4
#  no ip address
#  shutdown
#  negotiation auto
# interface Vlan50
#  ip address dhcp hostname testHostname
#  shutdown

- name: "Purge given interfaces (Note: This will delete the interface itself)"
  cisco.ios.ios_interfaces:
    config:
      - name: Loopback888
      - name: Vlan50
    state: purged

Scanned by Steampunk Spotter

# Task Output
# -----------
#
# before:
# - description: Management interface do not change
#   enabled: true
#   name: GigabitEthernet1
# - enabled: false
#   name: GigabitEthernet2
#   speed: '1000'
# - description: Configured and Overridden by Ansible Network
#   enabled: false
#   name: GigabitEthernet3
#   speed: '1000'
# - enabled: false
#   name: GigabitEthernet4
# - enabled: false
#   name: Loopback888
# - enabled: false
#   name: Loopback999
# - enabled: false
#   name: Vlan50
# commands:
# - no interface loopback888
# - no interface Vlan50
# after:
# - description: Management interface do not change
#   enabled: true
#   name: GigabitEthernet1
# - enabled: false
#   name: GigabitEthernet2
#   speed: '1000'
# - description: Configured and Overridden by Ansible Network
#   enabled: false
#   name: GigabitEthernet3
#   speed: '1000'
# - enabled: false
#   name: GigabitEthernet4
# - enabled: false
#   name: Loopback999

# After state:
# -------------
#
# vios#show running-config | section ^interface
# interface Loopback999
#  no ip address
#  shutdown
# interface GigabitEthernet1
#  description Management interface do not change
#  ip address dhcp
#  negotiation auto
# interface GigabitEthernet2
#  ip address dhcp
#  shutdown
#  speed 1000
#  no negotiation auto
# interface GigabitEthernet3
#  description Configured and Overridden by Ansible Network
#  no ip address
#  shutdown
#  speed 1000
#  no negotiation auto
# interface GigabitEthernet4
#  no ip address
#  shutdown
#  negotiation auto

# Using gathered

# Before state:
# -------------
#
# vios#sh running-config | section ^interface
# interface Loopback999
#  no ip address
#  shutdown
# interface GigabitEthernet1
#  description Management interface do not change
#  ip address dhcp
#  negotiation auto
# interface GigabitEthernet2
#  ip address dhcp
#  shutdown
#  speed 1000
#  no negotiation auto
# interface GigabitEthernet3
#  description Configured and Overridden by Ansible Network
#  no ip address
#  shutdown
#  speed 1000
#  no negotiation auto
# interface GigabitEthernet4
#  no ip address
#  shutdown
#  negotiation auto

- name: Gather facts of interfaces
  cisco.ios.ios_interfaces:
    config:
    state: gathered

Scanned by Steampunk Spotter

# Task Output
# -----------
#
# gathered:
# - description: Management interface do not change
#   enabled: true
#   name: GigabitEthernet1
# - enabled: false
#   name: GigabitEthernet2
#   speed: '1000'
# - description: Configured and Overridden by Ansible Network
#   enabled: false
#   name: GigabitEthernet3
#   speed: '1000'
# - enabled: false
#   name: GigabitEthernet4
# - enabled: false
#   name: Loopback999

# Using rendered

- name: Render the commands for provided configuration
  cisco.ios.ios_interfaces:
    config:
      - name: GigabitEthernet1
        description: Configured by Ansible-Network
        mtu: 110
        enabled: true
        duplex: half
      - name: GigabitEthernet2
        description: Configured by Ansible-Network
        mtu: 2800
        enabled: false
        speed: 100
        duplex: full
    state: rendered

Scanned by Steampunk Spotter

# Task Output
# -----------
#
# rendered:
# - interface GigabitEthernet1
# - description Configured by Ansible-Network
# - mtu 110
# - duplex half
# - no shutdown
# - interface GigabitEthernet2
# - description Configured by Ansible-Network
# - speed 100
# - mtu 2800
# - duplex full
# - shutdown

# Using parsed

# File: parsed.cfg
# ----------------
#
# interface Loopback999
#  no ip address
#  shutdown
# interface GigabitEthernet1
#  description Management interface do not change
#  ip address dhcp
#  negotiation auto
# interface GigabitEthernet2
#  ip address dhcp
#  shutdown
#  speed 1000
#  no negotiation auto
# interface GigabitEthernet3
#  description Configured and Overridden by Ansible Network
#  no ip address
#  shutdown
#  speed 1000
#  no negotiation auto
# interface GigabitEthernet4
#  no ip address
#  shutdown
#  negotiation auto

- name: Parse the provided configuration
  cisco.ios.ios_interfaces:
    running_config: "{{ lookup('file', 'parsed.cfg') }}"
    state: parsed

Inputs

state:
choices:
- merged
- replaced
- overridden
- deleted
- rendered
- gathered
- purged
- parsed
default: merged
description:
- The state the configuration should be left in
- The states I(rendered), I(gathered) and I(parsed) does not perform any change on
the device.
- The state I(rendered) will transform the configuration in C(config) option to platform
specific CLI commands which will be returned in the I(rendered) key within the result.
For state I(rendered) active connection to remote host is not required.
- The state I(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 I(gathered) key within the result.
- The state I(parsed) reads the configuration from C(running_config) option and transforms
it into JSON format as per the resource module parameters and the value is returned
in the I(parsed) key within the result. The value of C(running_config) option should
be the same format as the output of command I(show running-config | include ip route|ipv6
route) executed on device. For state I(parsed) active connection to remote host
is not required.
- The state I(purged) negates virtual/logical interfaces that are specified in task
from running-config.
type: str

config:
description: A dictionary of interface options
elements: dict
suboptions:
description:
description:
- Interface description.
type: str
duplex:
choices:
- full
- half
- auto
description:
- Interface link status. Applicable for Ethernet interfaces only, either in half
duplex, full duplex or in automatic state which negotiates the duplex automatically.
type: str
enabled:
default: true
description:
- Administrative state of the interface.
- Set the value to C(true) to administratively enable the interface or C(false)
to disable it.
type: bool
mode:
choices:
- layer2
- layer3
description:
- Manage Layer2 or Layer3 state of the interface.
- For a Layer 2 appliance mode Layer2 adds switchport command ( default impacts
idempotency).
- For a Layer 2 appliance mode Layer3 adds no switchport command.
- For a Layer 3 appliance mode Layer3/2 has no impact rather command fails on
apply.
type: str
mtu:
description:
- MTU for a specific interface. Applicable for Ethernet interfaces only.
- Refer to vendor documentation for valid values.
type: int
name:
description:
- Full name of interface, e.g. GigabitEthernet0/2, loopback999.
required: true
type: str
speed:
description:
- Interface link speed. Applicable for Ethernet interfaces only.
type: str
template:
description:
- IOS template name.
type: str
type: list

running_config:
description:
- This option is used only with state I(parsed).
- The value of this option should be the output received from the IOS device by executing
the command B(show running-config | section ^interface).
- The state I(parsed) reads the configuration from C(running_config) option and transforms
it into Ansible structured data as per the resource module's argspec and the value
is then returned in the I(parsed) key within the result.
type: str

Outputs

after:
  description: The resulting configuration after module execution.
  returned: when changed
  sample: 'This output will always be in the same format as the module argspec.

    '
  type: dict
before:
  description: The configuration prior to the module execution.
  returned: when I(state) is C(merged), C(replaced), C(overridden), C(deleted) or
    C(purged)
  sample: 'This output will always be in the same format as the module argspec.

    '
  type: dict
commands:
  description: The set of commands pushed to the remote device.
  returned: when I(state) is C(merged), C(replaced), C(overridden), C(deleted) or
    C(purged)
  sample:
  - interface GigabitEthernet2
  - speed 1200
  - mtu 1800
  type: list
gathered:
  description: Facts about the network resource gathered from the remote device as
    structured data.
  returned: when I(state) is C(gathered)
  sample: 'This output will always be in the same format as the module argspec.

    '
  type: list
parsed:
  description: The device native config provided in I(running_config) option parsed
    into structured data as per module argspec.
  returned: when I(state) is C(parsed)
  sample: 'This output will always be in the same format as the module argspec.

    '
  type: list
rendered:
  description: The provided configuration in the task rendered in device-native format
    (offline).
  returned: when I(state) is C(rendered)
  sample:
  - interface GigabitEthernet1
  - description Interface description
  - shutdown
  type: list