# 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?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?labels=2) |
| **Phase 3** | Full Fabric - BGP, MLAG, VRFs, dependency ordering | [phase-3-full-fabric](https://gitea.arnodo.fr/Damien/fabric-orchestrator/issues?labels=3) |
| **Phase 4** | Event-Driven - gNMI Subscribe, drift detection, webhooks | [phase-4-event-driven](https://gitea.arnodo.fr/Damien/fabric-orchestrator/issues?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
pip install -e .

# Verify gNMI connectivity to your fabric
fabric-orch discover --target leaf1:6030

# Generate execution plan
fabric-orch plan

# Apply changes
fabric-orch apply
```

## 📄 License

MIT License - See [LICENSE](LICENSE) for details.

---

**Status**: 🚧 Active Development - Phase 1