[TRM] Implement MPLS Label Mode Support in Terraform Provider

[camschaecisco]

MPLS Label Mode Support

This PR adds support for MPLS Label Mode configuration to the terraform-provider-iosxe.

This enhancement introduces the iosxe_mpls resource and data source with the ability to configure MPLS label allocation modes. This feature provides network operators with granular control over MPLS label distribution behavior across VRFs and address families, enabling optimized label allocation strategies for service provider MPLS/VPN deployments. MPLS label modes control how labels are allocated and distributed for VPN routes, allowing operators to balance between label efficiency (per-VRF mode using fewer labels) and traffic engineering flexibility (per-prefix mode allowing per-destination control).

CLI Commands Supported

MPLS Configuration
mpls label protocol {ldp | tdp}
mpls label mode all-vrfs protocol all-afs {per-vrf | per-prefix | per-ce | vrf-conn-aggr}
mpls label mode all-vrfs protocol bgp-vpnv4 {per-vrf | per-prefix | per-ce | vrf-conn-aggr}
mpls label mode all-vrfs protocol bgp-vpnv6 {per-vrf | per-prefix | per-ce | vrf-conn-aggr}

These commands enable MPLS label allocation control with the following capabilities:

• label protocol: Configure LDP (Label Distribution Protocol) or TDP (Tag Distribution Protocol)
• all-afs: Apply label mode to all address families (IPv4/IPv6 unicast and multicast)
• bgp-vpnv4: Apply label mode specifically to BGP VPNv4 address family
• bgp-vpnv6: Apply label mode specifically to BGP VPNv6 address family
• per-vrf: Allocate one label per VRF (most efficient)
• per-prefix: Allocate unique label per destination prefix (most granular)
• per-ce: Allocate label per customer edge router
• vrf-conn-aggr: Aggregate labels for connected VRF routes

Benefits

• Enables granular control over MPLS label allocation strategies for MPLS/VPN deployments
• Reduces label consumption with per-VRF mode (single label per VRF regardless of prefix count)
• Provides per-destination traffic engineering capabilities with per-prefix mode
• Supports service provider VPN scenarios with flexible label distribution options
• Allows independent label mode configuration for IPv4 and IPv6 VPN address families
• Enables label optimization for BGP VPNv4 and VPNv6 route advertisements
• Facilitates carrier supporting carrier (CSC) and inter-AS VPN deployments
• Reduces forwarding complexity for PE routers with per-VRF aggregation
• Provides scalability for large-scale MPLS VPN networks
• Supports both LDP and TDP label distribution protocols
• Compatible with existing MPLS infrastructure and service provider architectures
• Enables label space optimization without impacting VPN functionality
• Provides flexibility to balance between label efficiency and traffic engineering granularity

Platform Compatibility

These features have been validated against:

• Cisco Catalyst 8000V router running IOS-XE 17.15
• Cisco Catalyst 9000 switch running IOS-XE 17.15

Version Requirements

IOS-XE 17.15.1 and later:

• ✅ label_protocol (String: "ldp" or "tdp") - MPLS label distribution protocol
• ✅ label_mode_all_vrfs_protocol_all_afs_per_vrf (Boolean) - Per-VRF label mode for all address families
• ✅ label_mode_all_vrfs_protocol_all_afs_per_prefix (Boolean) - Per-prefix label mode for all address families
• ✅ label_mode_all_vrfs_protocol_all_afs_per_ce (Boolean) - Per-CE label mode for all address families
• ✅ label_mode_all_vrfs_protocol_all_afs_vrf_conn_aggr (Boolean) - VRF connected aggregate label mode for all address families
• ✅ label_mode_all_vrfs_protocol_bgp_vpnv4_per_vrf (Boolean) - Per-VRF label mode for BGP VPNv4
• ✅ label_mode_all_vrfs_protocol_bgp_vpnv4_per_prefix (Boolean) - Per-prefix label mode for BGP VPNv4
• ✅ label_mode_all_vrfs_protocol_bgp_vpnv4_per_ce (Boolean) - Per-CE label mode for BGP VPNv4
• ✅ label_mode_all_vrfs_protocol_bgp_vpnv4_vrf_conn_aggr (Boolean) - VRF connected aggregate label mode for BGP VPNv4
• ✅ label_mode_all_vrfs_protocol_bgp_vpnv6_per_vrf (Boolean) - Per-VRF label mode for BGP VPNv6
• ✅ label_mode_all_vrfs_protocol_bgp_vpnv6_per_prefix (Boolean) - Per-prefix label mode for BGP VPNv6
• ✅ label_mode_all_vrfs_protocol_bgp_vpnv6_per_ce (Boolean) - Per-CE label mode for BGP VPNv6
• ✅ label_mode_all_vrfs_protocol_bgp_vpnv6_vrf_conn_aggr (Boolean) - VRF connected aggregate label mode for BGP VPNv6

Platform Notes:

• Both Cat8k routers and Cat9k switches support all MPLS label mode features
• The implementation uses the Cisco-IOS-XE-mpls YANG model augmented to /native/mpls
• YANG model contains implicit case nodes in choice constructs requiring duplicated element names in yang_name attribute

Technical Implementation

• Added iosxe_mpls resource with the following attributes:
  • label_protocol (String, Optional) - Label distribution protocol ("ldp" or "tdp")
  • label_mode_all_vrfs_protocol_all_afs_per_vrf (Boolean, Optional) - Per-VRF mode for all AFs
  • label_mode_all_vrfs_protocol_all_afs_per_prefix (Boolean, Optional) - Per-prefix mode for all AFs
  • label_mode_all_vrfs_protocol_all_afs_per_ce (Boolean, Optional) - Per-CE mode for all AFs
  • label_mode_all_vrfs_protocol_all_afs_vrf_conn_aggr (Boolean, Optional) - VRF connected aggregate for all AFs
  • label_mode_all_vrfs_protocol_bgp_vpnv4_per_vrf (Boolean, Optional) - Per-VRF mode for BGP VPNv4
  • label_mode_all_vrfs_protocol_bgp_vpnv4_per_prefix (Boolean, Optional) - Per-prefix mode for BGP VPNv4
  • label_mode_all_vrfs_protocol_bgp_vpnv4_per_ce (Boolean, Optional) - Per-CE mode for BGP VPNv4
  • label_mode_all_vrfs_protocol_bgp_vpnv4_vrf_conn_aggr (Boolean, Optional) - VRF connected aggregate for BGP VPNv4
  • label_mode_all_vrfs_protocol_bgp_vpnv6_per_vrf (Boolean, Optional) - Per-VRF mode for BGP VPNv6
  • label_mode_all_vrfs_protocol_bgp_vpnv6_per_prefix (Boolean, Optional) - Per-prefix mode for BGP VPNv6
  • label_mode_all_vrfs_protocol_bgp_vpnv6_per_ce (Boolean, Optional) - Per-CE mode for BGP VPNv6
  • label_mode_all_vrfs_protocol_bgp_vpnv6_vrf_conn_aggr (Boolean, Optional) - VRF connected aggregate for BGP VPNv6
• Added corresponding iosxe_mpls data source for configuration retrieval
• Correctly mapped RESTCONF path: /restconf/data/Cisco-IOS-XE-native:native/mpls
• Implemented proper YANG model integration with Cisco-IOS-XE-native and Cisco-IOS-XE-mpls modules
• Handled implicit case nodes in YANG choice construct (label mode choices require element name duplication)
• Ensured idempotent behavior for all attributes
• Updated CHANGELOG and documentation with new resource
• Generated comprehensive examples for various MPLS label mode configurations

Testing

Go Acceptance Tests
=== RUN TestAccIosxeMPLS
--- PASS: TestAccIosxeMPLS (2.85s)
PASS
ok github.com/CiscoDevNet/terraform-provider-iosxe/internal/provider 2.856s

Multi-Platform Validation

• Catalyst 8000V (Router, IOS-XE 17.15.1): ✅ MPLS with LDP protocol and per-VRF label mode validated successfully (2.85s)
• Catalyst 9000 (Switch, IOS-XE 17.15.1): ✅ MPLS with LDP protocol and per-prefix label mode validated successfully (2.40s)

Network as Code (NaC) Framework Integration Testing

• ✅ Data model schema validation with yamale
• ✅ Terraform module integration (terraform-iosxe-nac-iosxe/iosxe_mpls.tf)
• ✅ Robot Framework RESTCONF validation tests
• ✅ Multi-device deployment testing (router + switch simultaneously)
• ✅ Result: 2 tests, 2 passed, 0 failed, 0 skipped

Terraform Testing

• ✅ terraform plan - Correctly identifies MPLS configuration changes
• ✅ terraform apply - Successfully applies MPLS label mode configuration
• ✅ terraform destroy - Cleanly removes MPLS configuration
• ✅ State management - Properly tracks resource state across apply/refresh/destroy lifecycle
• ✅ Import support - Terraform import command included in examples
• ✅ Multi-device deployment - Tested with both router and switch simultaneously

RESTCONF API Validation

• ✅ HTTP 204/201 responses for all configuration operations
• ✅ Proper YANG namespace handling (Cisco-IOS-XE-mpls:mpls)
• ✅ Correct JSON payload structure for label protocol and mode configuration
• ✅ Idempotent updates with no configuration drift
• ✅ Standard PATCH operation works (no put_only required)
• ✅ JSONPath validation for nested YANG structures

YANG Model Validation

• ✅ Verified feature availability in IOS-XE 17.12.1 and 17.15.1 YANG models (Cisco-IOS-XE-mpls.yang)
• ✅ Validated MPLS configuration via config-mpls-grouping augmented to /native/mpls
• ✅ Confirmed implicit case nodes in choice construct require yang_name duplication
• ✅ Verified label mode choice structure: all-afs, bgp-vpnv4, bgp-vpnv6 cases
• ✅ Validated nested container structure: label/mode/all-vrfs/protocol/{choice}

Example Usage

Example 1: Basic Per-VRF Label Mode (Recommended for label efficiency)

resource "iosxe_mpls" "example" {
  device                                          = "router1"
  label_protocol                                  = "ldp"
  label_mode_all_vrfs_protocol_all_afs_per_vrf    = true
}

Resulting CLI Configuration:
mpls label protocol ldp
mpls label mode all-vrfs protocol all-afs per-vrf

Example 2: Per-Prefix Label Mode for Traffic Engineering
resource "iosxe_mpls" "example" {
  device                                          = "router1"
  label_protocol                                  = "ldp"
  label_mode_all_vrfs_protocol_all_afs_per_prefix = true
}

Resulting CLI Configuration:
mpls label protocol ldp
mpls label mode all-vrfs protocol all-afs per-prefix

Example 3: BGP VPNv4-Specific Label Mode
resource "iosxe_mpls" "example" {
  device                                           = "router1"
  label_protocol                                   = "ldp"
  label_mode_all_vrfs_protocol_bgp_vpnv4_per_vrf   = true
}

Resulting CLI Configuration:
mpls label protocol ldp
mpls label mode all-vrfs protocol bgp-vpnv4 per-vrf

Example 4: Comprehensive Configuration with Multiple Address Families
resource "iosxe_mpls" "example" {
  device                                           = "router1"
  label_protocol                                   = "ldp"
  label_mode_all_vrfs_protocol_all_afs_per_vrf     = true
  label_mode_all_vrfs_protocol_bgp_vpnv4_per_vrf   = true
  label_mode_all_vrfs_protocol_bgp_vpnv6_per_vrf   = true
}

Resulting CLI Configuration:
mpls label protocol ldp
mpls label mode all-vrfs protocol all-afs per-vrf
mpls label mode all-vrfs protocol bgp-vpnv4 per-vrf
mpls label mode all-vrfs protocol bgp-vpnv6 per-vrf

Import Example:
terraform import iosxe_mpls.example "Cisco-IOS-XE-native:native/mpls"