document hostBGP subnets and container

Signed-off-by: Emanuele Di Pascale <emanuele@githedgehog.com>

Author: edipascale

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 <VIP>
+```

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<VPC-name>` 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
 ```
-
-