Ethernet

Ethernet interfaces provide the fundamental physical and logical connectivity for network devices, supporting various speeds from Fast Ethernet (100 Mbps) to multi-gigabit rates (1G, 2.5G, 5G, 10G, 25G, 40G, 100G) with comprehensive Layer 2 switching and Layer 3 routing capabilities. They offer extensive configuration options including switchport modes (access, trunk), VLAN assignments, spanning tree parameters, quality of service policies, security features, and advanced protocols such as OSPF, BFD, and IPv6. Ethernet interfaces serve as the backbone of modern networks, enabling both access layer connectivity for end devices and high-performance trunk links between network infrastructure components while supporting features like port channels, network access control, and comprehensive monitoring capabilities.

Diagram

Classes

interfaces (iosxe.devices.configuration)

Name	Type	Constraint	Mandatory	Default Value
ethernets	List	[ethernets]	No

ethernets (iosxe.devices.configuration.interfaces)

Name	Type	Constraint	Mandatory	Default Value
type	Choice	GigabitEthernet, TwoGigabitEthernet, FastEthernet, Ethernet, Port-channel, FiveGigabitEthernet, TenGigabitEthernet, TwentyFiveGigE, FortyGigabitEthernet, FiftyGigabitEthernet, HundredGigE, TwoHundredGigE, FourHundredGigE	Yes
id	String		Yes
managed	Boolean	true, false	No
interface_groups	List	String	No
interface_group_policy	Choice	merge, replace	No
media_type	Choice	auto-select, rj45, sfp	No
bandwidth	Integer	min: 1, max: 200000000	No
mtu	Integer	min: 64, max: 18000	No
description	String		No
shutdown	Boolean	true, false	No
vrf_forwarding	String		No
ipv4	Class	[ipv4]	No
ipv6	Class	[ipv6]	No
bfd	Class	[bfd]	No
spanning_tree	Class	[spanning_tree]	No
speed	Choice	100, 1000, 2500, 5000, 10000, 25000, 40000, 50000, 100000, auto	No
speed_nonegotiate	Boolean	true, false	No
port_channel_id	Integer	min: 1, max: 512	No
port_channel_mode	Choice	active, auto, desirable, on, passive	No
source_templates	List	[source_templates]	No
arp_timeout	Integer	min: 0, max: 2147483	No
negotiation_auto	Boolean	true, false	No
service_policy_input	String		No
service_policy_output	String		No
load_interval	Integer	min: 30, max: 600	No
snmp_trap_link_status	Boolean	true, false	No
logging_event_link_status	Boolean	true, false	No
device_tracking	Boolean	true, false	No
device_tracking_attached_policies	List	String	No
encapsulation_dot1q_vlan_id	Integer	min: 1, max: 4094	No
nbar_protocol_discovery	Boolean	true, false	No
mpls	Class	[mpls]	No
ospf	Class	[ospf]	No
ospfv3	Class	[ospfv3]	No
isis	Class	[isis]	No
pim	Class	[pim]	No
igmp	Class	[igmp]	No
switchport	Class	[switchport]	No
network_access_control	Class	[network_access_control]	No
auto_qos	Class	[auto_qos]	No
cdp	Boolean	true, false	No
cdp_tlv_app	Boolean	true, false	No
cdp_tlv_location	Boolean	true, false	No
cdp_tlv_server_location	Boolean	true, false	No
evpn_ethernet_segments	List	[evpn_ethernet_segments]	No
carrier_delay_msec	Integer	min: 0, max: 1000	No
hold_queue_in	Integer	min: 0, max: 240000	No
hold_queue_out	Integer	min: 0, max: 240000	No
vrrp_v2	List	[vrrp_v2]	No
zone_member_security	String		No

ipv4 (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
address	IP		No
address_mask	IP		No
proxy_arp	Boolean	true, false	No
arp_inspection_trust	Boolean	true, false	No
arp_inspection_limit_rate	Integer	min: 0, max: 4294967295	No
dhcp_snooping_trust	Boolean	true, false	No
dhcp_relay_source_interface_type	Choice	Loopback, Vlan, GigabitEthernet, TwoGigabitEthernet, FiveGigabitEthernet, TenGigabitEthernet, TwentyFiveGigabitEthernet, FortyGigabitEthernet, FiftyGigabitEthernet, HundredGigabitEthernet, PortChannel	No
dhcp_relay_source_interface_id	Any	String or Integer[min: 0]	No
dhcp_relay_information_option_vpn_id	Boolean	true, false	No
helper_addresses	List	[helper_addresses]	No
access_group_in	String		No
access_group_out	String		No
flow_monitors	List	[flow_monitors]	No
redirects	Boolean	true, false	No
unreachables	Boolean	true, false	No
unnumbered_interface_type	Choice	Loopback, Vlan, GigabitEthernet, TwoGigabitEthernet, FiveGigabitEthernet, TenGigabitEthernet, TwentyFiveGigabitEthernet, FortyGigabitEthernet, FiftyGigabitEthernet, HundredGigabitEthernet, PortChannel	No
unnumbered_interface_id	Any	String or Integer[min: 0]	No
nat_inside	Boolean	true, false	No
nat_outside	Boolean	true, false	No
address_dhcp	Boolean	true, false	No
verify_unicast_source_reachable_via	Choice	any, rx	No
verify_unicast_source_allow_self_ping	Boolean	true, false	No
verify_unicast_source_allow_default	Boolean	true, false	No

ipv6 (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
enable	Boolean	true, false	No
addresses	List	[addresses]	No
link_local_addresses	List	IP	No
address_autoconfig_default	Boolean	true, false	No
address_dhcp	Boolean	true, false	No
mtu	Integer	min: 1280, max: 9976	No
nd_ra_suppress_all	Boolean	true, false	No
flow_monitors	List	[flow_monitors]	No
pim	Class	[pim]	No

bfd (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
template	String		No
enable	Boolean	true, false	No
local_address	IP		No
interval	Integer	min: 50, max: 9999	No
interval_min_rx	Integer	min: 50, max: 9999	No
interval_multiplier	Integer	min: 3, max: 50	No
echo	Boolean	true, false	No

spanning_tree (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
portfast	Boolean	true, false	No
portfast_disable	Boolean	true, false	No
bpduguard	Boolean	true, false	No
bpduguard_disable	Boolean	true, false	No
guard	Choice	loop, none, root	No
link_type	Choice	shared, point-to-point	No
portfast_trunk	Boolean	true, false	No
portfast_edge	Boolean	true, false	No

source_templates (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
name	String		Yes
merge	Boolean	true, false	No

mpls (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
ip	Boolean	true, false	No
mtu	Integer		No

ospf (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
authentication_key_chain	String		No
authentication_message_digest	Boolean	true, false	No
authentication_null	Boolean	true, false	No
cost	Integer	min: 1, max: 65535	No
dead_interval	Integer	min: 1, max: 65535	No
hello_interval	Integer	min: 1, max: 65535	No
message_digest_keys	List	[message_digest_keys]	No
mtu_ignore	Boolean	true, false	No
multi_area_ids	List	Any[String or Integer[min: 0]]	No
network_type	Choice	broadcast, non-broadcast, point-to-multipoint, point-to-point	No
priority	Integer	min: 0, max: 255	No
process_ids	List	[process_ids]	No
ttl_security_hops	Integer	min: 1, max: 254	No

ospfv3 (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
bfd	Boolean	true, false	No
cost	Integer	min: 1, max: 65535	No
dead_interval	Integer	min: 1, max: 65535	No
hello_interval	Integer	min: 1, max: 65535	No
mtu_ignore	Boolean	true, false	No
network_type	Choice	broadcast, non-broadcast, point-to-multipoint, point-to-point	No
priority	Integer	min: 0, max: 255	No

isis (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
area_tag	String		No
ipv4_metric_levels	List	[ipv4_metric_levels]	No
network_point_to_point	Boolean	true, false	No

pim (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
passive	Boolean	true, false	No
dense_mode	Boolean	true, false	No
sparse_mode	Boolean	true, false	No
sparse_dense_mode	Boolean	true, false	No
bfd	Boolean	true, false	No
border	Boolean	true, false	No
bsr_border	Boolean	true, false	No
dr_priority	Integer	min: 0, max: 4294967294	No

igmp (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
version	Integer	min: 1, max: 3	No

switchport (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
enable	Boolean	true, false	No
mode	Choice	access, dot1q-tunnel, private-vlan-trunk, private-vlan-host, private-vlan-promiscuous, trunk	No
nonegotiate	Boolean	true, false	No
access_vlan	Integer	min: 1, max: 4094	No
voice_vlan	Any	Integer[min: 1, max: 4094] or Choice[dot1p, none, untagged] or String[Regex: ^.*[\$\%]\{.*$]	No
trunk_allowed_vlans	Class	[trunk_allowed_vlans]	No
trunk_allowed_vlans_legacy	Class	[trunk_allowed_vlans_legacy]	No
trunk_native_vlan_tag	Boolean	true, false	No
trunk_native_vlan_id	Integer	min: 1, max: 4094	No
host	Boolean	true, false	No

network_access_control (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
authentication_periodic	Boolean	true, false	No
authentication_timer_reauthenticate	Integer	min: 1, max: 1073741823	No
authentication_timer_reauthenticate_server	Boolean	true, false	No
mab	Boolean	true, false	No
mab_eap	Boolean	true, false	No
dot1x_pae	Choice	authenticator, supplicant, both	No
dot1x_timeout_auth_period	Integer	min: 1, max: 65535	No
dot1x_timeout_held_period	Integer	min: 1, max: 65535	No
dot1x_timeout_quiet_period	Integer	min: 1, max: 65535	No
dot1x_timeout_ratelimit_period	Integer	min: 1, max: 65535	No
dot1x_timeout_server_timeout	Integer	min: 1, max: 65535	No
dot1x_timeout_start_period	Integer	min: 1, max: 65535	No
dot1x_timeout_supp_timeout	Integer	min: 1, max: 65535	No
dot1x_timeout_tx_period	Integer	min: 1, max: 65535	No
dot1x_max_req	Integer	min: 1, max: 10	No
dot1x_max_reauth_req	Integer	min: 1, max: 10	No

auto_qos (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
classify	Boolean	true, false	No
classify_police	Boolean	true, false	No
trust	Boolean	true, false	No
trust_cos	Boolean	true, false	No
trust_dscp	Boolean	true, false	No
video_cts	Boolean	true, false	No
video_ip_camera	Boolean	true, false	No
video_media_player	Boolean	true, false	No
voip_cisco_phone	Boolean	true, false	No
voip_cisco_softphone	Boolean	true, false	No
voip_trust	Boolean	true, false	No
trust_device	Choice	cisco-phone, cts, ip-camera, media-player	No

evpn_ethernet_segments (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
es_value	Integer	min: 1, max: 65535	Yes

vrrp_v2 (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
group_id	Integer	min: 1, max: 255	Yes
ip_primary_address	IP		No
ip_secondary_addresses	List	IP	No
priority	Integer	min: 1, max: 254	No
preempt	Boolean	true, false	No
preempt_delay_minimum	Integer	min: 0, max: 3600	No
timers_advertise_interval	Integer	min: 1, max: 255	No
authentication_text	String		No
description	String		No
tracks	List	[tracks]	No
shutdown	Boolean	true, false	No

helper_addresses (iosxe.devices.configuration.interfaces.ethernets.ipv4)

Name	Type	Constraint	Mandatory	Default Value
address	IP		Yes
global	Boolean	true, false	No
vrf	String		No

flow_monitors (iosxe.devices.configuration.interfaces.ethernets.ipv4)

Name	Type	Constraint	Mandatory	Default Value
name	String		Yes
direction	Choice	input, output	Yes

addresses (iosxe.devices.configuration.interfaces.ethernets.ipv6)

Name	Type	Constraint	Mandatory	Default Value
prefix	IP		Yes
eui_64	Boolean	true, false	No

pim (iosxe.devices.configuration.interfaces.ethernets.ipv6)

Name	Type	Constraint	Mandatory	Default Value
pim	Boolean	true, false	No
bfd	Boolean	true, false	No
bsr_border	Boolean	true, false	No
dr_priority	Integer	min: 0, max: 4294967295	No

message_digest_keys (iosxe.devices.configuration.interfaces.ethernets.ospf)

Name	Type	Constraint	Mandatory	Default Value
id	Integer	min: 1, max: 255	Yes
md5_auth_key	String		No
md5_auth_type	Choice	0, 7	No

process_ids (iosxe.devices.configuration.interfaces.ethernets.ospf)

Name	Type	Constraint	Mandatory	Default Value
id	Integer	min: 1, max: 65535	No
areas	List	Any[String or Integer[min: 0]]	No

ipv4_metric_levels (iosxe.devices.configuration.interfaces.ethernets.isis)

Name	Type	Constraint	Mandatory	Default Value
level	Choice	level-1, level-2	Yes
value	Integer	min: 1, max: 16777214	Yes

trunk_allowed_vlans (iosxe.devices.configuration.interfaces.ethernets.switchport)

Name	Type	Constraint	Mandatory	Default Value
all	Boolean	true, false	No
none	Boolean	true, false	No
vlans	Class	[vlans]	No
add	Class	[add]	No
except	Class	[except]	No
remove	Class	[remove]	No

trunk_allowed_vlans_legacy (iosxe.devices.configuration.interfaces.ethernets.switchport)

Name	Type	Constraint	Mandatory	Default Value
ids	List	Integer[min: 1, max: 4094]	No
ranges	List	[ranges]	No

tracks (iosxe.devices.configuration.interfaces.ethernets.vrrp_v2)

Name	Type	Constraint	Mandatory	Default Value
object_id	Integer	min: 1, max: 1000	Yes
decrement	Integer	min: 1, max: 255	No

vlans (iosxe.devices.configuration.interfaces.ethernets.switchport.trunk_allowed_vlans)

Name	Type	Constraint	Mandatory	Default Value
ids	List	Integer[min: 1, max: 4094]	No
ranges	List	[ranges]	No

add (iosxe.devices.configuration.interfaces.ethernets.switchport.trunk_allowed_vlans)

Name	Type	Constraint	Mandatory	Default Value
ids	List	Integer[min: 1, max: 4094]	No
ranges	List	[ranges]	No

except (iosxe.devices.configuration.interfaces.ethernets.switchport.trunk_allowed_vlans)

Name	Type	Constraint	Mandatory	Default Value
ids	List	Integer[min: 1, max: 4094]	No
ranges	List	[ranges]	No

remove (iosxe.devices.configuration.interfaces.ethernets.switchport.trunk_allowed_vlans)

Name	Type	Constraint	Mandatory	Default Value
ids	List	Integer[min: 1, max: 4094]	No
ranges	List	[ranges]	No

ranges (iosxe.devices.configuration.interfaces.ethernets.switchport.trunk_allowed_vlans_legacy)

Name	Type	Constraint	Mandatory	Default Value
from	Integer	min: 1, max: 4094	Yes
to	Integer	min: 1, max: 4094	Yes

Guidelines and Limitations

Managed vs Unmanaged Interfaces

• managed attribute: Controls whether Terraform continuously manages the interface configuration. When set to false, Terraform will push the initial configuration but will not continuously read it, detect drift, or reconcile changes. This is useful for:

  • Interfaces whose configuration changes dynamically due to authorization policies
  • Interfaces modified by local scripts or automation
  • Interfaces where configuration drift should be allowed and not corrected
  • Default: true (Terraform fully manages the interface and reconciles drift)

• Usage example:

  interfaces:
    ethernets:
      - id: 1/0/1
        type: GigabitEthernet
        description: Dynamic interface
        managed: false  # Terraform pushes initial config but ignores subsequent changes

MTU Configuration

• mtu attribute: Sets the Maximum Transmission Unit (MTU) for the interface, which defines the largest packet size that can be transmitted. The valid range is 64-18000 bytes depending on platform capabilities.

• Catalyst Platform Requirement: On Catalyst switches, individual interface MTU values cannot exceed the global system MTU. The system MTU must be configured first using the system mtu <value> global configuration command (requires device reload). Interface MTU values can be set to any value up to and including the system MTU.

• Default MTU: Standard Ethernet default is 1500 bytes. Higher values (jumbo frames) improve performance for large data transfers but require end-to-end support.

• Example:

  interfaces:
    ethernets:
      - id: 1/0/1
        type: GigabitEthernet
        mtu: 1600
        description: Server uplink

• Platform-specific notes:

  • Catalyst switches: System MTU limits individual interface MTU (check with show system mtu)
  • Routers: Interface MTU can be configured independently without system MTU constraints

Spanning Tree Portfast Configuration

• spanning_tree_portfast_edge attribute limitation: The spanning_tree_portfast_edge attribute uses a deprecated YANG model path (spanning-tree/portfast/edge) that does not translate to valid CLI commands on Catalyst switch platforms. While the YANG model accepts this configuration for backward compatibility with routers or older platforms, modern Catalyst switches (including Catalyst 9000 series) do not support the spanning-tree portfast edge CLI command. Attempting to configure this attribute on Catalyst switches will result in device configuration rejection errors (“inconsistent value: Device refused one or more commands”).

• Recommended alternatives for Catalyst switches:

  • For access ports: Use spanning_tree_portfast: true (translates to spanning-tree portfast)
  • For trunk ports: Use spanning_tree_portfast_trunk: true (translates to spanning-tree portfast trunk)
  • Both options provide the same portfast functionality and are fully supported on Catalyst platforms

• Portfast and guard mutual exclusivity: The spanning-tree portfast variants (portfast, portfast_disable, portfast_trunk) and guard options (loop, root, none) serve different purposes:

  • Portfast enables immediate forwarding for edge ports connecting to end devices
  • Guard protects against topology loops (loop) or unauthorized root bridges (root)
  • These can be configured together on the same interface for comprehensive protection

• BPDU guard configuration: BPDU guard (bpduguard: true or bpduguard_disable: true) can be configured alongside any portfast variant to protect against unauthorized switches. When global BPDU guard is enabled (spanning-tree portfast bpduguard default), use bpduguard_disable: true to selectively disable it on specific interfaces.

IP Address Reassignment Between Interfaces

IOS-XE enforces IP address uniqueness within the same VRF — no two interfaces can hold the same IP address simultaneously. When swapping IP addresses between two interfaces (for example, moving 10.1.1.1 from GigabitEthernet1 to GigabitEthernet2 and vice versa), terraform apply will fail because Terraform updates both interfaces in parallel without awareness of the cross-resource conflict. The device rejects the new IP assignment with an “inconsistent value: Device refused one or more commands” error because the target IP still exists on the other interface.

To perform an IP swap, apply the change in two steps:

1. Remove the IP addresses from both interfaces (delete the ipv4 block or assign temporary addresses) and run terraform apply.
2. Set the new desired IP addresses and run terraform apply a second time.

Interface Ranges

Interface ranges allow defining multiple interfaces with identical configuration using a from/to range. Range entries are lightweight — they only specify identity fields (type, from, to) and interface_groups. All configuration must be defined in the referenced interface groups.

• Only the last numeric segment of the interface ID varies within a range (e.g., 1/0/1 to 1/0/48)
• Multiple ranges of the same interface type are supported
• Overlapping ranges or ranges that overlap with individual interface entries will produce errors when terraform plan is executed

Example:

iosxe:
  interface_groups:
    - name: ACCESS_100
      configuration:
        switchport:
          mode: access
          access_vlan: 100
        spanning_tree:
          portfast: true

  devices:
    - name: Switch1
      configuration:
        interfaces:
          ranges:
            ethernets:
              - type: GigabitEthernet
                from: "1/0/1"
                to: "1/0/48"
                interface_groups: [ACCESS_100]
              - type: TenGigabitEthernet
                from: "1/1/1"
                to: "1/1/4"
                interface_groups: [UPLINK_TRUNK]

Examples

Basic L2 Access Port with Port Channel and Spanning Tree

Cisco IOS-XE CLI Equivalent:

interface GigabitEthernet1/1
 description Server 1 Interface
 mtu 1600
 speed 1000
 channel-group 10 mode active
 switchport mode access
 switchport access vlan 100
 switchport voice vlan 900
 spanning-tree guard loop
interface GigabitEthernet1/2
 description WAN Interface
 ipv6 address dhcp

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - id: 1/1
              type: GigabitEthernet
              description: Server 1 Interface
              mtu: 1600
              speed: 1000
              port_channel_id: 10
              port_channel_mode: active
              carrier_delay_msec: 250
              hold_queue_in: 50
              hold_queue_out: 50
              switchport:
                mode: access
                access_vlan: 100
                voice_vlan: 900
              spanning_tree:
                guard: loop
            - id: 1/2
              type: GigabitEthernet
              description: WAN Interface
              ipv6:
                enable: true
                address_dhcp: true

Comprehensive L3 Routed Interface with OSPF, BFD, and IPv6

interface GigabitEthernet1/0/2
 description L3 interface
 mtu 1600
 vrf forwarding VRF-PROD
 arp timeout 300
 load-interval 90
 no snmp trap link-status
 no logging event link-status
 ip arp inspection limit rate 40
 ip arp inspection trust
 ip address 192.168.100.1 255.255.255.0
 ip proxy-arp
 ip dhcp relay source-interface Gi1/0/1
 ip helper-address 10.1.1.1
 ip access-group ACL-IN in
 ip access-group ACL-OUT out
 no ip redirects
 no ip unreachables
 ip verify unicast source reachable-via rx allow-self-ping allow-default
 ip flow monitor FLOW1 input
 ip igmp version 2
 ip pim sparse-mode
 ip ospf message-digest-key 1 md5 0 cisco
 ip ospf 1 area 0
 ip ospf cost 10
 ip ospf dead-interval 40
 ip ospf hello-interval 11
 ip ospf network point-to-point
 ip ospf priority 1
 ip ospf ttl-security hops 2
 ipv6 address 2001::1/64 eui-64
 ipv6 address fe80::1 link-local
 ipv6 mtu 1450
 ipv6 nd ra suppress all
 ipv6 pim dr-priority 100
 ipv6 ospf cost 10
 ipv6 ospf network point-to-point
 bfd enable
 bfd local-address 172.16.1.1
 bfd interval 100 min_rx 101 multiplier 3
 no bfd echo
 vrrp 1 ip 192.168.100.254
 vrrp 1 ip 192.168.100.253 secondary
 vrrp 1 priority 110
 vrrp 1 preempt delay minimum 30
 vrrp 1 timers advertise 3
 vrrp 1 authentication text SECRET
 vrrp 1 description VRRP-GROUP-1
 vrrp 1 track 1 decrement 20
 vrrp 1 shutdown

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/2
              description: L3 interface
              vrf_forwarding: "VRF-PROD"
              mtu: 1600
              arp_timeout: 300
              load_interval: 90
              snmp_trap_link_status: false
              logging_event_link_status: false
              ipv4:
                arp_inspection_limit_rate: 40
                arp_inspection_trust: true
                address: 192.168.100.1
                address_mask: 255.255.255.0
                address_dhcp: true
                proxy_arp: true
                dhcp_relay_source_interface_type: GigabitEthernet
                dhcp_relay_source_interface_id: 1/0/1
                helper_addresses:
                  - address: 10.1.1.1
                access_group_in: ACL-IN
                access_group_out: ACL-OUT
                redirects: false
                unreachables: false
                verify_unicast_source_reachable_via: rx
                verify_unicast_source_allow_self_ping: true
                verify_unicast_source_allow_default: true
                flow_monitors:
                  - name: FLOW1
                    direction: input
              ipv6:
                enable: true
                addresses:
                  - prefix: 2001::1/64
                    eui_64: true
                link_local_addresses:
                  - fe80::1
                mtu: 1450
                nd_ra_suppress_all: true
                pim:
                  dr_priority: 100
              bfd:
                enable: true
                local_address: 172.16.1.1
                interval: 100
                interval_multiplier: 3
                interval_min_rx: 101
                echo: false
              ospf:
                cost: 10
                dead_interval: 40
                hello_interval: 11
                mtu_ignore: false
                network_type: point-to-point
                priority: 1
                ttl_security_hops: 2
                process_ids:
                  - id: 1
                    areas:
                      - "0"
                message_digest_keys:
                  - id: 1
                    md5_auth_key: "cisco"
                    md5_auth_type: "0"
              ospfv3:
                cost: 10
                network_type: point-to-point
                bfd: true
                dead_interval: 40
                hello_interval: 10
                mtu_ignore: true
                priority: 100
              igmp:
                version: 2
              pim:
                sparse_mode: true
              vrrp_v2:
                - group_id: 1
                  ip_primary_address: 192.168.100.254
                  ip_secondary_addresses:
                    - 192.168.100.253
                  priority: 110
                  preempt: true
                  preempt_delay_minimum: 30
                  timers_advertise_interval: 3
                  authentication_text: SECRET
                  description: VRRP-GROUP-1
                  shutdown: true
                  tracks:
                    - object_id: 1
                      decrement: 20

Access Port with Portfast, BPDU Guard, and BFD Template

bfd-template single-hop SH-TEMPLATE-2
 interval min-tx 500 min-rx 500 multiplier 3
interface GigabitEthernet1/0/1
 description Access port with portfast
 spanning-tree portfast
 spanning-tree bpduguard
 spanning-tree guard root
 switchport mode access
 bfd template SH-TEMPLATE-2

iosxe:
  devices:
    - name: Device1
      configuration:
        bfd:
          single_hop_templates:
            - name: SH-TEMPLATE-2
                echo: false
                interval_milliseconds_min_tx: 500
                interval_milliseconds_min_rx: 500
                interval_milliseconds_multiplier: 3
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/1
              description: Access port with portfast
              spanning_tree:
                portfast: true
                bpduguard: true
                guard: root
              switchport:
                enable: true
                mode: access
              bfd:
                enable: true
                template: SH-TEMPLATE-2

Trunk Port with Portfast Trunk

interface GigabitEthernet1/0/2
 description Trunk port with portfast
 speed 2500
 spanning-tree portfast trunk
 spanning-tree bpduguard
 spanning-tree link-type shared
 switchport mode trunk
 switchport trunk allowed vlan 10-20,30,32
 switchport trunk native vlan 5

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/2
              description: Trunk port with portfast
              speed: 2500
              speed_nonegotiate: false
              spanning_tree:
                portfast_trunk: true
                bpduguard: true
                link_type: shared
              switchport:
                mode: trunk
                trunk_allowed_vlans:
                  vlans:
                    ids: [30, 32]
                    ranges:
                      - from: 10
                        to: 20
                trunk_native_vlan_id: 5

Access Port with Portfast and Loop Guard

interface GigabitEthernet1/0/3
 description Port with portfast and loop guard
 spanning-tree portfast
 spanning-tree guard loop
 switchport mode access

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/3
              description: Port with portfast and loop guard
              spanning_tree:
                portfast: true
                guard: loop
              switchport:
                enable: true
                mode: access

Access Port with Portfast Explicitly Disabled

interface GigabitEthernet1/0/4
 description Port with portfast disabled
 spanning-tree portfast disable
 spanning-tree guard loop
 switchport mode access

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/4
              description: Port with portfast disabled
              spanning_tree:
                portfast_disable: true
                guard: loop
              switchport:
                enable: true
                mode: access

Access Port with BPDU Guard Explicitly Disabled

interface GigabitEthernet1/0/5
 description Port with bpduguard disabled
 spanning-tree bpduguard disable
 spanning-tree link-type point-to-point
 switchport mode access

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/5
              description: Port with bpduguard disabled
              spanning_tree:
                bpduguard_disable: true
                link_type: point-to-point
              switchport:
                enable: true
                mode: access

Auto QoS Trust DSCP

interface GigabitEthernet1/0/7
 description Auto QoS trust DSCP test interface
 auto qos trust dscp

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/7
              description: Auto QoS trust DSCP test interface
              auto_qos:
                trust_dscp: true

Trunk Switchport Allowed VLANs

Allow All VLANs Explicitly

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/6
              switchport:
                mode: trunk
                trunk_allowed_vlans:
                  all: true

Allow All VLANs Implicitly (Default Behavior)

By default, all VLANs are allowed on a trunk switchport if no VLANs are explicitly allowed, mimicking native Cisco IOS-XE behavior.

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/7
              switchport:
                mode: trunk

Block All VLANs

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/8
              switchport:
                mode: trunk
                trunk_allowed_vlans:
                  none: true

Allow VLAN Range

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/9
              switchport:
                mode: trunk
                trunk_allowed_vlans:
                  vlans:
                    ranges:
                      - from: 100
                        to: 200

Allow All VLANs Except Specific VLANs

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/10
              switchport:
                mode: trunk
                trunk_allowed_vlans:
                  except:
                    ids:
                      - 999

Allow Specific VLANs and Ranges

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/11
              switchport:
                mode: trunk
                trunk_allowed_vlans:
                  vlans:
                    ids:
                      - 100
                      - 200
                    ranges:
                      - from: 300
                        to: 400

Trunk Native VLAN Tagging

Configure trunk interface with native VLAN tagging enabled.

Cisco IOS-XE CLI Equivalent:

interface GigabitEthernet1/0/12
 description Trunk port with native VLAN tagging
 switchport mode trunk
 switchport trunk native vlan 10
 switchport trunk native vlan tag

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/12
              description: Trunk port with native VLAN tagging
              switchport:
                mode: trunk
                trunk_native_vlan_id: 10
                trunk_native_vlan_tag: true

DHCP Relay Information Option VPN-ID

Configure DHCP relay information option vpn-id on interface.

Cisco IOS-XE CLI Equivalent:

interface GigabitEthernet2
 ip dhcp relay information option vpn-id

iosxe:
  devices:
    - name: router
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: '2'
              ipv4:
                dhcp_relay_information_option_vpn_id: true
            - type: GigabitEthernet
              id: '3'
              ipv4:
                dhcp_relay_information_option_vpn_id: true

Network Access Control (802.1X) Configuration

Configure 802.1X authentication parameters on interface including timeout values for rate limiting and server communication.

interface GigabitEthernet1/0/1
 dot1x timeout ratelimit-period 60
 dot1x timeout server-timeout 30
 dot1x pae authenticator
 authentication periodic
 authentication timer reauthenticate server

iosxe:
  devices:
    - name: switch
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/1
              description: NAC Enabled Port
              network_access_control:
                dot1x_timeout_ratelimit_period: 60
                dot1x_timeout_server_timeout: 30
                dot1x_pae: authenticator
                authentication_periodic: true
                authentication_timer_reauthenticate_server: true

CDP TLV Server Location

interface GigabitEthernet1/0/1
 cdp tlv server-location

iosxe:
  devices:
    - name: switch
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/1
              cdp_tlv_server_location: true

QoS Service Policies

interface GigabitEthernet1/0/6
 description Service policy test interface
 service-policy input INBOUND_QOS
 service-policy output OUTBOUND_QOS

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/6
              description: Service policy test interface
              service_policy_input: INBOUND_QOS
              service_policy_output: OUTBOUND_QOS

IS-IS Point-to-Point with Interface Metrics

interface GigabitEthernet2
 ip address 10.1.1.1 255.255.255.252
 ip router isis TEST
 isis network point-to-point
 isis metric 100 level-1
 isis metric 200 level-2

iosxe:
  devices:
    - name: router1
      configuration:
        routing:
          isis_processes:
            - area_tag: TEST
              nets:
                - tag: 49.0001.1920.0000.2001.00
              metric_style_wide: true
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: "2"
              ipv4:
                address: 10.1.1.1
                address_mask: 255.255.255.252
              isis:
                area_tag: TEST
                network_point_to_point: true
                ipv4_metric_levels:
                  - level: level-1
                    value: 100
                  - level: level-2
                    value: 200

Ethernet interfaces provide the fundamental physical and logical connectivity for network devices, supporting various speeds from Fast Ethernet (100 Mbps) to multi-gigabit rates (1G, 2.5G, 5G, 10G, 25G, 40G, 100G) with comprehensive Layer 2 switching and Layer 3 routing capabilities. They offer extensive configuration options including switchport modes (access, trunk), VLAN assignments, spanning tree parameters, quality of service policies, security features, and advanced protocols such as OSPF, BFD, and IPv6. Ethernet interfaces serve as the backbone of modern networks, enabling both access layer connectivity for end devices and high-performance trunk links between network infrastructure components while supporting features like port channels, network access control, and comprehensive monitoring capabilities.

Diagram

Classes

interfaces (iosxe.devices.configuration)

Name	Type	Constraint	Mandatory	Default Value
ethernets	List	[ethernets]	No

ethernets (iosxe.devices.configuration.interfaces)

Name	Type	Constraint	Mandatory	Default Value
type	Choice	GigabitEthernet, FastEthernet, Ethernet, Port-channel, FiveGigabitEthernet, TenGigabitEthernet, TwentyFiveGigE, FortyGigabitEthernet, HundredGigE, TwoHundredGigE, FourHundredGigE	Yes
id	String		Yes
managed	Boolean	true, false	No	true
interface_groups	List	String	No
media_type	Choice	auto-select, rj45, sfp	No
bandwidth	Integer	min: 1, max: 200000000	No
mtu	Integer	min: 64, max: 18000	No
description	String		No
shutdown	Boolean	true, false	No
vrf_forwarding	String		No
ipv4	Class	[ipv4]	No
ipv6	Class	[ipv6]	No
bfd	Class	[bfd]	No
spanning_tree	Class	[spanning_tree]	No
speed	Choice	100, 1000, 2500, 5000, 10000, 25000, 40000, 100000, auto	No
speed_nonegotiate	Boolean	true, false	No
port_channel_id	Integer	min: 1, max: 512	No
port_channel_mode	Choice	active, auto, desirable, on, passive	No
source_templates	List	[source_templates]	No
arp_timeout	Integer	min: 0, max: 2147483	No
negotiation_auto	Boolean	true, false	No
service_policy_input	String		No
service_policy_output	String		No
load_interval	Integer	min: 30, max: 600	No
snmp_trap_link_status	Boolean	true, false	No
logging_event_link_status	Boolean	true, false	No
device_tracking	Boolean	true, false	No
device_tracking_attached_policies	List	String	No
encapsulation_dot1q_vlan_id	Integer	min: 1, max: 4094	No
nbar_protocol_discovery	Boolean	true, false	No
mpls	Class	[mpls]	No
ospf	Class	[ospf]	No
ospfv3	Class	[ospfv3]	No
pim	Class	[pim]	No
igmp	Class	[igmp]	No
switchport	Class	[switchport]	No
network_access_control	Class	[network_access_control]	No
auto_qos	Class	[auto_qos]	No
cdp	Boolean	true, false	No
cdp_tlv_app	Boolean	true, false	No
cdp_tlv_location	Boolean	true, false	No
cdp_tlv_server_location	Boolean	true, false	No

ipv4 (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
address	IP		No
address_mask	IP		No
proxy_arp	Boolean	true, false	No
arp_inspection_trust	Boolean	true, false	No
arp_inspection_limit_rate	Integer	min: 0, max: 4294967295	No
dhcp_snooping_trust	Boolean	true, false	No
dhcp_relay_source_interface_type	Choice	Loopback, Vlan, GigabitEthernet, FiveGigabitEthernet, TenGigabitEthernet, FortyGigabitEthernet, HundredGigabitEthernet, PortChannel	No
dhcp_relay_source_interface_id	Any	String or Integer[min: 0]	No
dhcp_relay_information_option_vpn_id	Boolean	true, false	No
helper_addresses	List	[helper_addresses]	No
access_group_in	String		No
access_group_out	String		No
flow_monitors	List	[flow_monitors]	No
redirects	Boolean	true, false	No
unreachables	Boolean	true, false	No
unnumbered_interface_type	Choice	Loopback, Vlan, GigabitEthernet, FiveGigabitEthernet, TenGigabitEthernet, FortyGigabitEthernet, HundredGigabitEthernet, PortChannel	No
unnumbered_interface_id	Any	String or Integer[min: 0]	No
nat_inside	Boolean	true, false	No
nat_outside	Boolean	true, false	No

ipv6 (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
enable	Boolean	true, false	No
addresses	List	[addresses]	No
link_local_addresses	List	IP	No
address_autoconfig_default	Boolean	true, false	No
address_dhcp	Boolean	true, false	No
mtu	Integer	min: 1280, max: 9976	No
nd_ra_suppress_all	Boolean	true, false	No
flow_monitors	List	[flow_monitors]	No
pim	Class	[pim]	No

bfd (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
template	String		No
enable	Boolean	true, false	No
local_address	String		No
interval	Integer	min: 50, max: 9999	No
interval_min_rx	Integer	min: 50, max: 9999	No
interval_multiplier	Integer	min: 3, max: 50	No
echo	Boolean	true, false	No

spanning_tree (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
portfast	Boolean	true, false	No
portfast_disable	Boolean	true, false	No
bpduguard	Boolean	true, false	No
bpduguard_disable	Boolean	true, false	No
guard	Choice	loop, none, root	No
link_type	Choice	shared, point-to-point	No
portfast_trunk	Boolean	true, false	No
portfast_edge	Boolean	true, false	No

source_templates (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
name	String		Yes
merge	Boolean	true, false	No

mpls (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
ip	Boolean	true, false	No
mtu	Integer		No

ospf (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
cost	Integer	min: 1, max: 65535	No
dead_interval	Integer	min: 1, max: 65535	No
hello_interval	Integer	min: 1, max: 65535	No
mtu_ignore	Boolean	true, false	No
network_type	Choice	broadcast, non-broadcast, point-to-multipoint, point-to-point	No
priority	Integer	min: 0, max: 255	No
ttl_security_hops	Integer	min: 1, max: 254	No
process_ids	List	[process_ids]	No
message_digest_keys	List	[message_digest_keys]	No

ospfv3 (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
network_type	Choice	broadcast, non-broadcast, point-to-multipoint, point-to-point	No
cost	Integer	min: 1, max: 65535	No

pim (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
passive	Boolean	true, false	No
dense_mode	Boolean	true, false	No
sparse_mode	Boolean	true, false	No
sparse_dense_mode	Boolean	true, false	No
bfd	Boolean	true, false	No
border	Boolean	true, false	No
bsr_border	Boolean	true, false	No
dr_priority	Integer	min: 0, max: 4294967294	No

igmp (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
version	Integer	min: 1, max: 3	No

switchport (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
enable	Boolean	true, false	No
mode	Choice	access, dot1q-tunnel, private-vlan-trunk, private-vlan-host, private-vlan-promiscuous, trunk	No
nonegotiate	Boolean	true, false	No
access_vlan	Integer	min: 1, max: 4094	No
trunk_allowed_vlans	Class	[trunk_allowed_vlans]	No
trunk_allowed_vlans_legacy	Class	[trunk_allowed_vlans_legacy]	No
trunk_native_vlan_tag	Boolean	true, false	No
trunk_native_vlan_id	Integer	min: 1, max: 4094	No
host	Boolean	true, false	No

network_access_control (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
authentication_periodic	Boolean	true, false	No
authentication_timer_reauthenticate	Integer	min: 1, max: 1073741823	No
authentication_timer_reauthenticate_server	Boolean	true, false	No
mab	Boolean	true, false	No
mab_eap	Boolean	true, false	No
dot1x_pae	Choice	authenticator, supplicant, both	No
dot1x_timeout_auth_period	Integer	min: 1, max: 65535	No
dot1x_timeout_held_period	Integer	min: 1, max: 65535	No
dot1x_timeout_quiet_period	Integer	min: 1, max: 65535	No
dot1x_timeout_ratelimit_period	Integer	min: 1, max: 65535	No
dot1x_timeout_server_timeout	Integer	min: 1, max: 65535	No
dot1x_timeout_start_period	Integer	min: 1, max: 65535	No
dot1x_timeout_supp_timeout	Integer	min: 1, max: 65535	No
dot1x_timeout_tx_period	Integer	min: 1, max: 65535	No
dot1x_max_req	Integer	min: 1, max: 10	No
dot1x_max_reauth_req	Integer	min: 1, max: 10	No

auto_qos (iosxe.devices.configuration.interfaces.ethernets)

Name	Type	Constraint	Mandatory	Default Value
classify	Boolean	true, false	No
classify_police	Boolean	true, false	No
trust	Boolean	true, false	No
trust_cos	Boolean	true, false	No
trust_dscp	Boolean	true, false	No
video_cts	Boolean	true, false	No
video_ip_camera	Boolean	true, false	No
video_media_player	Boolean	true, false	No
voip	Boolean	true, false	No
voip_cisco_phone	Boolean	true, false	No
voip_cisco_softphone	Boolean	true, false	No
voip_trust	Boolean	true, false	No
trust_device	Choice	cisco-phone, cts, ip-camera, media-player	No

helper_addresses (iosxe.devices.configuration.interfaces.ethernets.ipv4)

Name	Type	Constraint	Mandatory	Default Value
address	IP		Yes
global	Boolean	true, false	No
vrf	String		No

flow_monitors (iosxe.devices.configuration.interfaces.ethernets.ipv4)

Name	Type	Constraint	Mandatory	Default Value
name	String		Yes
direction	Choice	input, output	Yes

addresses (iosxe.devices.configuration.interfaces.ethernets.ipv6)

Name	Type	Constraint	Mandatory	Default Value
prefix	IP		Yes
eui_64	Boolean	true, false	No

pim (iosxe.devices.configuration.interfaces.ethernets.ipv6)

Name	Type	Constraint	Mandatory	Default Value
pim	Boolean	true, false	No
bfd	Boolean	true, false	No
bsr_border	Boolean	true, false	No
dr_priority	Integer	min: 0, max: 4294967295	No

process_ids (iosxe.devices.configuration.interfaces.ethernets.ospf)

Name	Type	Constraint	Mandatory	Default Value
id	Integer	min: 1, max: 65535	No
areas	List	Any[String or Integer[min: 0]]	No

message_digest_keys (iosxe.devices.configuration.interfaces.ethernets.ospf)

Name	Type	Constraint	Mandatory	Default Value
id	Integer	min: 1, max: 255	Yes
md5_auth_key	String		No
md5_auth_type	Choice	0, 7	No

trunk_allowed_vlans (iosxe.devices.configuration.interfaces.ethernets.switchport)

Name	Type	Constraint	Mandatory	Default Value
all	Boolean	true, false	No
none	Boolean	true, false	No
vlans	Class	[vlans]	No
add	Class	[add]	No
except	Class	[except]	No
remove	Class	[remove]	No

trunk_allowed_vlans_legacy (iosxe.devices.configuration.interfaces.ethernets.switchport)

Name	Type	Constraint	Mandatory	Default Value
ids	List	Integer[min: 1, max: 4094]	No
ranges	List	[ranges]	No

vlans (iosxe.devices.configuration.interfaces.ethernets.switchport.trunk_allowed_vlans)

Name	Type	Constraint	Mandatory	Default Value
ids	List	Integer[min: 1, max: 4094]	No
ranges	List	[ranges]	No

add (iosxe.devices.configuration.interfaces.ethernets.switchport.trunk_allowed_vlans)

Name	Type	Constraint	Mandatory	Default Value
ids	List	Integer[min: 1, max: 4094]	No
ranges	List	[ranges]	No

except (iosxe.devices.configuration.interfaces.ethernets.switchport.trunk_allowed_vlans)

Name	Type	Constraint	Mandatory	Default Value
ids	List	Integer[min: 1, max: 4094]	No
ranges	List	[ranges]	No

remove (iosxe.devices.configuration.interfaces.ethernets.switchport.trunk_allowed_vlans)

Name	Type	Constraint	Mandatory	Default Value
ids	List	Integer[min: 1, max: 4094]	No
ranges	List	[ranges]	No

ranges (iosxe.devices.configuration.interfaces.ethernets.switchport.trunk_allowed_vlans_legacy)

Name	Type	Constraint	Mandatory	Default Value
from	Integer	min: 1, max: 4094	Yes
to	Integer	min: 1, max: 4094	Yes

Guidelines and Limitations

Managed vs Unmanaged Interfaces

• managed attribute: Controls whether Terraform continuously manages the interface configuration. When set to false, Terraform will push the initial configuration but will not continuously read it, detect drift, or reconcile changes. This is useful for:

  • Interfaces whose configuration changes dynamically due to authorization policies
  • Interfaces modified by local scripts or automation
  • Interfaces where configuration drift should be allowed and not corrected
  • Default: true (Terraform fully manages the interface and reconciles drift)

• Usage example:

  interfaces:
    ethernets:
      - id: 1/0/1
        type: GigabitEthernet
        description: Dynamic interface
        managed: false  # Terraform pushes initial config but ignores subsequent changes

Spanning Tree Portfast Configuration

• spanning_tree_portfast_edge attribute limitation: The spanning_tree_portfast_edge attribute uses a deprecated YANG model path (spanning-tree/portfast/edge) that does not translate to valid CLI commands on Catalyst switch platforms. While the YANG model accepts this configuration for backward compatibility with routers or older platforms, modern Catalyst switches (including Catalyst 9000 series) do not support the spanning-tree portfast edge CLI command. Attempting to configure this attribute on Catalyst switches will result in device configuration rejection errors (“inconsistent value: Device refused one or more commands”).

• Recommended alternatives for Catalyst switches:

  • For access ports: Use spanning_tree_portfast: true (translates to spanning-tree portfast)
  • For trunk ports: Use spanning_tree_portfast_trunk: true (translates to spanning-tree portfast trunk)
  • Both options provide the same portfast functionality and are fully supported on Catalyst platforms

• Portfast and guard mutual exclusivity: The spanning-tree portfast variants (portfast, portfast_disable, portfast_trunk) and guard options (loop, root, none) serve different purposes:

  • Portfast enables immediate forwarding for edge ports connecting to end devices
  • Guard protects against topology loops (loop) or unauthorized root bridges (root)
  • These can be configured together on the same interface for comprehensive protection

• BPDU guard configuration: BPDU guard (bpduguard: true or bpduguard_disable: true) can be configured alongside any portfast variant to protect against unauthorized switches. When global BPDU guard is enabled (spanning-tree portfast bpduguard default), use bpduguard_disable: true to selectively disable it on specific interfaces.

Examples

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - id: 1/1
              type: GigabitEthernet
              description: Server 1 Interface
              speed: 1000
              port_channel_id: 10
              port_channel_mode: active
              switchport:
                mode: access
                access_vlan: 100
              spanning_tree:
                guard: loop

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/2
              description: L3 interface
              vrf_forwarding: "VRF-PROD"
              speed: 10000
              arp_timeout: 300
              load_interval: 90
              snmp_trap_link_status: false
              logging_event_link_status: false
              ipv4:
                arp_inspection_limit_rate: 40
                arp_inspection_trust: true
                address: 192.168.100.1
                address_mask: 255.255.255.0
                proxy_arp: true
                dhcp_relay_source_interface: Gig1/0/1
                helper_addresses:
                  - address: 10.1.1.1
                access_group_in: ACL-IN
                access_group_out: ACL-OUT
                redirects: false
                unreachables: false
                flow_monitors:
                  - name: FLOW1
                    direction: input
              ipv6:
                enable: true
                addresses:
                  - prefix: 2001::1
                    prefix_length: 64
                    eui64: true
                link_local_addresses:
                  - fe80::1
                mtu: 1450
                nd_ra_suppress_all: true
              bfd:
                enable: true
                local_address: 172.16.1.1
                interval: 100
                interval_multiplier: 3
                interval_min_rx: 101
                echo: false
              ospf:
                cost: 10
                dead_interval: 40
                hello_interval: 11
                mtu_ignore: false
                network_type: point-to-point
                priority: 1
                ttl_security_hops: 2
                process_ids:
                  - id: 1
                    areas:
                      - "0"
                message_digest_keys:
                  - id: 1
                    md5_auth_key: "cisco"
                    md5_auth_type: "0"
              ospfv3:
                cost: 10
                network_type: point-to-point
              igmp:
                version: 2

# Example 1: Standard access port with portfast and bpduguard
iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/1
              description: Access port with portfast
              spanning_tree:
                portfast: true
                bpduguard: true
                guard: root
              switchport:
                enable: true
                mode: access

# Example 2: Trunk port with portfast_trunk
iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/2
              description: Trunk port with portfast
              speed: 2500
              speed_nonegotiate: false
              spanning_tree:
                portfast_trunk: true
                bpduguard: true
                link_type: shared
              switchport:
                mode: trunk
                trunk_allowed_vlans:
                  vlans:
                    ids: [30, 32]
                    ranges:
                      - from: 10
                        to: 20
                trunk_native_vlan_id: 5

# Example 3: Port with portfast and loop guard
iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/3
              description: Port with portfast and loop guard
              spanning_tree:
                portfast: true
                guard: loop
              switchport:
                enable: true
                mode: access

# Example 4: Explicitly disable portfast (useful when global portfast is enabled)
iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/4
              description: Port with portfast disabled
              spanning_tree:
                portfast_disable: true
                guard: loop
              switchport:
                enable: true
                mode: access

# Example 5: Port with bpduguard_disable (useful when global bpduguard is enabled)
iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/5
              description: Port with bpduguard disabled
              spanning_tree:
                bpduguard_disable: true
                link_type: point-to-point
              switchport:
                enable: true
                mode: access

Trunk Switchport Configuration

You can configure a trunk switchport to explicitly allow all VLANs as shown below.

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/6
              switchport:
                mode: trunk
                trunk_allowed_vlans:
                  all: true

Additionally, by default, all VLANs are allowed on a trunk switchport if no VLANs are explicitly allowed, mimicking native Cisco IOS-XE behavior. An example is shown below.

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/7
              switchport:
                mode: trunk

You can configure a trunk switchport to explicitly allow no VLANs as shown below.

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/8
              switchport:
                mode: trunk
                trunk_allowed_vlans:
                  none: true

You can configure a trunk switchport to allow a range of VLANs as shown below.

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/9
              switchport:
                mode: trunk
                trunk_allowed_vlans:
                  vlans:
                    ranges:
                      - from: 100
                        to: 200

You can configure a trunk switchport to allow all VLANs except for specific VLANs as shown below.

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/10
              switchport:
                mode: trunk
                trunk_allowed_vlans:
                  except:
                    ids:
                      - 999

You can configure a trunk switchport to allow specific VLANs alongside a range of VLANs as shown below.

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: 1/0/11
              switchport:
                mode: trunk
                trunk_allowed_vlans:
                  vlans:
                    ids:
                      - 100
                      - 200
                    ranges:
                      - from: 300
                        to: 400

Example configuring DHCP Relay information option vpn-id.

Cisco IOS-XE CLI Equivalent:

interface GigabitEthernet2
 ip dhcp relay information option vpn-id

NAC YAML Configuration:

iosxe:
  devices:
    - name: router
      configuration:
        interfaces:
          ethernets:
            - type: GigabitEthernet
              id: '2'
              ipv4:
                dhcp_relay_information_option_vpn_id: true
            - type: GigabitEthernet
              id: '3'
              ipv4:
                dhcp_relay_information_option_vpn_id: true