Files

darnodo e355cce4c8 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

2025-12-31 17:15:56 +01:00

20 KiB

Raw Blame History

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.

Installation
Quick Start
Environment Variables
Commands Overview
discover capabilities
discover get
discover set
discover subscribe
discover paths
Output Formats
Error Handling
Best Practices

Installation

Ensure you have Python 3.12+ and uv installed, then:

# 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

# 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:

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

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

# 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

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

# 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

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

# 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.

# 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

Subscribe to YANG path updates in real-time.

Usage

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

# 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:

# ✅ 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

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.

uv run fabric-orch discover get --path "/system/config" --output pretty

JSON

Machine-readable JSON output, suitable for piping to jq or other tools.

uv run fabric-orch discover get --path "/system/config" --output json | jq '.'

File

Save output directly to a file.

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:

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:

uv run fabric-orch discover capabilities

3. Explore Incrementally

Start with broad paths and narrow down:

# 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:

# 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:

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:

# 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

Verify gNMI is enabled on the device:
```
switch# show management api gnmi
```
Check the correct port (default: 6030 for Arista)
Ensure network connectivity:
```
nc -zv 172.16.0.50 6030
```

Certificate Issues

For lab environments with self-signed certificates, always use --insecure:

uv run fabric-orch discover capabilities --target leaf1:6030 --insecure

Path Not Found

Check path syntax - use exact key names
Verify the model is supported: discover capabilities
Try the parent path first
Check if it's config-only or state-only data

20 KiB Raw Blame History

Fabric Orchestrator CLI User Guide

Table of Contents

Installation

Quick Start

Environment Variables

Commands Overview

discover capabilities

Usage

Options

Examples

Sample Output

discover get

Usage

Options

Examples

Path Syntax

Common Paths

discover set

Usage

Options

Examples

Operations

Dry-Run Mode

discover subscribe

Usage

Options

Examples

Subscription Modes

Important Note for Arista EOS

Stopping Subscriptions

discover paths

Usage

Example Output

Output Formats

Pretty (default)

JSON

File

Error Handling

Connection Errors

Path Errors

Best Practices

1. Use Environment Variables

2. Start with Capabilities

3. Explore Incrementally

4. Use Dry-Run for Set Operations

5. Save Exploration Results

6. Use JSON Output for Scripting

Troubleshooting

gNMI Not Responding

Certificate Issues

Path Not Found

See Also

20 KiB

Raw Blame History