From b0b6755b0143b5671af07a564baf2c6a2555855b Mon Sep 17 00:00:00 2001 From: Emanuele Di Pascale Date: Fri, 30 Jan 2026 16:39:17 +0100 Subject: [PATCH] document hostBGP subnets and container Signed-off-by: Emanuele Di Pascale --- docs/user-guide/host-settings.md | 45 ++++++++++++++++++++++++++++++++ docs/user-guide/vpcs.md | 24 +++++++++++++++-- 2 files changed, 67 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/host-settings.md b/docs/user-guide/host-settings.md index 837b82c6..9225b7fb 100644 --- a/docs/user-guide/host-settings.md +++ b/docs/user-guide/host-settings.md @@ -95,3 +95,48 @@ kubectl fabric vpc attach --vpc-subnet vpc-2/default --connection server-1--leaf [bonding]: https://www.kernel.org/doc/html/latest/networking/bonding.html +## HostBGP container + +If using [HostBGP subnets](vpcs.md#hostbgp-subnets), BGP should be running on the host server and +an appropriate configuration should be applied. To facilitate these steps, Hedgehog provides a +docker container which automatically starts [FRR](https://docs.frrouting.org/en/latest/) with +a valid configuration to join the Fabric. + +As a first step, users should download the docker image from our registry: +```bash +docker pull ghcr.io/githedgehog/host-bgp:v0.1.1 +``` + +The container should then be run with host networking (so that FRR can communicate with the leaves +using the host's interfaces) and in privileged mode. Additionally, a few input parameters are required: + +- an optional ASN to use for BGP - if not specified the container will use ASN 64999; +- a comma-separated list of interfaces over which to establish unnumbered BGP sessions with leaves; +- a space-separated list of Virtual IPs (or VIPs) to be advertised to the leaves; these should have + a prefix length of /32 and be part of the subnet the host is attaching to. + +As an example, the command might look something like this: +```bash +docker run --network=host --privileged --rm --detach --name hostbgp ghcr.io/githedgehog/host-bgp:v0.1.1 enp2s1,enp2s2 10.100.34.5/32 +``` + +With the above command, BGP sessions would be created on interfaces `enp2s1` and `enp2s2`, +using ASN 64999 (the default), the address `10.100.34.5/32` will be configured on the loopback of +the host server and it will be advertised to the leaves. + +To further modify the configuration or to troubleshoot the state of the system, an +expert user can invoke the FRR CLI using the following command: +```bash +docker exec -it hostbgp vtysh +``` + +To stop the container, just run the following command: +```bash +docker stop -t 1 hostbgp +``` + +Note that stopping the docker container does not currently remove the VIPs from the loopback. +If needed, they can be removed manually, for example using iproute2: +```bash +sudo ip address delete dev lo +``` diff --git a/docs/user-guide/vpcs.md b/docs/user-guide/vpcs.md index 06976aeb..2dd7cfa7 100644 --- a/docs/user-guide/vpcs.md +++ b/docs/user-guide/vpcs.md @@ -56,6 +56,10 @@ spec: subnet: 10.10.100.0/24 vlan: 1100 + bgp-on-host: # Another subnet with hosts peering with leaves via BGP + subnet: 10.10.50.0/25 + hostBGP: true + permit: # Defines which subnets of the current VPC can communicate to each other, applied on top of subnets "isolated" flag (doesn't affect VPC peering) - [subnet-1, subnet-2, subnet-3] # 1, 2 and 3 subnets can communicate to each other - [subnet-4, subnet-5] # Possible to define multiple lists @@ -108,6 +112,24 @@ packet: Fabric and will be in `VrfV` format, for example `VrfVvpc-1` for a VPC named `vpc-1` in the Fabric API. * _CircuitID_ (suboption 1) identifies the VLAN which, together with the VRF (VPC) name, maps to a specific VPC subnet. +### HostBGP subnets + +At times, it is useful to have BGP running directly on the host and peering with the Fabric: one such case is +to support active-active multi-homed servers, or simply to have redundancy when other techniques such +as MCLAG or ESLAG are not available, for example because of hardware limitations. + +Consider this scenario: `server-1` is connected to two different Fabric switches `sw-1` and `sw-2`, and attached to +`vpc-1/subnet-1` on both of them. This subnet is configured as `hostBGP`; the switches will be configured to peer with +`server-1` using unnumbered BGP (IPv4 unicast address family), only importing /32 prefixes in the subnet of the VPC and +exporting routes learned from other VPC peers. Similarly, BGP is running on `server-1`, unnumbered BGP sessions are +established with each leaf, and one or more Virtual IPs (VIPs) in the VPC subnet are advertised. With this setup, the +host is part of the VPC and can be reached via one of the advertised VIPs from either link to the Fabric. + +It is important to keep in mind that Hedgehog Fabric does not directly operate the host servers attached to it; +running subnets in HostBGP mode requires running a routing suite and configuring it accordingly. To facilitate this +process, however, we do provide a container image which can autogenerate a valid configuration, given some input parameters. +For more details, see [the related section in the Host Settings page](host-settings.md#hostbgp-container). + ## VPCAttachment A VPCAttachment represents a specific VPC subnet assignment to the `Connection` object which means a binding between an @@ -279,5 +301,3 @@ user@server ~$ ip route 10.10.0.1/24 via 10.10.0.1 dev enp2s1.1000 proto dhcp src 10.10.0.4 metric 1024 # Route for VPC subnet gateway 10.10.0.1 dev enp2s1.1000 proto dhcp scope link src 10.10.0.4 metric 1024 ``` - -