From 4c7634da592e53fb1a4cb673991052c12ef2ba31 Mon Sep 17 00:00:00 2001 From: Damien Arnodo Date: Fri, 26 Dec 2025 13:39:58 +0000 Subject: [PATCH] docs: add YANG paths reference documentation Comprehensive documentation of validated gNMI YANG paths for: - Interfaces, Loopbacks, VLANs (OpenConfig) - BGP with EVPN AFI (OpenConfig) - VXLAN VNI mappings (Arista experimental) - MLAG and EVPN config (Arista experimental) Includes examples, limitations, and key learnings. Closes partial requirement for #3 --- docs/yang-paths.md | 296 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 296 insertions(+) create mode 100644 docs/yang-paths.md diff --git a/docs/yang-paths.md b/docs/yang-paths.md new file mode 100644 index 0000000..2cbc297 --- /dev/null +++ b/docs/yang-paths.md @@ -0,0 +1,296 @@ +# YANG Paths Reference for Arista EOS 4.35.0F + +This document provides the complete reference of validated gNMI YANG paths for managing Arista EVPN-VXLAN fabrics. + +> **Tested with**: Arista cEOS 4.35.0F via gNMI (port 6030) + +--- + +## Quick Reference + +| Feature | Model Type | Config | State | Subscribe ON_CHANGE | +|---------|------------|--------|-------|---------------------| +| Interfaces | OpenConfig | ✅ | ✅ | ✅ | +| Loopbacks | OpenConfig | ✅ | ✅ | ✅ | +| VLANs | OpenConfig | ✅ | ✅ | ✅ | +| BGP | OpenConfig | ✅ | ✅ | ✅ | +| VXLAN | Arista Exp | ✅ | ✅ | ✅ | +| MLAG | Arista Exp | ✅ | ❌ | N/A | +| EVPN | Arista Exp | ✅ | ❌ | N/A | + +--- + +## Interfaces + +**Model**: `openconfig-interfaces` + +| Operation | Path | +|-----------|------| +| All interfaces | `/interfaces/interface` | +| Specific interface | `/interfaces/interface[name=Ethernet1]` | +| Interface config | `/interfaces/interface[name=Ethernet1]/config` | +| Interface state | `/interfaces/interface[name=Ethernet1]/state` | +| Oper status only | `/interfaces/interface[name=Ethernet1]/state/oper-status` | +| Admin status only | `/interfaces/interface[name=Ethernet1]/state/admin-status` | +| Interface counters | `/interfaces/interface[name=Ethernet1]/state/counters` | + +### Example: Get Interface State + +```bash +gnmic -a 172.16.0.50:6030 -u admin -p admin --insecure \ + get --path "/interfaces/interface[name=Ethernet1]/state" +``` + +### Example: Subscribe to Interface Changes + +```bash +gnmic -a 172.16.0.50:6030 -u admin -p admin --insecure \ + subscribe --path "/interfaces/interface[name=Ethernet1]/state" \ + --mode stream --stream-mode on-change +``` + +--- + +## Loopbacks + +**Model**: `openconfig-interfaces` + +| Operation | Path | +|-----------|------| +| Loopback0 | `/interfaces/interface[name=Loopback0]` | +| Loopback1 (VTEP) | `/interfaces/interface[name=Loopback1]` | +| Loopback config | `/interfaces/interface[name=Loopback0]/config` | + +--- + +## VLANs + +**Model**: `openconfig-network-instance`, `openconfig-vlan` + +| Operation | Path | +|-----------|------| +| All VLANs | `/network-instances/network-instance[name=default]/vlans/vlan` | +| Specific VLAN | `/network-instances/network-instance[name=default]/vlans/vlan[vlan-id=40]` | +| VLAN config | `/network-instances/network-instance[name=default]/vlans/vlan[vlan-id=40]/config` | +| SVI interface | `/interfaces/interface[name=Vlan40]` | + +--- + +## BGP + +**Model**: `openconfig-bgp`, `openconfig-network-instance` + +### Base Path + +``` +/network-instances/network-instance[name=default]/protocols/protocol[identifier=BGP][name=BGP]/bgp +``` + +### Paths + +| Operation | Path (relative to base) | +|-----------|-------------------------| +| BGP global config | `/global/config` | +| BGP global state | `/global/state` | +| Router ID | `/global/config/router-id` | +| AS number | `/global/config/as` | +| All neighbors | `/neighbors/neighbor` | +| Specific neighbor | `/neighbors/neighbor[neighbor-address=10.0.1.0]` | +| Neighbor state | `/neighbors/neighbor[neighbor-address=10.0.1.0]/state` | +| Neighbor session state | `/neighbors/neighbor[neighbor-address=10.0.1.0]/state/session-state` | +| IPv4 Unicast AFI | `/neighbors/neighbor[neighbor-address=10.0.1.0]/afi-safis/afi-safi[afi-safi-name=IPV4_UNICAST]` | +| EVPN AFI | `/neighbors/neighbor[neighbor-address=10.0.1.0]/afi-safis/afi-safi[afi-safi-name=L2VPN_EVPN]` | + +### Example: Get All BGP Neighbors State + +```bash +gnmic -a 172.16.0.50:6030 -u admin -p admin --insecure \ + get --path "/network-instances/network-instance[name=default]/protocols/protocol[identifier=BGP][name=BGP]/bgp/neighbors/neighbor/state" +``` + +### Example: Subscribe to BGP Session Changes + +```bash +gnmic -a 172.16.0.50:6030 -u admin -p admin --insecure \ + subscribe \ + --path "/network-instances/network-instance[name=default]/protocols/protocol[identifier=BGP][name=BGP]/bgp/neighbors/neighbor/state/session-state" \ + --mode stream --stream-mode on-change +``` + +--- + +## VXLAN + +**Model**: `arista-exp-eos-vxlan` (augments `openconfig-interfaces`) + +| Operation | Path | +|-----------|------| +| VXLAN interface | `/interfaces/interface[name=Vxlan1]` | +| VXLAN augment | `/interfaces/interface[name=Vxlan1]/arista-vxlan` | +| VXLAN config | `/interfaces/interface[name=Vxlan1]/arista-vxlan/config` | +| VXLAN state | `/interfaces/interface[name=Vxlan1]/arista-vxlan/state` | +| Source interface | `/interfaces/interface[name=Vxlan1]/arista-vxlan/config/src-ip-intf` | +| UDP port | `/interfaces/interface[name=Vxlan1]/arista-vxlan/config/udp-port` | +| All VLAN-to-VNI mappings | `/interfaces/interface[name=Vxlan1]/arista-vxlan/vlan-to-vnis` | +| Specific VNI mapping | `/interfaces/interface[name=Vxlan1]/arista-vxlan/vlan-to-vnis/vlan-to-vni[vlan=40]` | +| VRF-to-VNI (L3 VNI) | `/interfaces/interface[name=Vxlan1]/arista-vxlan/vrf-to-vnis` | + +### Example: Get VXLAN VNI Mappings + +```bash +gnmic -a 172.16.0.50:6030 -u admin -p admin --insecure \ + get --path "/interfaces/interface[name=Vxlan1]/arista-vxlan/vlan-to-vnis" +``` + +### Example: Subscribe to VNI Changes + +```bash +gnmic -a 172.16.0.50:6030 -u admin -p admin --insecure \ + subscribe \ + --path "/interfaces/interface[name=Vxlan1]/arista-vxlan/vlan-to-vnis" \ + --mode stream --stream-mode on-change +``` + +--- + +## MLAG + +**Model**: `arista-exp-eos-mlag` + +> ⚠️ **Limitation**: Only configuration is exposed via gNMI. Operational state (peer status, role, negotiation) requires eAPI. + +| Operation | Path | +|-----------|------| +| Full MLAG | `/arista/eos/mlag` | +| MLAG config | `/arista/eos/mlag/config` | + +### Config Fields + +| Field | Description | +|-------|-------------| +| `domain-id` | MLAG domain identifier | +| `local-intf` | Local VLAN interface (e.g., Vlan4090) | +| `peer-address` | MLAG peer IP address | +| `peer-link-intf` | Peer-link port-channel | +| `dual-primary-action` | Action on dual-primary detection | +| `dual-primary-detection-delay` | Detection delay in seconds | +| `heartbeat-peer-address` | Heartbeat peer IP and VRF | + +### Example: Get MLAG Config + +```bash +gnmic -a 172.16.0.50:6030 -u admin -p admin --insecure \ + get --path "/arista/eos/mlag/config" +``` + +### For MLAG State: Use eAPI + +```bash +# MLAG state is NOT available via gNMI +# Use eAPI instead: +curl -X POST https://switch/command-api \ + -d '{"jsonrpc":"2.0","method":"runCmds","params":{"cmds":["show mlag"]},"id":1}' +``` + +--- + +## EVPN + +**Model**: `arista-exp-eos-evpn` + +> ⚠️ **Limitation**: Only configuration is exposed via gNMI. Learned routes and MACs require eAPI. + +| Operation | Path | +|-----------|------| +| All EVPN | `/arista/eos/evpn` | +| EVPN instances | `/arista/eos/evpn/evpn-instances` | +| Specific instance | `/arista/eos/evpn/evpn-instances/evpn-instance[name=40]` | + +### Config Fields + +| Field | Path | +|-------|------| +| Name | `.../evpn-instance[name=X]/config/name` | +| Route Distinguisher | `.../evpn-instance[name=X]/config/route-distinguisher` | +| Redistribute | `.../evpn-instance[name=X]/config/redistribute` | +| Route Target Import | `.../evpn-instance[name=X]/route-target/config/import` | +| Route Target Export | `.../evpn-instance[name=X]/route-target/config/export` | +| VLANs | `.../evpn-instance[name=X]/vlans/vlan` | + +### Example: Get EVPN Config + +```bash +gnmic -a 172.16.0.50:6030 -u admin -p admin --insecure \ + get --path "/arista/eos/evpn" +``` + +--- + +## Port-Channel / LAG + +**Model**: `openconfig-interfaces`, `openconfig-if-aggregate` + +| Operation | Path | +|-----------|------| +| Port-Channel interface | `/interfaces/interface[name=Port-Channel999]` | +| LAG config | `/interfaces/interface[name=Port-Channel999]/aggregation/config` | +| LAG state | `/interfaces/interface[name=Port-Channel999]/aggregation/state` | +| Member interfaces | `/interfaces/interface[name=Ethernet1]/ethernet/config/aggregate-id` | + +--- + +## Key Learnings + +### 1. Path Prefix for Subscriptions + +Use native paths **without** module prefix for ON_CHANGE subscriptions: + +```bash +# ✅ Works +--path "/interfaces/interface[name=Ethernet1]/state" + +# ❌ Does NOT work for ON_CHANGE +--path "/openconfig-interfaces:interfaces/interface[name=Ethernet1]/state" +``` + +### 2. Query Types + +```bash +# Config only +gnmic get --path "/path" --type config + +# State only +gnmic get --path "/path" --type state + +# Both (default) +gnmic get --path "/path" +``` + +### 3. Depth Control + +```bash +# Limit depth for exploration +gnmic get --path "/" --depth 1 +gnmic get --path "/interfaces" --depth 2 +``` + +### 4. Discovering Paths + +```bash +# Start broad +gnmic get --path "/" --depth 1 + +# Explore branches +gnmic get --path "/arista/eos" --depth 1 + +# Use prompt mode with YANG models +gnmic --file EOS-4.35.0F/openconfig/public/release/models prompt +``` + +--- + +## References + +- [Arista YANG Models](https://github.com/aristanetworks/yang/tree/master/EOS-4.35.0F) +- [OpenConfig Models](https://github.com/openconfig/public) +- [gNMIc Documentation](https://gnmic.openconfig.net/)