VLAN

VLAN interfaces, also known as Switched Virtual Interfaces (SVIs), provide Layer 3 gateway functionality for VLANs by creating routable interfaces associated with specific VLAN IDs, enabling inter-VLAN routing, network segmentation, and centralized gateway services for broadcast domains. They support comprehensive Layer 3 features including IPv4 and IPv6 addressing, routing protocol participation (OSPF, BGP), DHCP relay services, access control lists, and advanced capabilities such as BFD for fast convergence and HSRP/VRRP for high availability. VLAN interfaces are essential for network infrastructure design, serving as default gateways for VLANs, enabling communication between different network segments, and providing centralized routing and policy enforcement points in switched network environments.

Diagram

Diagram

Classes

iosxe

Name	Type	Constraint	Mandatory	Default Value
devices	List	devices	No
device_groups	List	device_groups	No
global	Class	global	No

devices (iosxe)

Name	Type	Constraint	Mandatory	Default Value
configuration	Class	configuration	No

device_groups (iosxe)

Name	Type	Constraint	Mandatory	Default Value
configuration	Class	configuration	No

global (iosxe)

Name	Type	Constraint	Mandatory	Default Value
configuration	Class	configuration	No

configuration (iosxe.devices)

Name	Type	Constraint	Mandatory	Default Value
interfaces	Class	interfaces	No

interfaces (iosxe.devices.configuration)

Name	Type	Constraint	Mandatory	Default Value
vlans	List	vlans	No

vlans (iosxe.devices.configuration.interfaces)

Name	Type	Constraint	Mandatory	Default Value
id	Integer	min: 1, max: 4094	Yes
interface_groups	List	String	No
interface_group_policy	Choice	merge, replace	No
description	String		No
shutdown	Boolean	true, false	No
ip_mtu	Integer	min: 68, max: 18000	No
autostate	Boolean	true, false	No
vrf_forwarding	String		No
ipv4	Class	ipv4	No
ipv6	Class	ipv6	No
bfd	Class	bfd	No
load_interval	Integer	min: 30, max: 600	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
mac_address	MAC		No
vrrp_v2	List	vrrp_v2	No
zone_member_security	String		No

vlans (iosxe.devices.configuration.interfaces)

Name	Type	Constraint	Mandatory	Default Value
id	Integer	min: 1, max: 4094	Yes
interface_groups	List	String	No
description	String		No
shutdown	Boolean	true, false	No
autostate	Boolean	true, false	No
vrf_forwarding	String		No
ipv4	Class	ipv4	No
ipv6	Class	ipv6	No
bfd	Class	bfd	No
load_interval	Integer	min: 30, max: 600	No
mpls	Class	mpls	No
ospf	Class	ospf	No
ospfv3	Class	ospfv3	No
pim	Class	pim	No
igmp	Class	igmp	No
mac_address	MAC		No

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

Name	Type	Constraint	Mandatory	Default Value
address	IP		No
address_mask	IP		No
proxy_arp	Boolean	true, false	No
local_proxy_arp	Boolean	true, false	No
arp_inspection_trust	Boolean	true, false	No
arp_inspection_limit_rate	Integer	min: 0, max: 4294967295	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
redirects	Boolean	true, false	No
unreachables	Boolean	true, false	No
nat_inside	Boolean	true, false	No
nat_outside	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
address_dhcp	Boolean	true, false	No

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

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_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
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

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

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.vlans)

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

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

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

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

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

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

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

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

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.vlans)

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

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

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

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

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.vlans)

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.vlans)

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

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

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.vlans.ipv4)

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

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

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

flow_monitors (iosxe.devices.configuration.interfaces.vlans.ipv6)

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

pim (iosxe.devices.configuration.interfaces.vlans.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.vlans.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.vlans.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.vlans.isis)

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

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

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

Guidelines and Limitations

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 Vlan100 to Vlan200 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.

Examples

Sample Configuration

interface loopback 200
 ip address 10.100.100.1 255.255.255.0
interface vlan 100
 description Production VLAN 100 Gateway
 no shutdown
 autostate
 ip address 10.100.1.1 255.255.255.0
 no ip proxy-arp
 ip local-proxy-arp
 ip helper-address 10.1.1.10
 ip verify unicast source reachable-via rx allow-self-ping allow-default
interface vlan 110
 description Production VLAN 110 Gateway
 no shutdown
 ip unnumbered loopback 200

Example YAML Code

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          loopbacks:
            - id: 200
              ipv4:
                address: 10.100.100.1
                address_mask: 255.255.255.0
          vlans:
            - id: 100
              description: Production VLAN 100 Gateway
              shutdown: false
              autostate: true
              ipv4:
                address: 10.100.1.1
                address_mask: 255.255.255.0
                proxy_arp: false
                local_proxy_arp: true
                helper_addresses:
                  - address: 10.1.1.10
            - id: 110
              description: Production VLAN 110 Gateway
              ipv4:
                unnumbered_interface_type: Loopback
                unnumbered_interface_id: 200
              load_interval: 90

Full example:

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          vlans:
            - id: 10
              description: VLAN 10
              interface_groups:
                - dot1x
              shutdown: false
              ip_mtu: 1400
              mac_address: 0000.dead.beef
              ipv4:
                address: 172.16.10.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
              ipv6:
                enable: true
                addresses:
                  - prefix: 2001:db8:10::1/64
                link_local_addresses:
                  - fe80::11
                address_autoconfig_default: false
                address_dhcp: false
                mtu: 1450
                nd_ra_suppress_all: true
                pim:
                  dr_priority: 100
              bfd:
                enable: true
                local_address: 1.2.3.4
                interval: 100
                interval_multiplier: 3
                interval_min_rx: 120
                echo: false
              mpls:
                ip: true
                mtu: 1450
              ospf:
                cost: 50
                dead_interval: 3
                hello_interval: 1
                mtu_ignore: true
                network_type: broadcast
                priority: 1
                ttl_security_hops: 2
                process_ids:
                  - id: 1
                    areas:
                      - "0.0.0.1"
              ospfv3:
                network_type: broadcast
                cost: 50
                bfd: true
                dead_interval: 40
                hello_interval: 10
                mtu_ignore: true
                priority: 100
              pim:
                passive: true
                dense_mode: false
                sparse_mode: false
                sparse_dense_mode: false
                bfd: true
                border: true
                bsr_border: true
                dr_priority: 100
              igmp:
                version: 2
              vrrp_v2:
                - group_id: 1
                  ip_primary_address: 172.16.10.254
                  ip_secondary_addresses:
                    - 172.16.10.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

Example configuring VRRPv2 on an SVI:

Cisco IOS-XE CLI Equivalent:

interface Vlan10
 vrrp 1 ip 172.16.10.254
 vrrp 1 ip 172.16.10.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

Example configuring DHCP Relay information option vpn-id.

Cisco IOS-XE CLI Equivalent:

interface Vlan2000
 ip dhcp relay information option vpn-id

NAC YAML Configuration:

iosxe:
  devices:
    - name: router
      url: https://10.81.239.58
      configuration:
        interfaces:
          vlans:
            - id: 2000
              ipv4:
                dhcp_relay_information_option_vpn_id: true

NAT Inside VLAN Interface

Configure a VLAN interface as a NAT inside interface. This is commonly used when the SVI serves as the default gateway for an internal VLAN whose traffic should be translated by NAT.

Note: nat_inside and nat_outside are mutually exclusive on a single interface (only one can be configured at a time).

Cisco IOS-XE CLI Equivalent:

interface Vlan100
 description Internal VLAN - NAT Inside
 ip address 10.100.1.1 255.255.255.0
 ip nat inside

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          vlans:
            - id: 100
              description: Internal VLAN - NAT Inside
              shutdown: false
              ipv4:
                address: 10.100.1.1
                address_mask: 255.255.255.0
                nat_inside: true

NAT Outside VLAN Interface

Configure a VLAN interface as a NAT outside interface. This is used when the SVI faces an external or public-facing network segment.

Cisco IOS-XE CLI Equivalent:

interface Vlan200
 description External VLAN - NAT Outside
 ip address 203.0.113.1 255.255.255.0
 ip nat outside

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          vlans:
            - id: 200
              description: External VLAN - NAT Outside
              shutdown: false
              ipv4:
                address: 203.0.113.1
                address_mask: 255.255.255.0
                nat_outside: true

Examples

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          vlans:
            - id: 100
              description: Production VLAN 100 Gateway
              shutdown: false
              autostate: true
              ipv4:
                address: 10.100.1.1
                address_mask: 255.255.255.0
                proxy_arp: false
                helper_addresses:
                  - address: 10.1.1.10

Full example:

iosxe:
  devices:
    - name: Device1
      configuration:
        interfaces:
          vlans:
            - id: 10
              description: VLAN 10
              interface_groups:
                - dot1x
              shutdown: false
              mac_address: 0000.dead.beef
              ipv4:
                address: 172.16.10.1
                address_mask: 255.255.255.0
                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
              ipv6:
                enable: true
                addresses:
                  - prefix: 2001:db8:10::1/64
                link_local_addresses:
                  - fe80::11
                address_autoconfig_default: false
                address_dhcp: false
                mtu: 1450
                nd_ra_suppress_all: true
              bfd:
                enable: true
                local_address: 1.2.3.4
                interval: 100
                interval_multiplier: 3
                interval_min_rx: 120
                echo: false
              mpls:
                ip: true
                mtu: 1450
              ospf:
                cost: 50
                dead_interval: 3
                hello_interval: 1
                mtu_ignore: true
                network_type: broadcast
                priority: 1
                ttl_security_hops: 2
                process_ids:
                  - id: 1
                    areas:
                      - "0.0.0.1"
              ospfv3:
                network_type: broadcast
                cost: 50
              pim:
                passive: true
                dense_mode: false
                sparse_mode: false
                sparse_dense_mode: false
                bfd: true
                border: true
                bsr_border: true
                dr_priority: 100
              igmp:
                version: 2

Example configuring DHCP Relay information option vpn-id.

Cisco IOS-XE CLI Equivalent:

interface Vlan2000
 ip dhcp relay information option vpn-id

NAC YAML Configuration:

iosxe:
  devices:
    - name: router
      url: https://10.81.239.58
      configuration:
        interfaces:
          vlans:
            - id: 2000
              ipv4:
                dhcp_relay_information_option_vpn_id: true