e355cce4c8
Add comprehensive documentation for the fabric-orch CLI tool covering: - Installation and quick start instructions - Environment variables for gNMI authentication - All discover subcommands (capabilities, get, set, subscribe, paths) - YANG path syntax reference and common paths table - Output formats and error handling guidance
627 lines
20 KiB
Markdown
627 lines
20 KiB
Markdown
# Fabric Orchestrator CLI User Guide
|
|
|
|
This guide covers the `fabric-orch` command-line interface for exploring YANG paths and managing Arista EVPN-VXLAN fabrics via gNMI.
|
|
|
|
## Table of Contents
|
|
|
|
- [Installation](#installation)
|
|
- [Quick Start](#quick-start)
|
|
- [Environment Variables](#environment-variables)
|
|
- [Commands Overview](#commands-overview)
|
|
- [discover capabilities](#discover-capabilities)
|
|
- [discover get](#discover-get)
|
|
- [discover set](#discover-set)
|
|
- [discover subscribe](#discover-subscribe)
|
|
- [discover paths](#discover-paths)
|
|
- [Output Formats](#output-formats)
|
|
- [Error Handling](#error-handling)
|
|
- [Best Practices](#best-practices)
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
Ensure you have Python 3.12+ and `uv` installed, then:
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://gitea.arnodo.fr/Damien/fabric-orchestrator.git
|
|
cd fabric-orchestrator
|
|
|
|
# Install dependencies
|
|
uv sync
|
|
|
|
# Verify installation
|
|
uv run fabric-orch --version
|
|
```
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Set environment variables (optional but recommended)
|
|
export GNMI_TARGET="172.16.0.50:6030"
|
|
export GNMI_USERNAME="admin"
|
|
export GNMI_PASSWORD="admin"
|
|
|
|
# List device capabilities
|
|
uv run fabric-orch discover capabilities
|
|
|
|
# Get interface state
|
|
uv run fabric-orch discover get --path "/interfaces/interface[name=Ethernet1]/state"
|
|
|
|
# Show common YANG paths reference
|
|
uv run fabric-orch discover paths
|
|
```
|
|
|
|
---
|
|
|
|
## Environment Variables
|
|
|
|
The CLI supports these environment variables to avoid passing credentials repeatedly:
|
|
|
|
| Variable | Description | Default |
|
|
| --------------- | ----------------------------------- | ---------- |
|
|
| `GNMI_TARGET` | Target device in `host:port` format | (required) |
|
|
| `GNMI_USERNAME` | Username for gNMI authentication | `admin` |
|
|
| `GNMI_PASSWORD` | Password for gNMI authentication | `admin` |
|
|
|
|
**Example:**
|
|
```bash
|
|
export GNMI_TARGET="leaf1:6030"
|
|
export GNMI_USERNAME="admin"
|
|
export GNMI_PASSWORD="admin"
|
|
|
|
# Now you can omit --target, --username, --password
|
|
uv run fabric-orch discover capabilities
|
|
```
|
|
|
|
---
|
|
|
|
## Commands Overview
|
|
|
|
```
|
|
fabric-orch
|
|
└── discover # YANG path discovery tools
|
|
├── capabilities # List device capabilities
|
|
├── get # Get config/state data
|
|
├── set # Set configuration
|
|
├── subscribe # Subscribe to updates
|
|
└── paths # Show common paths reference
|
|
```
|
|
|
|
---
|
|
|
|
## discover capabilities
|
|
|
|
List device capabilities and supported YANG models.
|
|
|
|
### Usage
|
|
|
|
```bash
|
|
fabric-orch discover capabilities [OPTIONS]
|
|
```
|
|
|
|
### Options
|
|
|
|
| Option | Short | Description |
|
|
| -------------------------- | ----- | -------------------------------------- |
|
|
| `--target` | `-t` | Target device (host:port) |
|
|
| `--username` | `-u` | Username for authentication |
|
|
| `--password` | `-p` | Password for authentication |
|
|
| `--insecure/--no-insecure` | | Skip TLS verification (default: True) |
|
|
| `--output` | `-o` | Output format: pretty, json, file:path |
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# Basic usage with all options
|
|
uv run fabric-orch discover capabilities \
|
|
--target 172.16.0.50:6030 \
|
|
--username admin \
|
|
--password admin \
|
|
--insecure
|
|
|
|
# Using environment variables
|
|
export GNMI_TARGET="172.16.0.50:6030"
|
|
uv run fabric-orch discover capabilities
|
|
|
|
# Output as JSON
|
|
uv run fabric-orch discover capabilities --output json
|
|
|
|
# Save to file
|
|
uv run fabric-orch discover capabilities --output file:capabilities.json
|
|
```
|
|
|
|
### Sample Output
|
|
|
|
```
|
|
Device Capabilities - 172.16.0.50:6030
|
|
|
|
gNMI Version: 0.8.0
|
|
Supported Encodings: json_ietf, json, proto
|
|
|
|
Supported Models (156):
|
|
|
|
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
|
|
┃ Model Name ┃ Organization ┃ Version ┃
|
|
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
|
|
│ arista-exp-eos-evpn │ Arista Networks │ 2023-01-01 │
|
|
│ arista-exp-eos-mlag │ Arista Networks │ 2023-01-01 │
|
|
│ arista-exp-eos-vxlan │ Arista Networks │ 2023-01-01 │
|
|
│ openconfig-interfaces │ OpenConfig │ 2.4.3 │
|
|
│ openconfig-network-instance │ OpenConfig │ 1.1.0 │
|
|
│ ... │ ... │ ... │
|
|
└───────────────────────────────────┴─────────────────┴────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## discover get
|
|
|
|
Get configuration or state data at a YANG path.
|
|
|
|
### Usage
|
|
|
|
```bash
|
|
fabric-orch discover get [OPTIONS]
|
|
```
|
|
|
|
### Options
|
|
|
|
| Option | Short | Description |
|
|
| -------------------------- | ----- | -------------------------------------------- |
|
|
| `--target` | `-t` | Target device (host:port) |
|
|
| `--username` | `-u` | Username for authentication |
|
|
| `--password` | `-p` | Password for authentication |
|
|
| `--insecure/--no-insecure` | | Skip TLS verification |
|
|
| `--output` | `-o` | Output format: pretty, json, file:path |
|
|
| `--path` | `-P` | YANG path to get data from **(required)** |
|
|
| `--type` | `-T` | Data type: config, state, all (default: all) |
|
|
| `--depth` | `-d` | Maximum depth (not implemented yet) |
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# Get all data at a path
|
|
uv run fabric-orch discover get \
|
|
--target 172.16.0.50:6030 \
|
|
--path "/interfaces/interface[name=Ethernet1]"
|
|
|
|
# Get config only
|
|
uv run fabric-orch discover get \
|
|
--target 172.16.0.50:6030 \
|
|
--path "/interfaces/interface[name=Ethernet1]" \
|
|
--type config
|
|
|
|
# Get state only
|
|
uv run fabric-orch discover get \
|
|
--target 172.16.0.50:6030 \
|
|
--path "/interfaces/interface[name=Ethernet1]/state" \
|
|
--type state
|
|
|
|
# Get BGP neighbor state
|
|
uv run fabric-orch discover get \
|
|
--target 172.16.0.50:6030 \
|
|
--path "/network-instances/network-instance[name=default]/protocols/protocol[identifier=BGP][name=BGP]/bgp/neighbors/neighbor/state"
|
|
|
|
# Get VXLAN VNI mappings
|
|
uv run fabric-orch discover get \
|
|
--target 172.16.0.50:6030 \
|
|
--path "/interfaces/interface[name=Vxlan1]/arista-vxlan/vlan-to-vnis"
|
|
|
|
# Save output to file
|
|
uv run fabric-orch discover get \
|
|
--target 172.16.0.50:6030 \
|
|
--path "/interfaces/interface" \
|
|
--output file:interfaces.json
|
|
|
|
# Machine-readable JSON output
|
|
uv run fabric-orch discover get \
|
|
--target 172.16.0.50:6030 \
|
|
--path "/system/config" \
|
|
--output json | jq '.notification[0].update[0].val'
|
|
```
|
|
|
|
### Path Syntax
|
|
|
|
YANG paths use a specific syntax:
|
|
|
|
- **Basic path**: `/interfaces/interface`
|
|
- **With key**: `/interfaces/interface[name=Ethernet1]`
|
|
- **Multiple keys**: `/protocols/protocol[identifier=BGP][name=BGP]`
|
|
- **Nested path**: `/interfaces/interface[name=Ethernet1]/state/oper-status`
|
|
|
|
### Common Paths
|
|
|
|
| Category | Path | Description |
|
|
| ---------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------- |
|
|
| Interfaces | `/interfaces/interface[name=Ethernet1]/state` | Interface state |
|
|
| BGP | `/network-instances/network-instance[name=default]/protocols/protocol[identifier=BGP][name=BGP]/bgp/neighbors/neighbor/state` | BGP neighbors |
|
|
| VXLAN | `/interfaces/interface[name=Vxlan1]/arista-vxlan/vlan-to-vnis` | VNI mappings |
|
|
| MLAG | `/arista/eos/mlag/config` | MLAG config |
|
|
| System | `/system/config/hostname` | Hostname |
|
|
|
|
---
|
|
|
|
## discover set
|
|
|
|
Set configuration at a YANG path.
|
|
|
|
> ⚠️ **Warning**: This command modifies device configuration. Use with caution!
|
|
|
|
### Usage
|
|
|
|
```bash
|
|
fabric-orch discover set [OPTIONS]
|
|
```
|
|
|
|
### Options
|
|
|
|
| Option | Short | Description |
|
|
| -------------------------- | ----- | ---------------------------------------------------- |
|
|
| `--target` | `-t` | Target device (host:port) |
|
|
| `--username` | `-u` | Username for authentication |
|
|
| `--password` | `-p` | Password for authentication |
|
|
| `--insecure/--no-insecure` | | Skip TLS verification |
|
|
| `--output` | `-o` | Output format: pretty, json, file:path |
|
|
| `--path` | `-P` | YANG path to set **(required)** |
|
|
| `--value` | `-v` | Value to set (JSON or string) **(required)** |
|
|
| `--operation` | `-O` | Operation: update, replace, delete (default: update) |
|
|
| `--dry-run/--no-dry-run` | | Dry-run mode (default: True) |
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# Dry-run (default) - shows what would be set
|
|
uv run fabric-orch discover set \
|
|
--target 172.16.0.50:6030 \
|
|
--path "/interfaces/interface[name=Ethernet1]/config/description" \
|
|
--value "Uplink to Spine1"
|
|
|
|
# Actually apply the change
|
|
uv run fabric-orch discover set \
|
|
--target 172.16.0.50:6030 \
|
|
--path "/interfaces/interface[name=Ethernet1]/config/description" \
|
|
--value "Uplink to Spine1" \
|
|
--no-dry-run
|
|
|
|
# Set JSON value
|
|
uv run fabric-orch discover set \
|
|
--target 172.16.0.50:6030 \
|
|
--path "/interfaces/interface[name=Ethernet1]/config" \
|
|
--value '{"description": "Uplink", "enabled": true}' \
|
|
--no-dry-run
|
|
|
|
# Replace operation (overwrites existing config)
|
|
uv run fabric-orch discover set \
|
|
--target 172.16.0.50:6030 \
|
|
--path "/interfaces/interface[name=Ethernet1]/config" \
|
|
--value '{"description": "New config"}' \
|
|
--operation replace \
|
|
--no-dry-run
|
|
|
|
# Delete configuration
|
|
uv run fabric-orch discover set \
|
|
--target 172.16.0.50:6030 \
|
|
--path "/interfaces/interface[name=Ethernet1]/config/description" \
|
|
--value "" \
|
|
--operation delete \
|
|
--no-dry-run
|
|
```
|
|
|
|
### Operations
|
|
|
|
| Operation | Description |
|
|
| --------- | ------------------------------------------- |
|
|
| `update` | Merge with existing configuration (default) |
|
|
| `replace` | Replace existing configuration at path |
|
|
| `delete` | Delete configuration at path |
|
|
|
|
### Dry-Run Mode
|
|
|
|
By default, the `set` command runs in **dry-run mode**, which shows what would be changed without applying it. This is a safety feature.
|
|
|
|
```bash
|
|
# Dry-run output
|
|
⚠ DRY-RUN MODE - No changes will be applied
|
|
|
|
SET (dry-run) /interfaces/interface[name=Ethernet1]/config/description
|
|
|
|
Operation: update
|
|
Value: Uplink to Spine1
|
|
|
|
Use --no-dry-run to apply this change
|
|
```
|
|
|
|
---
|
|
|
|
## discover subscribe
|
|
|
|
Subscribe to YANG path updates in real-time.
|
|
|
|
### Usage
|
|
|
|
```bash
|
|
fabric-orch discover subscribe [OPTIONS]
|
|
```
|
|
|
|
### Options
|
|
|
|
| Option | Short | Description |
|
|
| -------------------------- | ----- | ------------------------------------------------------------ |
|
|
| `--target` | `-t` | Target device (host:port) |
|
|
| `--username` | `-u` | Username for authentication |
|
|
| `--password` | `-p` | Password for authentication |
|
|
| `--insecure/--no-insecure` | | Skip TLS verification |
|
|
| `--output` | `-o` | Output format: pretty, json, file:path |
|
|
| `--path` | `-P` | YANG path(s) to subscribe to (can repeat) **(required)** |
|
|
| `--mode` | `-m` | Mode: on-change, sample, target-defined (default: on-change) |
|
|
| `--interval` | `-i` | Sample interval in seconds (for sample mode) |
|
|
| `--count` | `-c` | Number of updates before exiting |
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# Subscribe to interface operational status changes
|
|
uv run fabric-orch discover subscribe \
|
|
--target 172.16.0.50:6030 \
|
|
--path "/interfaces/interface/state/oper-status" \
|
|
--mode on-change
|
|
|
|
# Sample interface counters every 10 seconds
|
|
uv run fabric-orch discover subscribe \
|
|
--target 172.16.0.50:6030 \
|
|
--path "/interfaces/interface[name=Ethernet1]/state/counters" \
|
|
--mode sample \
|
|
--interval 10
|
|
|
|
# Subscribe to multiple paths
|
|
uv run fabric-orch discover subscribe \
|
|
--target 172.16.0.50:6030 \
|
|
--path "/interfaces/interface/state/oper-status" \
|
|
--path "/network-instances/network-instance[name=default]/protocols/protocol[identifier=BGP][name=BGP]/bgp/neighbors/neighbor/state/session-state"
|
|
|
|
# Get only 5 updates then exit
|
|
uv run fabric-orch discover subscribe \
|
|
--target 172.16.0.50:6030 \
|
|
--path "/interfaces/interface/state/counters" \
|
|
--mode sample \
|
|
--interval 5 \
|
|
--count 5
|
|
|
|
# Output as JSON (useful for piping)
|
|
uv run fabric-orch discover subscribe \
|
|
--target 172.16.0.50:6030 \
|
|
--path "/interfaces/interface/state/oper-status" \
|
|
--output json
|
|
```
|
|
|
|
### Subscription Modes
|
|
|
|
| Mode | Description |
|
|
| ---------------- | ------------------------------------------------- |
|
|
| `on-change` | Receive updates only when values change (default) |
|
|
| `sample` | Receive periodic updates at specified interval |
|
|
| `target-defined` | Let the device decide the update strategy |
|
|
|
|
### Important Note for Arista EOS
|
|
|
|
For **ON_CHANGE** subscriptions on Arista EOS, use native paths **without** module prefixes:
|
|
|
|
```bash
|
|
# ✅ Correct - native path
|
|
--path "/interfaces/interface[name=Ethernet1]/state"
|
|
|
|
# ❌ Incorrect - with module prefix (may fail)
|
|
--path "/openconfig-interfaces:interfaces/interface[name=Ethernet1]/state"
|
|
```
|
|
|
|
### Stopping Subscriptions
|
|
|
|
Press `Ctrl+C` to stop a subscription gracefully.
|
|
|
|
---
|
|
|
|
## discover paths
|
|
|
|
Display a reference table of commonly used YANG paths for Arista EOS.
|
|
|
|
### Usage
|
|
|
|
```bash
|
|
fabric-orch discover paths
|
|
```
|
|
|
|
This command doesn't require a target connection - it displays a static reference.
|
|
|
|
### Example Output
|
|
|
|
```
|
|
Common YANG Paths for Arista EOS
|
|
|
|
┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
|
|
┃ Category ┃ Path ┃ Notes ┃
|
|
┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
|
|
│ Interfaces │ /interfaces/interface[name=Ethernet1]/state │ Full interface state │
|
|
│ Interfaces │ /interfaces/interface[name=Ethernet1]/state/oper-status │ Operational status │
|
|
│ Interfaces │ /interfaces/interface[name=Ethernet1]/state/counters │ Interface counters │
|
|
│ Loopbacks │ /interfaces/interface[name=Loopback0] │ Loopback interface │
|
|
│ VLANs │ /network-instances/network-instance[name=default]/vlans/vlan │ All VLANs │
|
|
│ BGP │ .../bgp/neighbors/neighbor/state │ All BGP neighbors │
|
|
│ VXLAN │ /interfaces/interface[name=Vxlan1]/arista-vxlan/vlan-to-vnis │ VLAN-to-VNI mappings │
|
|
│ VXLAN │ /interfaces/interface[name=Vxlan1]/arista-vxlan/config │ VXLAN config │
|
|
│ MLAG │ /arista/eos/mlag/config │ MLAG config (config only) │
|
|
│ EVPN │ /arista/eos/evpn │ EVPN config (config only) │
|
|
│ System │ /system/config/hostname │ System hostname │
|
|
└────────────┴──────────────────────────────────────────────────────────────────┴───────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Output Formats
|
|
|
|
All discovery commands support three output formats via the `--output` / `-o` option:
|
|
|
|
### Pretty (default)
|
|
|
|
Rich formatted output with syntax highlighting and tables.
|
|
|
|
```bash
|
|
uv run fabric-orch discover get --path "/system/config" --output pretty
|
|
```
|
|
|
|
### JSON
|
|
|
|
Machine-readable JSON output, suitable for piping to `jq` or other tools.
|
|
|
|
```bash
|
|
uv run fabric-orch discover get --path "/system/config" --output json | jq '.'
|
|
```
|
|
|
|
### File
|
|
|
|
Save output directly to a file.
|
|
|
|
```bash
|
|
uv run fabric-orch discover get --path "/interfaces/interface" --output file:interfaces.json
|
|
```
|
|
|
|
---
|
|
|
|
## Error Handling
|
|
|
|
The CLI provides helpful error messages with hints:
|
|
|
|
### Connection Errors
|
|
|
|
```
|
|
✗ Connection Error: Failed to connect to 172.16.0.50:6030
|
|
|
|
Hints:
|
|
• Check if the target is reachable
|
|
• Verify gNMI is enabled on the device
|
|
• Check credentials
|
|
• Try --insecure flag for self-signed certs
|
|
```
|
|
|
|
### Path Errors
|
|
|
|
```
|
|
✗ Path Error: Path not found or invalid: /invalid/path
|
|
|
|
Hints:
|
|
• Use 'discover capabilities' to see supported models
|
|
• Check path syntax (e.g., /interfaces/interface[name=Ethernet1])
|
|
• Try a parent path first
|
|
```
|
|
|
|
---
|
|
|
|
## Best Practices
|
|
|
|
### 1. Use Environment Variables
|
|
|
|
Set credentials once to avoid repetition:
|
|
|
|
```bash
|
|
export GNMI_TARGET="172.16.0.50:6030"
|
|
export GNMI_USERNAME="admin"
|
|
export GNMI_PASSWORD="admin"
|
|
```
|
|
|
|
### 2. Start with Capabilities
|
|
|
|
Before exploring paths, check what models the device supports:
|
|
|
|
```bash
|
|
uv run fabric-orch discover capabilities
|
|
```
|
|
|
|
### 3. Explore Incrementally
|
|
|
|
Start with broad paths and narrow down:
|
|
|
|
```bash
|
|
# Start broad
|
|
uv run fabric-orch discover get --path "/interfaces"
|
|
|
|
# Then narrow down
|
|
uv run fabric-orch discover get --path "/interfaces/interface[name=Ethernet1]"
|
|
|
|
# Then specific leaves
|
|
uv run fabric-orch discover get --path "/interfaces/interface[name=Ethernet1]/state/oper-status"
|
|
```
|
|
|
|
### 4. Use Dry-Run for Set Operations
|
|
|
|
Always test with dry-run first:
|
|
|
|
```bash
|
|
# Test first
|
|
uv run fabric-orch discover set --path "..." --value "..."
|
|
|
|
# Then apply
|
|
uv run fabric-orch discover set --path "..." --value "..." --no-dry-run
|
|
```
|
|
|
|
### 5. Save Exploration Results
|
|
|
|
Save interesting discoveries to files for documentation:
|
|
|
|
```bash
|
|
uv run fabric-orch discover get --path "/arista/eos/evpn" --output file:evpn-config.json
|
|
```
|
|
|
|
### 6. Use JSON Output for Scripting
|
|
|
|
For automation, use JSON output:
|
|
|
|
```bash
|
|
# Get interface names
|
|
uv run fabric-orch discover get \
|
|
--path "/interfaces/interface" \
|
|
--output json | jq -r '.notification[0].update[0].val | keys[]'
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### gNMI Not Responding
|
|
|
|
1. Verify gNMI is enabled on the device:
|
|
```
|
|
switch# show management api gnmi
|
|
```
|
|
|
|
2. Check the correct port (default: 6030 for Arista)
|
|
|
|
3. Ensure network connectivity:
|
|
```bash
|
|
nc -zv 172.16.0.50 6030
|
|
```
|
|
|
|
### Certificate Issues
|
|
|
|
For lab environments with self-signed certificates, always use `--insecure`:
|
|
|
|
```bash
|
|
uv run fabric-orch discover capabilities --target leaf1:6030 --insecure
|
|
```
|
|
|
|
### Path Not Found
|
|
|
|
1. Check path syntax - use exact key names
|
|
2. Verify the model is supported: `discover capabilities`
|
|
3. Try the parent path first
|
|
4. Check if it's config-only or state-only data
|
|
|
|
---
|
|
|
|
## See Also
|
|
|
|
- [YANG Paths Reference](yang-paths.md) - Detailed path documentation
|
|
- [gNMI Module README](../src/gnmi/README.md) - Python API documentation
|