BGP & Egress

The BGP & Egress tab is where the supervisor’s routing meets the physical fabric: which prefixes the cluster tells its BGP peers about, whether each node’s sessions are actually up, and how outbound traffic leaves through egress gateways.

BGP engines

The view adapts to the BGP engine the supervisor runs — the engine pill in the page header tells you which:

Engine	What it is
FRR-K8s	FRR managed through `FRRConfiguration` objects — the current default
Legacy FRR	The earlier FRR integration driven by the cluster agent
Cilium BGP control plane	Cilium’s built-in BGP speaker, configured through Cilium CRDs

Whichever engine is active, the same two surfaces render: per-node sessions and the advertise table.

Session monitoring

The session table shows one row per node and peer: peer address, local and peer ASN, session state and uptime, and the counts of advertised and received routes. A healthy row looks like this:

Node	Peer	Local AS	Peer AS	State	Uptime	Pfx sent	Pfx received
`node-1`	`10.0.0.1`	65200	65000	Established	1d12h43m	12	3

Anything other than Established means that node is not exchanging routes. A node whose session is down stops carrying traffic for advertised prefixes — with more than one node peering, the fabric routes around it; with one, the prefix goes dark. Expanding a node also shows the routes it advertises and receives, with next hop and best-path markers.

The advertise table

The advertise machinery has several layers — candidate prefixes from live objects, the operator’s selection, the engine’s expansion, and what each node’s BGP daemon actually pushes. The advertise table flattens all of it into one row per prefix:

Column	Meaning
Prefix	The advertised CIDR
Source	Where it comes from — a project’s LoadBalancer pool, a pod pool, an egress IP
Kind	`pod`, `lb`, or `egress`
Scope	`cluster` (advertised by every node) or a single node
Advertise	The operator’s intent — a toggle per row
Live	What the BGP daemon is actually doing

The Live column is the drift detector:

State	Meaning
`advertised`	Selected and present in the BGP daemon everywhere it should be
`partial`	Selected, but only some nodes are advertising it
`missing`	Selected but absent — bridge lag, or something is wrong
`off`	Not selected and not advertised — consistent
`drift`	Not selected but still being advertised

Treat drift as a real finding, not noise. A prefix the fabric can still reach after you turned it off means intent and reality have diverged — the row’s diagnostic explains where.

Two rows from a healthy-but-imperfect three-node supervisor:

Prefix	Source	Kind	Scope	Advertise	Live
`10.0.20.0/24`	system · LB pool `service-pool` (platform services)	`lb`	cluster	On	advertised · 3/3 nodes
`10.0.30.0/29`	project `shop` · LB pool	`lb`	cluster	On	partial · 2/3 nodes

The second row is what partial looks like in practice: the prefix is selected and two nodes push it, but the third does not — usually that node’s BGP session is down, or the engine has not converged yet. The session table above tells you which. Flipping a row’s toggle updates the operator selection; the engine converges and the Live column confirms it. Project-sourced rows follow the owning project’s own advertise toggles — change them on the project, and the rows here follow. The Overview tab shows a snapshot of this same table.

BGP peers

On a supervisor whose BGP engine is FRR-K8s, the BGP Configuration card lists the peers you configured. Each peer is one FRRConfiguration in frr-k8s-system. The card hides the per-node configurations that the cluster agent writes for egress addresses (bridge-node-*). Their prefixes show in the advertise table. The Cilium BGP control plane has its own peer card, and the form below is for FRR-K8s only. On that card, Add peer adds a peer with no address and an empty ASN. An empty ASN means Cilium accepts any ASN the peer announces. Apply refuses a peer until it has an address or DefaultGateway auto-discovery.

Dashboard
API
MCP

Networking → BGP & Egress → BGP Configuration → Create opens Create BGP peer. The pencil on a row opens the same form for that peer. The bin deletes the peer after you confirm.

GET /api/supervisors/{name}/frr-k8s/config lists the configurations and GET .../frr-k8s/config/{cfgName} reads one. Both need cilium:GetState. PUT .../frr-k8s/config/{cfgName} with {"spec": {...}, "md5Password": "..."} creates or replaces one, and DELETE .../frr-k8s/config/{cfgName} removes it. Both need cilium:Apply. The same routes also answer under .../networking/frr-k8s/config.

list_frr_configs and get_frr_config read. update_frr_k8s_config creates or replaces a peer. No tool deletes a peer.

Field	What it sets
NAME	The `FRRConfiguration` name. You cannot change it later. To rename, delete the peer and create it again
Local ASN, Remote ASN	The supervisor’s ASN and the peer’s ASN. Local ASN starts from the router ASN that the supervisor’s other FRR-K8s configurations share. If there is no other configuration, or they use different ASNs, enter it yourself. Remote ASN has no default. Apply refuses an ASN of `0`
Neighbor address	The address of the peer router. Required
eBGP multihop	Turn on when the peer is more than one hop away
Inbound soft reconfiguration	Keeps the routes the peer sends before your policy filters them, so you can see everything the peer offered. Off by default, because it uses memory in proportion to the number of prefixes the peer sends
TCP MD5 authentication, MD5 password	Authenticates the session with a shared password. The peer must use the same password
Keepalive (s), Hold (s)	The BGP timers. The defaults are `3` and `9` seconds
Enable BFD, Receive (ms), Transmit (ms), Multiplier	Detects a failed peer in under a second. On by default with `50` ms, `50` ms and a multiplier of `3`
Echo mode, Passive mode	BFD echo packets (the peer must support them), and waiting for the peer to start BFD. Both off by default

The password never goes into the object. The form sends it alongside the spec. If the supervisor has a working secret store, Celum keeps the password there. Without a secret store, Celum writes the Secret <name>-md5 in frr-k8s-system directly (type kubernetes.io/basic-auth, key password). The peer refers to <name>-md5 through passwordSecret. When you edit a peer, leave the password empty to keep the stored one. Type it when you create the peer, because the form does not require it. What the form writes. The form writes one router with one neighbor that advertises in mode: all, and a BFD profile named <name>-bfd. It never writes prefixes. The cluster agent owns prefixes and toAdvertise.allowed.prefixes and fills them from the advertise table. The FRR-K8s API has no field for inbound soft reconfiguration, so the form adds it as a raw FRR line: neighbor <address> soft-reconfiguration inbound. Advanced (JSON). This tab edits the FRRConfiguration spec directly, for example to add more neighbors, more routers or other raw FRR configuration. When you switch to it from Form, it shows exactly what Apply will send. Switching back to Form is refused when the spec holds more than the form can show. A peer like that always opens in Advanced (JSON). Only Form sends the MD5 password. Apply refuses a spec in which a router, or a neighbor without dynamicASN, has no ASN above 0.

Apply replaces the configuration. It does not merge. Celum writes the configuration with server-side apply, so a block you leave out of the spec is removed from the peer, for example a BFD profile or a raw line. The FRR-K8s admission webhook checks the spec, and its message comes back with 422.

When you delete a peer, Celum removes its FRRConfiguration. FRR-K8s then closes the peer’s sessions on every node at once and withdraws what was announced to that peer and learned from it. You cannot undo this. To restore the peer, enter it again.

Egress

Egress is the outbound mirror of gateways: instead of traffic coming in through a shared address, workloads leave the cluster through designated gateway nodes with a dedicated source IP (SNAT). Use it when an upstream firewall allow-lists by source address, or when compliance requires attributable egress. This tab is the single home for all three egress surfaces.

Candidate nodes

Egress gateways are label-driven: a node label marks which nodes are eligible to carry egress IPs, and the candidate-nodes card manages that label declaratively — tick the nodes that should be candidates, and the platform labels exactly those. The same candidate set drives the per-node spread preview in project creation, the agent that places egress IPs on nodes, and the gateway selection in egress policies, so there is one source of truth.

Egress HA

With a single candidate node, that node is a single point of failure for every egress IP it carries. The Egress HA section configures BGP-backed failover for the egress path:

Egress interface — the interface egress IPs are placed on, typically a VLAN subinterface of the nodes’ bond.
Local ASN and AS-path prepend count — how the egress speakers present themselves to the upstream, and how strongly standby paths are depreferenced.
Upstream peers — the routers the egress nodes peer with: address, remote ASN, optional eBGP multihop and BFD per peer. A new peer starts with neither, and Save asks for both.
BFD timers — shared receive/transmit intervals and multiplier. At 50 ms / 50 ms with a multiplier of 3, a dead node is detected in roughly 150 ms — the egress IP moves before applications notice.
Per-node settings — the candidate toggle and the BGP source address each node peers from.

The section also reports how many egress addresses are currently allocated across the candidate set, so you can see the blast radius of a node failure at a glance.

Egress HA configures the platform’s own BGP speaker on the candidate nodes — it is independent of the cluster-wide BGP engine settings above, because failover needs per-node advertise and withdraw that a cluster-scoped configuration cannot express.

Egress policies

The policy table lists every CiliumEgressGatewayPolicy. New policy creates a policy and Delete in a row’s menu removes it. You cannot edit a policy: to change one, delete it and create it again. A policy says: traffic from these pods to these destinations leaves via this gateway node with this source IP.

Field	Meaning
Destination CIDRs	Which traffic to capture — `0.0.0.0/0` for all external traffic
Excluded CIDRs	Exceptions, for example `10.0.0.0/8` to leave internal traffic alone
Pod selector	Labels matching the source pods
Namespace	Restricts the policy to one namespace
Gateway node selector	Which node performs the SNAT — required
Egress IP	The SNAT source address — must already exist on an interface of the gateway node
Interface	Alternative to an explicit IP: SNAT from this NIC’s address

A sanitized policy, as the table shows it:

name: shop-egress
destinationCIDRs: ["0.0.0.0/0"]
excludedCIDRs: ["10.0.0.0/8"]
selectors:
  - podSelector:
      matchLabels:
        io.kubernetes.pod.namespace: proj-shop
egressGateway:
  nodeSelector:
    matchLabels:
      kubernetes.io/hostname: node-2
  egressIP: 10.0.8.5

Behavior worth knowing:

Egress IP and Interface are mutually exclusive. With neither set, the default-route interface’s address is used.
In-cluster destinations are automatically excluded, even when they fall inside the destination CIDRs.
If the node selector matches several nodes, the first in lexical order wins — for deterministic placement, use the candidate machinery rather than broad selectors.

Create a policy

Dashboard
API
MCP

BGP & Egress → Egress policies → New policy opens New egress policy:

Name: required.
Destination CIDRs: one per line, starting with 0.0.0.0/0. At least one is required.
Excluded CIDRs: optional, one per line.
Namespace: leave it empty to match every namespace. Celum writes it as the io.kubernetes.pod.namespace label in the pod selector.
Pod selector: optional key=value lines. A pod must match all of them.
Gateway node selector: key=value lines, at least one. It starts as nuvira.dev/egress-gateway-candidate=true, the label that the candidate-nodes card manages.
Egress IP: optional. Pick Node’s own IP, the default, which leaves the field empty, or one of the free addresses that the picker offers from the egress band of the supervisor’s address plan. Other… lets you type an address. The form keeps Create disabled while a typed address is not a single IPv4 address or overlaps an address or range that the plan records as held. An address outside the egress band also keeps Create disabled until you turn on Place it outside the plan. The address must be routed to the gateway node, normally as a /32 advertised over BGP. If the fabric does not route the address back, the replies are lost.
Interface: optional. The NIC that carries the egress IP.

POST /api/supervisors/{name}/networking/egress with name, destinationCIDRs, excludedCIDRs, podSelector, namespaceSelector ({"namespace": "<namespace>"}), gatewayNodeSelector, egressIP and interface. DELETE .../networking/egress/{policy} removes a policy. Both need cilium:Apply. GET .../networking/egress lists the policies and needs cilium:GetState.

list_egress_policies reads the policies. get_network_candidates with view=egress-candidate-nodes lists the nodes the selector can match. No tool creates or deletes a policy.

Only the form checks the egress IP. Nothing on the server checks egressIP against the address plan or for overlaps. An API call takes any address, and so does the form when it cannot read the address plan (reading it needs cilium:GetState). The picker is then a plain text field and says that nothing checks what you type for overlaps.

Creating a policy overwrites any policy with the same name. Celum applies the policy with server-side apply and force. If the name is already in use, also by a project’s policy, Celum replaces that policy’s spec. Use a name that no other policy has.

Policies generated from a project’s egress configuration appear in the table but are read-only there — they carry the owning project in their labels and follow the project lifecycle. A project spreading several egress IPs across gateway nodes materializes as one such policy per node/IP pair. Edit the project, not the policy.

Each project’s egress IP, and the node currently carrying it, is also visible in the allocation views on the Pools & IPAM tab.

Permissions

Task	Action
Read sessions, advertise table, egress state	`cilium:GetState`
Toggle advertisements, edit BGP config, manage candidates, HA, policies	`cilium:Apply`

Both are scoped to krn:celum:supervisor:<supervisor>:cilium:*.

Pools & IPAM

The pools whose prefixes populate the advertise table.

Project networking

The per-tenant intent behind read-only policies and project advertise rows.

Gateways & Routes

The inbound counterpart to egress.

Networking overview

The engine model and the Overview tab’s advertise snapshot.

Get Started

Concepts

Clusters

GitOps & Apps

Virtual machines

Networking

Security

Platform Health

Storage

Reference

Administration

BGP & Egress

BGP engines

Session monitoring

The advertise table

BGP peers

Egress

Candidate nodes

Egress HA

Egress policies

Create a policy

Permissions

Pools & IPAM

Project networking

Gateways & Routes

Networking overview

​BGP engines

​Session monitoring

​The advertise table

​BGP peers

​Egress

​Candidate nodes

​Egress HA

​Egress policies

​Create a policy

​Permissions

​Related

Pools & IPAM

Project networking

Gateways & Routes

Networking overview

BGP engines

Session monitoring

The advertise table

BGP peers

Egress

Candidate nodes

Egress HA

Egress policies

Create a policy

Permissions

Related