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.
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 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_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.
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:
Remove the IP addresses from both interfaces (delete the ipv4 block or assign temporary addresses) and run terraform apply.
Set the new desired IP addresses and run terraform apply a second time.
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
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_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.
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.
