ios_l3_interfaces – Manage Layer-3 interface on Cisco IOS devices

From Get docs
Ansible/docs/2.9/modules/ios l3 interfaces module


ios_l3_interfaces – Manage Layer-3 interface on Cisco IOS devices

New in version 2.9.


Synopsis

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

Parameters

Parameter Choices/Defaults Comments

config

list / elements=dictionary

A dictionary of Layer-3 interface options

ipv4

list / elements=dictionary

IPv4 address to be set for the Layer-3 interface mentioned in name option. The address format is /, the mask is number in range 0-32 eg. 192.168.0.1/24.

address

string

Configures the IPv4 address for Interface.

dhcp_client

integer

Configures and specifies client-id to use over DHCP ip. Note, This option shall work only when dhcp is configured as IP.

GigabitEthernet interface number

dhcp_hostname

string

Configures and specifies value for hostname option over DHCP ip. Note, This option shall work only when dhcp is configured as IP.

secondary

boolean

  • no
  • yes

Configures the IP address as a secondary address.

ipv6

list / elements=dictionary

IPv6 address to be set for the Layer-3 interface mentioned in name option.

The address format is /, the mask is number in range 0-128 eg. fd5d:12c9:2201:1::1/64

address

string

Configures the IPv6 address for Interface.

name

string / required

Full name of the interface excluding any logical unit number, i.e. GigabitEthernet0/1.

state

string

  • merged

  • replaced
  • overridden
  • deleted

The state of the configuration after module completion



Examples

---
# Using merged
#
# Before state:
# -------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
#  description Configured by Ansible
#  ip address 10.1.1.1 255.255.255.0
#  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 Network
#  no ip address
# interface GigabitEthernet0/3.100
#  encapsulation dot1Q 20

- name: Merge provided configuration with device configuration
  ios_l3_interfaces:
    config:
      - name: GigabitEthernet0/1
        ipv4:
        - address: 192.168.0.1/24
          secondary: True
      - name: GigabitEthernet0/2
        ipv4:
        - address: 192.168.0.2/24
      - name: GigabitEthernet0/3
        ipv6:
        - address: fd5d:12c9:2201:1::1/64
      - name: GigabitEthernet0/3.100
        ipv4:
        - address: 192.168.0.3/24
    state: merged

# After state:
# ------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
#  description Configured by Ansible
#  ip address 10.1.1.1 255.255.255.0
#  ip address 192.168.0.1 255.255.255.0 secondary
#  duplex auto
#  speed auto
# interface GigabitEthernet0/2
#  description This is test
#  ip address 192.168.0.2 255.255.255.0
#  duplex auto
#  speed 1000
# interface GigabitEthernet0/3
#  description Configured by Ansible Network
#  ipv6 address FD5D:12C9:2201:1::1/64
# interface GigabitEthernet0/3.100
#  encapsulation dot1Q 20
#  ip address 192.168.0.3 255.255.255.0

# Using replaced
#
# Before state:
# -------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
#  description Configured by Ansible
#  ip address 10.1.1.1 255.255.255.0
#  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 Network
#  ip address 192.168.2.0 255.255.255.0
# interface GigabitEthernet0/3.100
#  encapsulation dot1Q 20
#  ip address 192.168.0.2 255.255.255.0

- name: Replaces device configuration of listed interfaces with provided configuration
  ios_l3_interfaces:
    config:
      - name: GigabitEthernet0/2
        ipv4:
        - address: 192.168.2.0/24
      - name: GigabitEthernet0/3
        ipv4:
        - address: dhcp
          dhcp_client: 2
          dhcp_hostname: test.com
      - name: GigabitEthernet0/3.100
        ipv4:
        - address: 192.168.0.3/24
          secondary: True
    state: replaced

# After state:
# ------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
#  description Configured by Ansible
#  ip address 10.1.1.1 255.255.255.0
#  duplex auto
#  speed auto
# interface GigabitEthernet0/2
#  description This is test
#  ip address 192.168.2.1 255.255.255.0
#  duplex auto
#  speed 1000
# interface GigabitEthernet0/3
#  description Configured by Ansible Network
#  ip address dhcp client-id GigabitEthernet0/2 hostname test.com
# interface GigabitEthernet0/3.100
#  encapsulation dot1Q 20
#  ip address 192.168.0.2 255.255.255.0
#  ip address 192.168.0.3 255.255.255.0 secondary

# Using overridden
#
# Before state:
# -------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
#  description Configured by Ansible
#  ip address 10.1.1.1 255.255.255.0
#  duplex auto
#  speed auto
# interface GigabitEthernet0/2
#  description This is test
#  ip address 192.168.2.1 255.255.255.0
#  duplex auto
#  speed 1000
# interface GigabitEthernet0/3
#  description Configured by Ansible Network
#  ipv6 address FD5D:12C9:2201:1::1/64
# interface GigabitEthernet0/3.100
#  encapsulation dot1Q 20
#  ip address 192.168.0.2 255.255.255.0

- name: Override device configuration of all interfaces with provided configuration
  ios_l3_interfaces:
    config:
      - name: GigabitEthernet0/2
        ipv4:
        - address: 192.168.0.1/24
      - name: GigabitEthernet0/3.100
        ipv6:
        - address: autoconfig
    state: overridden

# 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 This is test
#  ip address 192.168.0.1 255.255.255.0
#  duplex auto
#  speed 1000
# interface GigabitEthernet0/3
#  description Configured by Ansible Network
# interface GigabitEthernet0/3.100
#  encapsulation dot1Q 20
#  ipv6 address autoconfig

# Using Deleted
#
# Before state:
# -------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
#  ip address 192.0.2.10 255.255.255.0
#  shutdown
#  duplex auto
#  speed auto
# interface GigabitEthernet0/2
#  description Configured by Ansible Network
#  ip address 192.168.1.0 255.255.255.0
# interface GigabitEthernet0/3
#  description Configured by Ansible Network
#  ip address 192.168.0.1 255.255.255.0
#  shutdown
#  duplex full
#  speed 10
#  ipv6 address FD5D:12C9:2201:1::1/64
# interface GigabitEthernet0/3.100
#  encapsulation dot1Q 20
#  ip address 192.168.0.2 255.255.255.0

- name: "Delete attributes of given interfaces (NOTE: This won't delete the interface itself)"
  ios_l3_interfaces:
    config:
      - name: GigabitEthernet0/2
      - name: GigabitEthernet0/3.100
    state: deleted

# After state:
# -------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
#  no ip address
#  shutdown
#  duplex auto
#  speed auto
# interface GigabitEthernet0/2
#  description Configured by Ansible Network
#  no ip address
# interface GigabitEthernet0/3
#  description Configured by Ansible Network
#  ip address 192.168.0.1 255.255.255.0
#  shutdown
#  duplex full
#  speed 10
#  ipv6 address FD5D:12C9:2201:1::1/64
# interface GigabitEthernet0/3.100
#  encapsulation dot1Q 20

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

#
# Before state:
# -------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
#  ip address 192.0.2.10 255.255.255.0
#  shutdown
#  duplex auto
#  speed auto
# interface GigabitEthernet0/2
#  description Configured by Ansible Network
#  ip address 192.168.1.0 255.255.255.0
# interface GigabitEthernet0/3
#  description Configured by Ansible Network
#  ip address 192.168.0.1 255.255.255.0
#  shutdown
#  duplex full
#  speed 10
#  ipv6 address FD5D:12C9:2201:1::1/64
# interface GigabitEthernet0/3.100
#  encapsulation dot1Q 20
#  ip address 192.168.0.2 255.255.255.0

- name: "Delete L3 attributes of ALL interfaces together (NOTE: This won't delete the interface itself)"
  ios_l3_interfaces:
    state: deleted

# After state:
# -------------
#
# vios#show running-config | section ^interface
# interface GigabitEthernet0/1
#  no ip address
#  shutdown
#  duplex auto
#  speed auto
# interface GigabitEthernet0/2
#  description Configured by Ansible Network
#  no ip address
# interface GigabitEthernet0/3
#  description Configured by Ansible Network
#  shutdown
#  duplex full
#  speed 10
# interface GigabitEthernet0/3.100
#  encapsulation dot1Q 20

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', 'ip address 192.168.0.2 255.255.255.0']




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.


© 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_l3_interfaces_module.html