BGP control plane

Active contributors: ldelossa, MrFreezeex, joestringer, julianwiedmann

Purpose

Cilium can act as a BGP speaker on every node, advertising pod CIDRs and LoadBalancer service IPs to upstream routers and learning routes from peers. This makes Cilium-native routing usable in environments where the underlay router fabric speaks BGP.

The implementation sits on top of GoBGP (vendored). A control plane in pkg/bgp/ translates Kubernetes-native CRDs into GoBGP configuration.

Directory layout

pkg/bgp/
├── manager/                # BGP session manager (per-node speaker)
├── speaker/                # speaker implementation
├── routemgr/               # route table management
├── api/                    # gRPC for cilium-dbg / cilium-cli
├── instance/               # per-instance BGP state
├── reconciler/             # CRD -> session reconciliation
├── policy/                 # route policies (filtering, route maps)
├── nodeipam/               # node IPAM integration
├── status/                 # status reporting
├── types/                  # shared types
└── ...

cilium-cli/bgp/             # `cilium bgp peers / routes / route-policies`

CRDs:

• CiliumBGPClusterConfig (v2)
• CiliumBGPPeerConfig (v2)
• CiliumBGPNodeConfig (v2)
• CiliumBGPNodeConfigOverride (v2alpha1)
• CiliumBGPAdvertisement (v2)

These supersede the older single CRD CiliumBGPPeeringPolicy (still supported in compatibility mode).

How it works

graph LR
    User[User]
    CRDs[CiliumBGP* CRDs]
    Op[cilium-operator<br/>BGP cluster reconciler]
    Agent[cilium-agent BGP cell]
    GoBGP[GoBGP speaker]
    Peer[Upstream BGP peer]

    User --> CRDs
    CRDs --> Op
    Op -->|render per-node config| CRDs
    CRDs --> Agent
    Agent --> GoBGP
    GoBGP <-->|BGP TCP/179| Peer

1. The user creates a CiliumBGPClusterConfig selecting nodes and pointing at a CiliumBGPPeerConfig and one or more CiliumBGPAdvertisements.
2. The operator selects matching nodes and emits a CiliumBGPNodeConfig per node.
3. The agent's BGP cell consumes the node config, configures GoBGP, and starts sessions with the listed peers.
4. Advertisements describe what to export — pod CIDRs, LB-IPAM IPs, service VIPs — and route policies attach communities or filter.
5. Status flows back via a separate status sub-resource that surfaces in cilium bgp peers.

Run-time visibility

kubectl -n kube-system exec ds/cilium -- cilium bgp peers
kubectl -n kube-system exec ds/cilium -- cilium bgp routes
kubectl -n kube-system exec ds/cilium -- cilium bgp route-policies

The agent exposes a gRPC API (pkg/bgp/api/) that the CLI consumes for richer queries.

Integration points

• LB-IPAM: advertised LB IPs come from CiliumLoadBalancerIPPool allocations.
• Datapath: advertised pod CIDRs reflect the CiliumNode.spec.ipam and node pod CIDRs.
• Operator: owns the CiliumBGPNodeConfig lifecycle and node selection.

Entry points for modification

• New advertisement type: extend CiliumBGPAdvertisement and the reconciler in pkg/bgp/reconciler/.
• New route policy primitive: pkg/bgp/policy/.
• New peer property: CiliumBGPPeerConfig + pkg/bgp/instance/.

Key source files

File	Purpose
pkg/bgp/manager/manager.go	Speaker manager cell.
pkg/bgp/reconciler/	CRD reconciliation.
pkg/bgp/instance/instance.go	Per-instance BGP state.
pkg/bgp/api/server.go	gRPC API for CLI.
cilium-cli/bgp/	CLI commands.