ios_l2_interfaces – Manage Layer-2 interface on Cisco IOS devices

New in version 2.9.

Synopsis
Parameters
Notes
Examples
Return Values
Status

Synopsis

This module provides declarative management of Layer-2 interface on Cisco IOS devices.

Parameters

Parameter			Choices/Defaults	Comments
config list / elements=dictionary				A dictionary of Layer-2 interface options
	access dictionary			Switchport mode access command to configure the interface as a layer 2 access.
		vlan integer		Configure given VLAN in access port. It's used as the access VLAN ID.
	name string / required			Full name of the interface excluding any logical unit number, i.e. GigabitEthernet0/1.
	trunk dictionary			Switchport mode trunk command to configure the interface as a Layer 2 trunk. Note The encapsulation is always set to dot1q.
		allowed_vlans list		List of allowed VLANs in a given trunk port. These are the only VLANs that will be configured on the trunk.
		encapsulation string	Choices: dot1q isl negotiate	Trunking encapsulation when interface is in trunking mode.
		native_vlan integer		Native VLAN to be configured in trunk port. It's used as the trunk native VLAN ID.
		pruning_vlans list		Pruning VLAN to be configured in trunk port. It's used as the trunk pruning VLAN ID.
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:
# -------------
#
# viosl2#show running-config | section ^interface
# interface GigabitEthernet0/1
#  description Configured by Ansible
#  negotiation auto
# interface GigabitEthernet0/2
#  description This is test
#  switchport access vlan 20
#  media-type rj45
#  negotiation auto

- name: Merge provided configuration with device configuration
  ios_l2_interfaces:
    config:
      - name: GigabitEthernet0/1
        access:
          vlan: 10
      - name: GigabitEthernet0/2
        trunk:
          allowed_vlan: 10-20, 40
          native_vlan: 20
          pruning_vlan: 10,20
          encapsulation: dot1q
    state: merged

# After state:
# ------------
#
# viosl2#show running-config | section ^interface
# interface GigabitEthernet0/1
#  description Configured by Ansible
#  switchport access vlan 10
#  negotiation auto
# interface GigabitEthernet0/2
#  description This is test
#  switchport trunk allowed vlan 10-20,40
#  switchport trunk encapsulation dot1q
#  switchport trunk native vlan 20
#  switchport trunk pruning vlan 10,20
#  media-type rj45
#  negotiation auto

# Using replaced

# Before state:
# -------------
#
# viosl2#show running-config | section ^interface
# interface GigabitEthernet0/1
#  description Configured by Ansible
#  switchport access vlan 20
#  negotiation auto
# interface GigabitEthernet0/2
#  description This is test
#  switchport access vlan 20
#  media-type rj45
#  negotiation auto

- name: Replaces device configuration of listed l2 interfaces with provided configuration
  ios_l2_interfaces:
    config:
      - name: GigabitEthernet0/2
        trunk:
        - allowed_vlan: 20-25,40
          native_vlan: 20
          pruning_vlan: 10
          encapsulation: isl
    state: replaced

# After state:
# -------------
#
# viosl2#show running-config | section ^interface
# interface GigabitEthernet0/1
#  description Configured by Ansible
#  switchport access vlan 20
#  negotiation auto
# interface GigabitEthernet0/2
#  description This is test
#  switchport trunk allowed vlan 20-25,40
#  switchport trunk encapsulation isl
#  switchport trunk native vlan 20
#  switchport trunk pruning vlan 10
#  media-type rj45
#  negotiation auto

# Using overridden

# Before state:
# -------------
#
# viosl2#show running-config | section ^interface
# interface GigabitEthernet0/1
#  description Configured by Ansible
#  switchport trunk encapsulation dot1q
#  switchport trunk native vlan 20
#  negotiation auto
# interface GigabitEthernet0/2
#  description This is test
#  switchport access vlan 20
#  switchport trunk encapsulation dot1q
#  switchport trunk native vlan 20
#  media-type rj45
#  negotiation auto

- name: Override device configuration of all l2 interfaces with provided configuration
  ios_l2_interfaces:
    config:
      - name: GigabitEthernet0/2
        access:
          vlan: 20
    state: overridden

# After state:
# -------------
#
# viosl2#show running-config | section ^interface
# interface GigabitEthernet0/1
#  description Configured by Ansible
#  negotiation auto
# interface GigabitEthernet0/2
#  description This is test
#  switchport access vlan 20
#  media-type rj45
#  negotiation auto

# Using Deleted

# Before state:
# -------------
#
# viosl2#show running-config | section ^interface
# interface GigabitEthernet0/1
#  description Configured by Ansible
#  switchport access vlan 20
#  negotiation auto
# interface GigabitEthernet0/2
#  description This is test
#  switchport access vlan 20
#  switchport trunk allowed vlan 20-40,60,80
#  switchport trunk encapsulation dot1q
#  switchport trunk native vlan 10
#  switchport trunk pruning vlan 10
#  media-type rj45
#  negotiation auto

- name: Delete IOS L2 interfaces as in given arguments
  ios_l2_interfaces:
    config:
      - name: GigabitEthernet0/1
    state: deleted

# After state:
# -------------
#
# viosl2#show running-config | section ^interface
# interface GigabitEthernet0/1
#  description Configured by Ansible
#  negotiation auto
# interface GigabitEthernet0/2
#  description This is test
#  switchport access vlan 20
#  switchport trunk allowed vlan 20-40,60,80
#  switchport trunk encapsulation dot1q
#  switchport trunk native vlan 10
#  switchport trunk pruning vlan 10
#  media-type rj45
#  negotiation auto


# Using Deleted without any config passed
#"(NOTE: This will delete all of configured resource module attributes from each configured interface)"

# Before state:
# -------------
#
# viosl2#show running-config | section ^interface
# interface GigabitEthernet0/1
#  description Configured by Ansible
#  switchport access vlan 20
#  negotiation auto
# interface GigabitEthernet0/2
#  description This is test
#  switchport access vlan 20
#  switchport trunk allowed vlan 20-40,60,80
#  switchport trunk encapsulation dot1q
#  switchport trunk native vlan 10
#  switchport trunk pruning vlan 10
#  media-type rj45
#  negotiation auto

- name: Delete IOS L2 interfaces as in given arguments
  ios_l2_interfaces:
    state: deleted

# After state:
# -------------
#
# viosl2#show running-config | section ^interface
# interface GigabitEthernet0/1
#  description Configured by Ansible
#  negotiation auto
# interface GigabitEthernet0/2
#  description This is test
#  media-type rj45
#  negotiation 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 GigabitEthernet0/1', 'switchport access vlan 20']

Status

This module is not guaranteed to have a backwards compatible interface. [preview]
This module is maintained by the Ansible Network Team. [network]

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.

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.9/modules/ios_l2_interfaces_module.html