[TRM] Implement VRF VNID/EVPN-Instance Support in Terraform Provider

[camschaecisco]

VRF VNID and EVPN-Instance Support

This PR adds support for Virtual Network Identifier (VNID) and EVPN-Instance configuration within VRF definitions for the terraform-provider-iosxe.

This enhancement introduces VNID configuration capabilities to the existing iosxe_vrf resource, enabling VXLAN EVPN Layer 3 services. This feature provides network operators with the ability to configure Virtual Network Identifiers for VRFs, which are essential for VXLAN fabric deployments and EVPN-based multi-tenancy. VNID allows automatic route-target generation and EVPN-instance configuration enables Layer 3 VNI assignment for overlay network virtualization.

CLI Commands Supported

VNID Configuration

vrf definition <name>
  vnid <1-2147483647>
  vnid <1-2147483647> evpn-instance vni <4096-16777215>
  vnid <1-2147483647> evpn-instance vni <4096-16777215> core-vlan <1-4094>

These commands enable VXLAN EVPN Layer 3 services with the following capabilities:

• vnid: Configure Virtual Network Identifier for automatic route-target generation
• evpn-instance vni: Associate VRF with EVPN instance and specify Layer 3 VNI
• core-vlan: Associate a core VLAN with the VNI (platform-dependent)

Benefits

• Enables VXLAN EVPN Layer 3 VPN services for multi-tenant data center fabrics
• Provides automatic route-target generation based on VNID configuration
• Supports Layer 3 overlay network virtualization with EVPN control plane
• Facilitates multi-tenancy in campus and data center VXLAN deployments
• Enables seamless integration with VXLAN Network Virtualization Edge (NVE) interfaces
• Simplifies VRF route-target configuration through automatic VNID-based generation
• Supports both router (Cat8k) and switch (Cat9k) platforms with platform-specific CLI
• Compatible with SD-Access fabric and VXLAN BGP EVPN architectures
• Enables consistent tenant segmentation across distributed VXLAN fabrics
• Provides foundation for multi-site DCI with EVPN Type-5 routing

Platform Compatibility

These features have been validated against:

• Cisco Catalyst 8000V routers running IOS-XE 17.12 and 17.15
• Cisco Catalyst 9000 switches running IOS-XE 17.15

Version Requirements

IOS-XE 17.12 and later:

• ✅ vnid_value (Number: 1-2147483647) - Virtual Network Identifier
• ✅ evpn_instance_vni_vni_num (Number: 4096-16777215) - Layer 3 VNI number
• ✅ evpn_instance_vni_vni_num_core_vlan (Number: 1-4094, Optional) - Core VLAN (platform-dependent)

Platform-Specific Behavior:

Router Platforms (Catalyst 8000):

• ✅ VNID only: vnid 11500
• ✅ Explicit VNI without core-vlan: vnid 11510 evpn-instance vni 21510
• ❌ core-vlan parameter not supported by router CLI

Switch Platforms (Catalyst 9000):

• ✅ VNID only: vnid 10900
• ✅ Explicit VNI with core-vlan: vnid 10910 evpn-instance vni 20910 core-vlan 910
• ⚠️ core-vlan required when using evpn-instance on switches

Technical Implementation

• Enhanced iosxe_vrf resource with the following new attributes:
  • vnid (List of Objects, Optional, max 1) - VNID configuration block
    • vnid_value (Number, Required) - VNID value for route-target auto generation (range: 1-2147483647)
    • evpn_instance_vni_vni_num (List of Objects, Optional, max 1) - EVPN instance VNI configuration
      • vni_num (Number, Required) - Layer 3 VNI number (range: 4096-16777215)
      • core_vlan (Number, Optional) - Core VLAN number (range: 1-4094)
• Updated corresponding iosxe_vrf data source for VNID configuration retrieval
• Correctly mapped to YANG model: Cisco-IOS-XE-native:native/vrf/definition with Cisco-IOS-XE-ip:vnid
• Implemented proper YANG model integration with nested EVPN-instance structure
• Ensured idempotent behavior for all VNID attributes
• Made core-vlan optional to support both router and switch platforms
• Added comprehensive examples for both platform types
• Updated CHANGELOG and documentation with new VNID attributes
• Generated terraform import examples for VRF resources with VNID

Testing

Multi-Platform Validation

Catalyst 8000V (Router, IOS-XE 17.15): ✅

vrf definition VRF_VNID_ONLY_1715
 vnid 11500
 !
 address-family ipv4
 exit-address-family

vrf definition VRF_EXPLICIT_NO_VLAN_1715
 vnid 11510 evpn-instance vni 21510
 !
 address-family ipv4
 exit-address-family
 !
 address-family ipv6
 exit-address-family

Catalyst 8000V (Router, IOS-XE 17.12): ✅

vrf definition VRF_VNID_ONLY_1712
 vnid 11200
 !
 address-family ipv4
 exit-address-family

vrf definition VRF_EXPLICIT_NO_VLAN_1712
 vnid 11210 evpn-instance vni 21210
 !
 address-family ipv4
 exit-address-family
 !
 address-family ipv6
 exit-address-family

Catalyst 9000 (Switch, IOS-XE): ✅

vrf definition VRF_VNID_ONLY_CAT9K
 vnid 10900
 !
 address-family ipv4
 exit-address-family

vrf definition VRF_EXPLICIT_WITH_VLAN_CAT9K
 vnid 10910 evpn-instance vni 20910 core-vlan 910
 !
 address-family ipv4
 exit-address-family
 !
 address-family ipv6
 exit-address-family

Terraform Testing

• ✅ terraform plan - Correctly identifies VNID configuration changes
• ✅ terraform apply - Successfully applies VNID and EVPN-instance configuration
• ✅ terraform destroy - Cleanly removes VNID configuration
• ✅ State management - Properly tracks VNID state across apply/refresh/destroy lifecycle
• ✅ Import support - Terraform import command works with VRFs containing VNID

RESTCONF API Validation

• ✅ HTTP 204/201 responses for all VNID configuration operations
• ✅ Proper YANG namespace handling (Cisco-IOS-XE-ip:vnid)
• ✅ Correct JSON payload structure for VNID with nested EVPN-instance
• ✅ Idempotent updates with no configuration drift
• ✅ Platform-specific behavior correctly handled (core-vlan optional)

YANG Model Validation

• ✅ Verified VNID feature availability in Cisco-IOS-XE-ip.yang
• ✅ Confirmed nested structure: vnid → evpn-instance → vni → vni-num/core-vlan
• ✅ Validated presence container handling for evpn-instance
• ✅ Verified platform-specific CLI behavior (routers vs switches)
• ✅ Tested cross-platform compatibility (Cat8k routers and Cat9k switches)

Example Usage

Router Configuration (Cat8k) - VNID with Explicit VNI:

resource iosxe_vrf example_router {
  device              = Cat8k-Router
  name                = TENANT-A
  address_family_ipv4 = true
  address_family_ipv6 = true
  
  vnid = [{
    vnid_value = 10001
    evpn_instance_vni_vni_num = [{
      vni_num = 20001
    }]
  }]
}

Resulting CLI Configuration:

vrf definition TENANT-A
 vnid 10001 evpn-instance vni 20001
 !
 address-family ipv4
 exit-address-family
 !
 address-family ipv6
 exit-address-family

Switch Configuration (Cat9k) - VNID with Explicit VNI and Core-VLAN:

resource iosxe_vrf example_switch {
  device              = Cat9k-Switch
  name                = TENANT-B
  address_family_ipv4 = true
  address_family_ipv6 = true
  
  vnid = [{
    vnid_value = 10002
    evpn_instance_vni_vni_num = [{
      vni_num   = 20002
      core_vlan = 100
    }]
  }]
}

Resulting CLI Configuration:

vrf definition TENANT-B
 vnid 10002 evpn-instance vni 20002 core-vlan 100
 !
 address-family ipv4
 exit-address-family
 !
 address-family ipv6
 exit-address-family

VNID Only Configuration (Both Platforms):

resource iosxe_vrf example_vnid_only {
  device              = Device
  name                = TENANT-C
  address_family_ipv4 = true
  
  vnid = [{
    vnid_value = 10003
  }]
}

Resulting CLI Configuration:

vrf definition TENANT-C
 vnid 10003
 !
 address-family ipv4
 exit-address-family