Node-local routing control plane for Kubernetes — BGP, BFD, and OSPF via FRR
NovaRoute is a unified routing control service that centralizes BGP, BFD, and OSPF management on each Kubernetes node. It acts as the single owner of the FRR routing daemon, exposing a gRPC API over a Unix domain socket so that multiple clients — load balancers, CNI plugins, and administrators — can safely share one routing stack without conflicting.
NovaEdge NovaNet Admin (CLI)
│ │ │
└─────── gRPC (Unix Socket) ──────┐
│
┌─────────────────────────▼──┐
│ NovaRoute Agent │
│ Intent Store → Reconciler │
└────────────┬───────────────┘
│ vtysh
┌────────────▼───────────────┐
│ FRR Daemon │
│ BGP · BFD · OSPF · bfdd │
└────────────────────────────┘
Full Documentation · API Reference · CLI Reference
- Multi-protocol — BGP (peers, prefixes, dynamic AS, soft-reconfigure, graceful-restart, max-prefix, prefix-lists), BFD (single-hop detection), OSPF (per-interface areas)
- Intent-based — Clients declare desired state; the reconciler diffs and applies to FRR
- Multi-tenant — Ownership model with per-client tokens, prefix-type validation, and conflict detection
- Observable — Prometheus metrics at
:9100(default; configurable viametrics_address), real-time event streaming, health endpoints (/healthz,/readyz) - Production-ready — Graceful shutdown, FRR state monitoring, periodic reconciliation, error recovery
- Multi-arch — Docker images for
linux/amd64andlinux/arm64published to GHCR
# Apply the ConfigMaps and DaemonSet
kubectl apply -f deploy/configmap.yaml
kubectl apply -f deploy/daemonset.yaml# Register as an owner
novaroutectl register --owner myapp --token secret
# Add a BGP peer
novaroutectl apply-peer --owner myapp --token secret \
--neighbor 10.0.0.254 --remote-as 65001
# Advertise a prefix
novaroutectl advertise --owner myapp --token secret \
--prefix 10.10.0.0/24novaroutectl status
novaroutectl peers
novaroutectl prefixesNovaRoute reads a JSON config file (default: /etc/novaroute/config.json):
{
"listen_socket": "/run/novaroute/novaroute.sock",
"frr": {
"socket_dir": "/run/frr",
"connect_timeout": 10,
"retry_interval": 5
},
"bgp": {
"local_as": 65000,
"router_id": "10.0.0.1"
},
"owners": {
"novaedge": {
"token": "${NOVAEDGE_TOKEN}",
"allowed_prefixes": {
"type": "host_only",
"allowed_cidrs": ["10.0.0.0/8"]
}
}
},
"log_level": "info",
"metrics_address": ":9100"
}Note: the code default for metrics_address is :9100. The recommended production value is :9102 to avoid conflicts with node_exporter.
Environment variable overrides: NOVAROUTE_BGP_LOCAL_AS, NOVAROUTE_BGP_ROUTER_ID. Token values support ${ENV_VAR} expansion.
See the Configuration Guide for all options.
┌────────────────────────────────────────────────┐
│ Kubernetes Node │
│ │
│ Clients ──gRPC──▶ Server ──▶ Policy Engine │
│ │ │
│ Intent Store │
│ │ │
│ Reconciler (30s + triggered) │
│ │ │
│ FRR Client (vtysh) │
│ │ │
│ FRR Daemon │
│ (bgpd, bfdd, ospfd, zebra) │
└────────────────────────────────────────────────┘
| Component | Role |
|---|---|
| gRPC Server | 13 RPCs over Unix socket — register, peers, prefixes, BFD, OSPF, status, events |
| Policy Engine | Token auth, prefix-type validation, CIDR restrictions, cross-owner conflict check |
| Intent Store | Thread-safe in-memory store of desired routing state per owner |
| Reconciler | Diffs desired vs applied state, generates FRR commands, monitors FRR state |
| FRR Client | Translates intents into vtysh -c batched commands |
See the Architecture Guide for detailed component diagrams and data flow.
NovaRoute/
├── api/
│ ├── v1/ # Protobuf/gRPC service definition
│ └── v1alpha1/ # CRD API types for the Kubernetes operator
├── cmd/
│ ├── novaroute-agent/ # Main agent binary
│ ├── novaroute-operator/ # Kubernetes operator binary
│ ├── novaroute-test/ # Integration test binary
│ └── novaroutectl/ # CLI tool
├── internal/
│ ├── config/ # JSON config loading + env var expansion
│ ├── frr/ # FRR vtysh client (BGP, BFD, OSPF)
│ ├── intent/ # In-memory intent store
│ ├── metrics/ # Prometheus metrics
│ ├── operator/ # Kubernetes operator reconciler
│ ├── policy/ # Ownership + prefix policy engine
│ ├── reconciler/ # State reconciliation + FRR monitoring
│ └── server/ # gRPC handlers + event streaming
├── config/ # Kubernetes CRD and RBAC manifests
├── charts/ # Helm charts
├── deploy/ # Kubernetes manifests (DaemonSet, ConfigMaps)
├── docs/ # Documentation site (Jekyll)
├── .github/workflows/ # CI + release + docs deployment
├── Dockerfile # Multi-stage build (Go + Alpine + FRR)
└── Makefile # Build automation
# Build binaries
make build
# Run tests
make test
# Build Docker image
make docker-build
# Regenerate protobuf (requires protoc)
make protoWe welcome contributions! See the Contributing Guide for development setup, testing, and PR guidelines.
Apache-2.0. See LICENSE for details. FRR itself is GPL-2.0.