NETCONF Protocol Support

[hayibrah]

📋 Overview

This MR adds NETCONF protocol support to the Terraform IOS-XR provider, enabling it to support both gNMI and NETCONF protocols for device communication. The architecture has been refactored to support multiple protocols through a clean, extensible design.

🎯 Key Features

Multi-Protocol Architecture

• ✅ Support for both gNMI and NETCONF protocols
• ✅ Clean separation of concerns with protocol-specific clients
• ✅ Unified interface for seamless protocol switching
• ✅ Backward compatible with existing gNMI configurations

NETCONF Client Capabilities

• Protocol: NETCONF 1.0/1.1 via Scrapli/Scrapligo
• Workflow: Proper candidate datastore workflow (Lock → Edit-Config → Commit → Unlock)
• Data Format: XML-based configuration with automatic JSON↔XML conversion
• Connection Management: Session reuse with configurable timeouts
• Error Handling: Retry logic with exponential backoff
• Thread Safety: Mutex-based locking for concurrent operations

🏗️ Architecture

Client Interface Design

type Client interface {
    AddTarget(ctx, device, host, username, password, ...)
    Set(ctx, device, operations...)
    Get(ctx, device, path)
    GetProtocol()
    Close(ctx)
}

Protocol Selection

• Factory Pattern: NewClient(protocol, reuseConnection, maxRetries)
• Protocol Types: ProtocolGNMI and ProtocolNETCONF
• Smart Routing: Automatic routing to correct protocol implementation

Request Flow

Set Operation:

User → Client.Set() → Protocol Router
                         ├─→ NETCONF: JSON→XML → Lock → EditConfig → Commit → Unlock
                         └─→ gNMI: Direct Set with JSON-IETF encoding

Get Operation:

User → Client.Get() → Protocol Router
                        ├─→ NETCONF: GetConfig → XML→JSON conversion
                        └─→ gNMI: Direct Get with JSON-IETF encoding

🔧 Configuration Examples

Provider Configuration

gNMI (existing - backward compatible):

provider "iosxr" {
  username = "admin"
  password = "password"
  host     = "10.1.1.1:57400"
  # protocol defaults to "gnmi"
}

NETCONF (new capability):

provider "iosxr" {
  username = "admin"
  password = "password"
  host     = "10.1.1.1"
  protocol = "netconf"
  port     = 830  # optional, defaults to 830 for NETCONF
}

Multi-Device with Mixed Protocols:

provider "iosxr" {
  username = "admin"
  password = "password"
  
  devices = [
    {
      name     = "router1"
      host     = "10.1.1.1"
      protocol = "gnmi"
      port     = 57400
    },
    {
      name     = "router2"
      host     = "10.1.1.2"
      protocol = "netconf"
      port     = 830
    }
  ]
}

Environment Variables

# Supported environment variables
export IOSXR_PROTOCOL=netconf         # or gnmi
export IOSXR_USERNAME=admin
export IOSXR_PASSWORD=password
export IOSXR_HOST=10.1.1.1
export IOSXR_PORT=830                 # optional
export IOSXR_REUSE_CONNECTION=true    # optional
export IOSXR_MAX_RETRIES=3            # optional

✅ Benefits

• Protocol Flexibility: Users can choose between gNMI and NETCONF based on infrastructure requirements
• Backward Compatible: Existing gNMI configurations work without changes
• Clean Architecture: Easy to extend with new protocols in the future
• Robust Error Handling: Comprehensive retry logic and error propagation
• Production Ready: Includes timeout controls, session reuse, and thread-safe operations
• Automatic Conversion: Seamless XML↔JSON conversion for cross-protocol compatibility

📚 Documentation

• Architecture Guide: NETCONF_GNMI_ARCHITECTURE.md - Comprehensive documentation of the multi-protocol architecture

Quick Start

provider "iosxr" {
  protocol = "netconf"  # Add this line
  username = "admin"
  password = "password"
  host     = "10.1.1.1"
}

🔍 Breaking Changes

None - This is a backward-compatible addition. Existing users are not affected.

📝 Known Issues

• For NETCONF clients using the Scrapli library, the payload isn't sorted automatically—the key element (list identifier) must appear first in the payload. Otherwise, the device might reject the configuration in certain cases.