From e355cce4c8e9d256d4bdb101f68f72a3fc5f319b Mon Sep 17 00:00:00 2001 From: darnodo Date: Wed, 31 Dec 2025 17:15:56 +0100 Subject: [PATCH] docs: add CLI user guide for fabric-orch commands 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 --- docs/cli-user-guide.md | 626 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 626 insertions(+) create mode 100644 docs/cli-user-guide.md diff --git a/docs/cli-user-guide.md b/docs/cli-user-guide.md new file mode 100644 index 0000000..74d300f --- /dev/null +++ b/docs/cli-user-guide.md @@ -0,0 +1,626 @@ +# 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