Architecture overview
How Prelude TE peers with your network over BGP-LS, builds a consolidated view of your topology, and streams changes to your stack.
Prelude Topology Engine peers with your network over BGP-LS, keeps a live view of your topology, and streams every change to whatever downstream systems you have configured. You declare your peers and your outputs once, point the engine at your network, and it does the rest.
Three things to understand before you go further: how peering works, what the engine builds out of it, and how changes reach your stack.
Peering
Prelude TE is a passive BGP-LS speaker. You declare each peer — its address, the local and peer AS numbers, hold and keepalive timers, optional MD5 authentication — through the API or the web UI, and the engine maintains the session for you. Peers are stored in the database, so you can add, disable, or reconfigure them at runtime without restarting the engine.
You can peer with as many BGP-LS speakers as you need, in any
combination of route reflectors and direct router sessions. Each peer
keeps reporting its state in the UI (idle / connect / active / opensent / openconfirm / established) and you see the message
counters tick as updates arrive.
AS numbers can be entered in 2-byte plain (65001), 4-byte
plain (4200000001), or dotted notation (1.0) form — the
engine accepts all three.
Consolidated topology
The engine merges what every peer reports into a single, unified view
of the network. You query that view through the REST API or browse it
in the built-in web UI on port 4040.
Three things are worth knowing:
- It is live, not stored. The topology is rebuilt from your peers on every restart. BGP-LS is the source of truth — there is no cache to drift from reality.
- It is organized by domain. Each IGP scope — an ISIS area, an OSPF area, a routing realm you keep separate — is held as its own graph. Peers reporting on different IGPs populate different domains.
- Connected domains read as one network. When your network spans several IGP scopes — multi-area ISIS, inter-area OSPF, multi-IGP cores — Prelude TE surfaces both the per-domain views and a single unified view across every domain, in the UI and the API. You pick the scope per query.
- It tracks who said what. Every node, link, and prefix records the list of peers that contributed it. When a peer disappears, only the elements uniquely reported by that peer drop out; everything else stays in place. That is what makes redundant route reflectors safe to add.
Inside each domain the graph carries the usual BGP-LS objects — nodes, links, prefixes — with all the attributes BGP-LS advertises: IGP/TE metrics, bandwidth, admin groups, SRLGs, delay, and the full Segment Routing picture (SR-MPLS adjacency/prefix/node SIDs, SRv6 locators and behaviors, Flex-Algo definitions). The full schema is in the API reference.
Outputs
Whenever the topology changes — a new node appears, a link metric moves, a prefix is withdrawn — Prelude TE publishes a delta. There are two places those deltas show up:
- The web UI updates in real time, no refresh needed.
- Every configured NATS output receives a message describing the entity that changed.
Whichever surface you consume — the web UI, the REST API, or a configured output — you receive the same structured JSON object per entity, not raw BGP-LS NLRIs. Prelude TE decodes every NLRI, merges the contributions from your peers, and emits objects with consistent field names, decoded flag bits, human-readable Segment Routing endpoint behaviors, and resolved cross-references. Consumers can wire in directly without an embedded BGP-LS parser.
Two properties of the NATS stream are worth knowing as a consumer:
- Withdrawals are always published. If an entity leaves the graph, your subscriber learns about it.
- Updates are deduplicated. When a peer re-announces unchanged state — which BGP does all the time — the engine does not generate noise for you. You only get a message when the payload actually differs from the previous one.
NATS is the only output type today. See Outputs for the connection settings, authentication, and payload format.
Putting it all together
A typical deployment looks like this:
- One Prelude TE instance per site or region, packaged as an OCI image and run under Docker, Podman, or systemd.
- Two to four BGP-LS peers per domain — usually a pair of route reflectors plus one or two direct router sessions for redundancy.
- One NATS output shared with the rest of your Prelude stack, that ships every topology change to a message bus your tooling already consumes.
- Operators using the built-in web UI for peer health, topology visualization, and Flex-Algo views; planners and integrations using the REST API and the NATS stream.