f8ef64e9b0
- Update the dependency installation command in the main README to use `uv sync` instead of `pip`, reflecting the project's package manager. - Realign markdown tables in `src/yang/README.md` to improve raw text readability and consistency.
171 lines
10 KiB
Markdown
171 lines
10 KiB
Markdown
# Fabric Orchestrator
|
|
|
|
**Declarative Network Infrastructure Management for Arista EVPN-VXLAN Fabrics**
|
|
|
|
A Terraform-like orchestration system that uses NetBox as Source of Truth and gNMI/YANG for atomic configuration management of Arista data center fabrics.
|
|
|
|
## 🎯 Project Vision
|
|
|
|
Transform network infrastructure management from imperative scripting to true declarative infrastructure-as-code, where:
|
|
|
|
- **Intent** is defined in NetBox (ConfigContexts, Custom Fields)
|
|
- **State** is continuously monitored via gNMI Subscribe
|
|
- **Changes** are computed as diffs and applied atomically via gNMI Set
|
|
- **Drift** is detected and optionally auto-remediated
|
|
|
|
Think `terraform plan` and `terraform apply`, but for your network fabric.
|
|
|
|
## 🏗️ Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ INTENT LAYER │
|
|
│ ┌─────────────┐ ┌──────────────────┐ ┌─────────────────────────────┐ │
|
|
│ │ NetBox │ │ ConfigContexts │ │ Custom Fields / Tags │ │
|
|
│ │ (SoT) │◄──►│ (Structured │◄──►│ (VLAN, VNI, VRF, BGP AS) │ │
|
|
│ │ │ │ Intent Data) │ │ │ │
|
|
│ └──────┬──────┘ └──────────────────┘ └─────────────────────────────┘ │
|
|
└─────────┼───────────────────────────────────────────────────────────────────┘
|
|
│ Webhook / Polling
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ ORCHESTRATION LAYER │
|
|
│ ┌─────────────────────────────────────────────────────────────────────────┐│
|
|
│ │ State Reconciliation Engine ││
|
|
│ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────────────────┐ ││
|
|
│ │ │ Intent Parser │ │ Diff Engine │ │ Transaction Planner │ ││
|
|
│ │ │ (NetBox→YANG) │──►│ (Want vs Have)│──►│ (Ordered gNMI SetReqs) │ ││
|
|
│ │ └───────────────┘ └───────────────┘ └───────────────────────────┘ ││
|
|
│ └─────────────────────────────────────────────────────────────────────────┘│
|
|
│ │ │
|
|
│ ┌─────────────────────────────────┼───────────────────────────────────────┐│
|
|
│ │ Event Bus (Redis / NATS) ││
|
|
│ │ • config_drift_detected • intent_changed • apply_complete ││
|
|
│ └─────────────────────────────────────────────────────────────────────────┘│
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
│ gNMI Subscribe (Telemetry) │ gNMI Set (Config)
|
|
▼ ▼
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ DEVICE LAYER │
|
|
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
|
|
│ │ spine1 │ │ spine2 │ │ leaf1 │ │ leaf2 │ ... │
|
|
│ │ gNMI:6030 │ │ gNMI:6030 │ │ gNMI:6030 │ │ gNMI:6030 │ │
|
|
│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## 🔧 Target Fabric
|
|
|
|
This project is designed for the Arista EVPN-VXLAN ContainerLab topology:
|
|
|
|
- **2 Spines** (BGP Route Reflectors, AS 65000)
|
|
- **8 Leafs** (4 MLAG VTEP pairs, AS 65001-65004)
|
|
- **cEOS 4.35.0F** with gNMI enabled
|
|
- **EVPN Type-2** (L2 VXLAN) and **Type-5** (L3 VXLAN) support
|
|
|
|
Reference: [arista-evpn-vxlan-clab](https://gitea.arnodo.fr/Damien/arista-evpn-vxlan-clab)
|
|
|
|
## 📋 Project Phases
|
|
|
|
Progress is tracked via issues. See [all issues](https://gitea.arnodo.fr/Damien/fabric-orchestrator/issues) or filter by phase:
|
|
|
|
| Phase | Description | Issues |
|
|
|-------|-------------|--------|
|
|
| **Phase 1** | YANG Path Discovery - Map EOS 4.35.0F YANG models, validate gNMI | [phase-1-yang-discovery](https://gitea.arnodo.fr/Damien/fabric-orchestrator/issues?type=all&state=all&labels=1) |
|
|
| **Phase 2** | Minimal Reconciler - VLANs/VNIs, diff engine, CLI plan/apply | [phase-2-minimal-reconciler](https://gitea.arnodo.fr/Damien/fabric-orchestrator/issues?type=all&state=all&labels=2) |
|
|
| **Phase 3** | Full Fabric - BGP, MLAG, VRFs, dependency ordering | [phase-3-full-fabric](https://gitea.arnodo.fr/Damien/fabric-orchestrator/issues?type=all&state=all&labels=3) |
|
|
| **Phase 4** | Event-Driven - gNMI Subscribe, drift detection, webhooks | [phase-4-event-driven](https://gitea.arnodo.fr/Damien/fabric-orchestrator/issues?type=all&state=all&labels=4) |
|
|
|
|
📌 **Project Board**: [View Kanban](https://gitea.arnodo.fr/Damien/fabric-orchestrator/projects)
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
fabric-orchestrator/
|
|
├── README.md
|
|
├── pyproject.toml
|
|
├── docker-compose.yml # Redis, API server
|
|
├── src/
|
|
│ ├── __init__.py
|
|
│ ├── cli.py # CLI interface (plan, apply, drift)
|
|
│ ├── api.py # FastAPI server for webhooks
|
|
│ ├── reconciler/
|
|
│ │ ├── engine.py # Core reconciliation logic
|
|
│ │ ├── diff.py # State comparison
|
|
│ │ └── planner.py # Change ordering/dependencies
|
|
│ ├── yang/
|
|
│ │ ├── mapper.py # NetBox intent → YANG paths
|
|
│ │ ├── paths.py # YANG path definitions
|
|
│ │ └── validators.py # Schema validation
|
|
│ ├── gnmi/
|
|
│ │ ├── client.py # gNMI client wrapper
|
|
│ │ └── transactions.py # Atomic operations
|
|
│ ├── netbox/
|
|
│ │ ├── client.py # NetBox API client
|
|
│ │ └── models.py # Intent data models
|
|
│ └── events/
|
|
│ ├── handlers.py # Event handlers
|
|
│ └── bus.py # Event bus (Redis)
|
|
├── tests/
|
|
└── docs/
|
|
├── architecture.md
|
|
├── yang-paths.md # Documented YANG paths
|
|
└── netbox-schema.md # ConfigContext schema
|
|
```
|
|
|
|
## 🛠️ Technology Stack
|
|
|
|
| Component | Technology | Purpose |
|
|
|-----------|------------|---------|
|
|
| Source of Truth | NetBox | Intent definition via ConfigContexts |
|
|
| Transport | gNMI | Configuration and telemetry |
|
|
| Data Models | YANG (OpenConfig + Arista) | Structured configuration |
|
|
| Orchestrator | Python (asyncio) | Reconciliation engine |
|
|
| CLI | Click + Rich | User interface |
|
|
| API | FastAPI | Webhook receiver |
|
|
| Event Bus | Redis | Async event handling |
|
|
| Lab | ContainerLab + cEOS | Development environment |
|
|
|
|
## 🔗 Related Projects
|
|
|
|
- [arista-evpn-vxlan-clab](https://gitea.arnodo.fr/Damien/arista-evpn-vxlan-clab) - Target fabric topology
|
|
- [projet-vxlan-automation](https://gitea.arnodo.fr/Damien/projet-vxlan-automation) - Previous NetBox RenderConfig work
|
|
- [Arista YANG Models](https://github.com/aristanetworks/yang/tree/master/EOS-4.35.0F) - EOS 4.35.0F YANG definitions
|
|
|
|
## 📚 References
|
|
|
|
### YANG / gNMI
|
|
- [Arista gNMI Documentation](https://aristanetworks.github.io/openmgmt/configuration/gnmi/)
|
|
- [OpenConfig Models](https://github.com/openconfig/public)
|
|
- [pygnmi Library](https://github.com/akarneliuk/pygnmi)
|
|
|
|
### EVPN-VXLAN
|
|
- [Arista BGP EVPN Configuration Example](https://overlaid.net/2019/01/27/arista-bgp-evpn-configuration-example/)
|
|
- [Arista EVPN Deployment Guide](https://www.arista.com/en/solutions/evpn-vxlan)
|
|
|
|
## 🚀 Getting Started
|
|
|
|
*Coming in Phase 1*
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://gitea.arnodo.fr/Damien/fabric-orchestrator.git
|
|
cd fabric-orchestrator
|
|
|
|
# Install dependencies
|
|
uv sync
|
|
|
|
# Verify gNMI connectivity to your fabric
|
|
fabric-orch discover --target leaf1:6030
|
|
|
|
# Generate execution plan
|
|
fabric-orch plan
|
|
|
|
# Apply changes
|
|
fabric-orch apply
|
|
```
|
|
|
|
---
|
|
|
|
**Status**: 🚧 Active Development - Phase 1
|