.. _ovn_bgp:

===
BGP
===

.. note::

   This page documents the **OVN BGP service plugin** built into Neutron.
   This is distinct from the legacy
   :ref:`neutron-dynamic-routing BGP speaker <config-bgp-dynamic-routing>`,
   which is an external project with its own agent.

The OVN BGP service plugin integrates BGP route advertisements directly into
the Neutron server and the OVN Neutron Agent.  It is designed for
**spine-and-leaf** data-centre fabrics where every rack (leaf) is an
independent L3 routing domain and inter-rack traffic is forwarded over BGP
rather than stretched L2 VLANs.

Architecture overview
---------------------

A spine-and-leaf fabric consists of:

* **Leaf switches** -- top-of-rack (ToR) switches, each providing L2
  connectivity inside a single rack.
* **Spine switches** -- interconnecting all leaf switches via routed (L3)
  links.

Because every link between a leaf and the spine is a routed link, there is no
end-to-end L2 domain across racks.  BGP runs on every leaf (and optionally on
every compute node) to exchange reachability information.

::

           ┌────────┐       ┌────────┐
           │ Spine1 │       │ Spine2 │
           └───┬┬───┘       └───┬┬───┘
         ┌─────┘└─────┬─────────┘└─────┐
         │  BGP       │  BGP           │  BGP
    ┌────┴───┐   ┌────┴───┐      ┌─────┴──┐
    │ Leaf 1 │   │ Leaf 2 │      │ Leaf N │
    └──┬──┬──┘   └──┬──┬──┘      └──┬──┬──┘
       │  │         │  │            │  │
     ┌─┘  └─┐     ┌─┘  └─┐        ┌─┘  └─┐
     CN1  CN2     CN3  CN4        CN..  CN..

Each compute node (CN) has a point-to-point L2 link to its leaf switch port.
On the Neutron server side, a **flat** provider network is connected to a BGP
logical router topology that the plugin creates in the OVN Northbound
database.  On each chassis, a **BGP peer bridge** (an OVS bridge carrying
both a physical NIC port and a patch port to ``br-int``) bridges the OVN
overlay out to that per-NIC L2 link facing the leaf switch.  This way the
relevant IP prefixes (router gateway IPs, floating IPs) are advertised to the
leaf so that return traffic from the spine can be routed back to the correct
host.

Components
~~~~~~~~~~

The feature has two components:

**BGP service plugin** (``ovn-bgp``) -- runs inside the Neutron server
process.  It watches network creation events and manages the BGP topology in
the OVN Northbound database (logical routers, route policies, VRFs).

**BGP agent extension** (``ovn-bgp``) -- runs inside the OVN Neutron Agent on
every compute/network node.  It programs OpenFlow rules on the provider bridge
so that traffic arriving from the leaf switch is correctly steered to the OVN
integration bridge, and vice-versa.

.. important::

   Neither the BGP service plugin nor the BGP agent extension speaks the BGP
   protocol itself.  They only prepare the OVN logical topology and the
   OpenFlow data-path.  An external routing suite such as
   `FRR <https://frrouting.org/>`_ must be deployed on every node where BGP
   route advertisement is required (typically every compute and network node).
   FRR peers with the leaf switch and advertises the routes that OVN makes
   available through its VRF-based logical routers.


Why VLAN provider networks are not supported
--------------------------------------------

When the BGP service plugin is enabled it **rejects creation of VLAN provider
networks** with an HTTP 400 error:

.. warning::

   VLAN provider networks are not supported when the BGP service plugin
   is enabled. Only flat provider networks are supported.

The reason is architectural.  In a spine-and-leaf fabric:

1. **L2 does not cross rack boundaries.** Each leaf switch terminates L2 at
   the rack level.  A VLAN-tagged frame leaving one leaf cannot reach a
   different leaf through the spine because the spine routes at L3.

2. **VLAN tags are a local concern.** The leaf switch strips/adds VLAN tags
   locally; they have no meaning beyond the rack.  A Neutron VLAN provider
   network implies that a given VLAN ID carries the same broadcast domain
   across all hosts -- an assumption that breaks in a routed fabric.

3. **Flat networks model the local segment correctly.** A flat provider
   network does not assume any global L2 scope.  Combined with BGP route
   advertisement the reachability of IPs behind different racks is handled
   entirely at L3, which matches the physical topology.

.. note::

   If your deployment requires VLAN segmentation within a single rack (e.g.
   for separating management traffic from tenant traffic on the same physical
   NIC), that segmentation is handled at the OVS / OS level on the host and
   does not need a Neutron VLAN provider network.

   The existing documentation for
   :ref:`BGP floating IPs over L2 segmented networks
   <config-bgp-floating-ip-over-l2-segmented-network>` describes a different
   approach that uses the legacy ``neutron-dynamic-routing`` project and VLAN
   segments confined to individual racks.  That setup is unrelated to the OVN
   BGP plugin.


Enabling the plugin
-------------------

Server side
~~~~~~~~~~~

Add ``ovn-bgp`` to the list of service plugins in ``neutron.conf``:

.. code-block:: ini

   [DEFAULT]
   service_plugins = ovn-router,ovn-bgp

The plugin registers the following configuration options under the ``[bgp]``
section:

.. list-table::
   :header-rows: 1
   :widths: 30 15 55

   * - Option
     - Default
     - Description
   * - ``main_router_vrf_id``
     - ``42``
     - VRF ID attached to the main BGP logical router.
   * - ``chassis_router_vrf_id``
     - ``10``
     - VRF ID for per-chassis BGP routers.  Used to learn default routes for
       egress traffic leaving the chassis.

Agent side
~~~~~~~~~~

On every compute or network node, enable the ``ovn-bgp`` agent extension in
the OVN agent configuration file (e.g.
``/etc/neutron/plugins/ml2/ovn_agent.ini``):

.. code-block:: ini

   [agent]
   extensions = ovn-bgp

The agent extension watches OVS and OVN Southbound events to:

* Detect provider bridge creation and configure OpenFlow rules that steer
  ingress traffic from the physical NIC to the OVN integration bridge (via
  the patch port), and allow egress traffic out.
* Track the logical router port (LRP) MAC address bound to the local chassis
  so that incoming packets are rewritten with the correct destination MAC
  before entering OVN's pipeline.
* Advertise the set of BGP bridges to the OVN Southbound ``Chassis`` table so
  that the server-side reconciler can create the appropriate per-chassis
  logical routers and route policies.


Creating provider networks
--------------------------

With the BGP plugin active, provider networks must use the **flat** type:

.. code-block:: console

   $ openstack network create --external \
       --provider-physical-network physnet1 \
       --provider-network-type flat \
       provider

Attempting to create a VLAN provider network will fail:

.. code-block:: console

   $ openstack network create --external \
       --provider-physical-network physnet1 \
       --provider-network-type vlan \
       --provider-segment 100 \
       provider-vlan
   BadRequestException: 400: ...VLAN provider networks are not supported...

Overlay (Geneve, VXLAN, GRE) self-service networks remain fully supported and
are unaffected by the BGP plugin.


Leaking tenant subnet routes
-----------------------------

By default, only the external gateway IP addresses of Neutron routers are
advertised via BGP.  The ``leak_routes`` subnet attribute allows an
administrator to additionally advertise a tenant (self-service) subnet's CIDR
to the physical fabric so that external hosts can reach tenant workloads
directly without floating IPs.

Prerequisites
~~~~~~~~~~~~~

Before enabling ``leak_routes`` on a subnet, ensure:

* The subnet belongs to a **Geneve** overlay network.
* The subnet is attached to a Neutron router that has an **external gateway**.

Enabling route leaking
~~~~~~~~~~~~~~~~~~~~~~

The ``leak_routes`` attribute is set on the subnet via an update operation.  It
is an admin-only attribute by default:

.. code-block:: console

   $ openstack subnet set --leak-routes <subnet-id>

To disable:

.. code-block:: console

   $ openstack subnet set --no-leak-routes <subnet-id>

When ``leak_routes`` is enabled the plugin:

1. Connects the BGP main logical router (``bgp-lr-main``) to the tenant
   logical switch corresponding to the subnet's network.
2. Adds a static route on ``bgp-lr-main`` for the subnet CIDR pointing to the
   router's external gateway IP as the nexthop.

The static route is then redistributed into BGP by FRR (or whichever routing
suite runs on the compute nodes), making the tenant subnet reachable from the
physical fabric.

When ``leak_routes`` is disabled (or the subnet is detached from the router)
the static route is removed.  If this was the last leaked subnet on the
network, the connection between ``bgp-lr-main`` and the tenant logical switch
is also removed.

.. _ovn-bgp-leak-routes-caveat:

Known limitation: all IPs on the network are advertised
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. important::

   OVN operates at the **logical switch** (network) level, not at the
   individual subnet level.  When ``leak_routes`` is enabled on *any* subnet
   of a network, the plugin must connect ``bgp-lr-main`` to the network's
   logical switch.  As a side effect, IP addresses from **all** subnets on
   that network -- not just the explicitly leaked subnet(s) -- become visible
   to ``bgp-lr-main`` and are advertised to the physical fabric as host
   routes via BGP.

   ``bgp-lr-main`` does **not** create routes for non-leaked subnets, so it
   will not forward traffic for those IPs.  The advertised host routes are
   therefore misleading: external hosts learn the routes but traffic sent to
   non-leaked IPs will be dropped at the ``bgp-lr-main`` router.

   This is an inherent limitation of the OVN data model, which does not
   support connecting a logical router to a single subnet within a logical
   switch.  To avoid advertising unintended IP addresses, administrators
   should place subnets that require route leaking on **dedicated networks**
   that do not share the logical switch with subnets whose addresses should
   remain hidden from the underlay.
