OSDOCS-10810: Add BGP routing

_topic_maps/_topic_map.yml

@@ -1721,6 +1721,13 @@ Topics:
     File: metallb-troubleshoot-support
 - Name: Associating secondary interfaces metrics to network attachments
   File: associating-secondary-interfaces-metrics-to-network-attachments
+- Name: BGP routing
+  Dir: bgp_routing
+  Topics:
+  - Name: About BGP routing
+    File: about-bgp-routing
+  - Name: Configuring BGP routing
+    File: configuring-bgp-routing
 ---
 Name: Storage
 Dir: storage

modules/nw-bgp-about.adoc

@@ -0,0 +1,55 @@
+// Module included in the following assemblies:
+//
+// * networking/bgp_routing/about-bgp-routing.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="nw-bgp-about_{context}"]
+= Route advertisements with BGP
+
+With route advertisements enabled, {product-title} Networking supports the following features:
+
+- Importing routes from the provider network
+- Exporting routes into the provider network
+- Supporting multi-homing, link redundancy, and fast convergence for provider network gateways
+////
+https://github.com/openshift/openshift-docs/pull/85842/files#r1900917285
+- Improving throughput and reducing packet overhead
+////
+
+[id="supported-platforms_{context}"]
+== Supported platforms
+
+BGP routing is supported on the following infrastructure types:
+
+- Bare-metal
+- {vmw-full} on-premise
+
+[id="prerequisites_{context}"]
+== Prerequisites
+
+Use of BGP routing requires that you have properly configured BGP for your network provider. Outages or misconfigurations of your network provider might cause disruptions to your cluster network.
+
+[id="considerations-for-use-with-the-metallb-operator_{context}"]
+== Considerations for use with the MetalLB Operator
+
+The MetalLB Operator is installed as an add-on to the cluster. Deployment of the MetalLB Operator automatically enables FRR-K8s as an additional routing capability provider and uses the FRR-K8s daemon installed by this feature.
+
+[IMPORTANT]
+====
+If you are using the MetalLB Operator, you must manually copy any existing `FRRConfiguration` CRs in the `metallb-system` namespace to the `openshift-frr-k8s` namespace. This includes `FRRConfiguration` CRs created by both cluster administrators and by cluster components.
+====
+
+[id="cluster-network-operator_{context}"]
+== Cluster Network Operator configuration
+
+The Cluster Network Operator API exposes the following API field to configure BGP routing:
+
+- `spec.additionalRoutingCapabilities`: Enables deployment of the FRR-K8S daemon for the cluster, which can be used independently of route advertisements. When enabled, the FRR-K8S daemon is deployed on all nodes.
+
+[id="bgp-routing-custom-resources_{context}"]
+== BGP routing custom resources
+
+The following custom resources are used to configure BGP routing:
+
+`FRRConfiguration`::
+This custom resource defines the FRR configuration for the BGP routing. This CR is namespaced.

modules/nw-bgp-examples.adoc

@@ -0,0 +1,245 @@
+// Module included in the following assemblies:
+//
+// * networking/bgp-routing/about-bgp-routing.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="nw-bgp-examples_{context}"]
+= Examples advertising pod IP addresses with BGP
+
+The following examples describe several different configurations for advertising pod IP addresses with BGP. The external network border router has the `172.18.0.5` IP address.
+
+Each example relies upon the following `FRRConfiguration` object:
+
+.`FRRConfiguration` CR
+[source,yaml]
+----
+apiVersion: frrk8s.metallb.io/v1beta1
+kind: FRRConfiguration
+metadata:
+  name: receive-all
+  namespace: openshift-frr-k8s
+spec:
+  bgp:
+    routers:
+    - asn: 64512
+      neighbors:
+      - address: 172.18.0.5
+        asn: 64512
+        disableMP: true
+        toReceive:
+          allowed:
+            mode: filtered
+----
+
+The OVN-Kubernetes controller checks that the `RouteAdvertisements` CR selected nodes are a subset of the nodes selected by the `RouteAdvertisements` CR selected FRRConfigurations.
+
+For these examples a user-defined network named `blue` exists with a network of `10.0.0.0/16` and a matching VRF device exists in the Linux host. The slice of this supernet allocated to nodes with the `kubernetes.io/hostname: ovn-worker` label is `10.0.1.0/24`.
+
+[id="advertising-pod-ips-from-a-user-defined-network-over-bgp_{context}"]
+== Advertising pod IPs from a user-defined network over BGP
+
+In this scenario, the blue user-defined network is exposed to the external network so that the attached pods have IP addresses that are reachable from the external network. The user-defined networks are each attached to a different VRF device:
+
+Red user-defined network::
+- A VRF named `mp0-red`
+- A subnet of `10.0.0.0/24`
+
+Blue user-defined network::
+- A VRF named `mp0-blue`
+- A subnet of `10.0.1.0/24`
+
+In this configuration, two separate user-defined networks are defined. The red network covers the `10.0.0.0/24` subnet and the blue network covers the `10.0.1.0/24` subnet.
+
+The following `RouteAdvertisements` CR describes the configuration for the blue tenant:
+
+.`RouteAdvertisements` CR for the blue tenant
+[source,yaml]
+----
+apiVersion: k8s.ovn.org/v1
+kind: RouteAdvertisements
+metadata:
+  name: default
+spec:
+  advertisements:
+  - PodNetwork
+  networkSelector:
+    matchLabels:
+      k8s.ovn.org/metadata.name: blue
+  frrConfigurationSelector:
+    matchLabels:
+      routeAdvertisements: receive-all
+----
+
+When the OVN-Kubernetes controller sees this `RouteAdvertisements` CR, it generates a `FRRConfiguration` object that configures the FRR daemon to advertise the routes.
+
+.`FRRConfiguration` CR generated by OVN-Kubernetes
+[source,yaml]
+----
+apiVersion: frrk8s.metallb.io/v1beta1
+kind: FRRConfiguration
+metadata:
+  name: ovnk-generated-abcdef
+  namespace: openshift-frr-k8s
+spec:
+  bgp:
+    routers:
+    - asn: 64512
+      vrf: blue
+      imports:
+      - vrf: default
+    - asn: 64512
+      neighbors:
+        - address: 172.18.0.5
+          asn: 64512
+          toReceive:
+            allowed:
+              prefixes:
+              - 10.0.1.0/16
+                le: 24
+                ge:24
+          toAdvertise:
+            allowed:
+              prefixes:
+              - 10.0.1.0/24
+      prefixes:
+      - 10.0.1.0/24
+      imports:
+      - vrf: blue
+  nodeSelector:
+    matchLabels:
+      kubernetes.io/hostname: ovn-worker
+----
+
+The generated `FRRConfiguration` object configures the subnet `10.0.1.0/24`, which belongs to VRF blue, is imported into the default VRF and advertised to the `172.18.0.5` neighbor. An `FRRConfiguration` object is generated for each node selected by a `RouteAdvertisements` CR with the appropriate prefixes that apply to each node.
+
+Because the `targetVRF` uses the default value, the routes are leaked and advertised in the default VRF. Additionally, routes are imported from the default VRF into the blue VRF.
+
+[id="advertising-pod-ips-from-a-user-defined-network-over-bgp-with-vpn_{context}"]
+== Advertising pod IPs from a user-defined network over BGP with VPN
+
+In this scenario, a VLAN interface is attached to the VRF device associated with the blue network. This setup provides a _VRF lite_ design where FRR-K8S is leveraged to advertise the blue network over only the corresponding VRF/VLAN link to the next hop PE router. The red tenant uses the same configuration.
+
+Red user-defined network::
+- A VRF named `mp0-red`
+- A VLAN interface attached to the VRF device and connected to the external PE router
+- An assigned subnet of `10.0.2.0/24`
+
+Blue user-defined network::
+- A VRF named `mp0-blue`
+- A VLAN interface attached to the VRF device and connected to the external PE router
+- An assigned subnet of `10.0.1.0/24`
+
+[NOTE]
+====
+This approach is available only when using OVN-Kubernetes local gateway mode by setting `routingViaHost=true`.
+====
+
+In the following configuration, an additional `FRRConfiguration` CR configures peering with the PE router on the blue and red VLANs:
+
+.`FRRConfiguration` CR manually configured for BGP VPN setup
+[source,yaml]
+----
+apiVersion: frrk8s.metallb.io/v1beta1
+kind: FRRConfiguration
+metadata:
+  name: vpn-blue-red
+  namespace: openshift-frr-k8s
+  labels:
+    routeAdvertisements: vpn-blue-red
+spec:
+  bgp:
+    routers:
+    - asn: 64512
+      vrf: blue
+      neighbors:
+      - address: 182.18.0.5
+        asn: 64512
+        toReceive:
+          allowed:
+            mode: filtered
+    - asn: 64512
+      vrf: red
+      neighbors:
+      - address: 192.18.0.5
+        asn: 64512
+        toReceive:
+          allowed:
+            mode: filtered
+----
+
+The following `RouteAdvertisements` CR describes the configuration for the blue and red tenants:
+
+.`RouteAdvertisements` CR for the blue and red tenants
+[source,yaml]
+----
+apiVersion: k8s.ovn.org/v1
+kind: RouteAdvertisements
+metadata:
+  name: default
+spec:
+  targetVRF: auto
+  advertisements:
+    - PodNetwork
+  networkSelector:
+    matchExpressions:
+    - { key: k8s.ovn.org/metadata.name, operator: In, values: [blue,red] }
+  frrConfigurationSelector:
+    matchLabels:
+      routeAdvertisements: vpn-blue-red
+----
+
+In the `RouteAdvertisements` CR the `targetVRF` is set to `auto` so that advertisements will occur within the VRF device corresponding to the individual networks selected. In this scenario, the pod subnet for blue is advertised over the blue VRF device and the pod subnet for red is advertised over the red VRF device.
+
+When the OVN-Kubernetes controller sees this `RouteAdvertisements` CR, it generates a `FRRConfiguration` object that configures the FRR daemon to advertise the routes for the blue and red tenants.
+
+.`FRRConfiguration` CR generated by OVN-Kubernetes for blue and red tenants
+[source,yaml]
+----
+apiVersion: frrk8s.metallb.io/v1beta1
+kind: FRRConfiguration
+metadata:
+  name: ovnk-generated-abcde
+  namespace: openshift-frr-k8s
+spec:
+  bgp:
+    routers:
+    - asn: 64512
+      neighbors:
+      - address: 182.18.0.5
+        asn: 64512
+        toReceive:
+          allowed:
+            prefixes:
+            - 10.0.1.0/16
+              le: 24
+              ge:24
+        toAdvertise:
+          allowed:
+            prefixes:
+            - 10.0.1.0/24
+      vrf: blue
+      prefixes:
+        - 10.0.1.0/24
+    - asn: 64512
+      neighbors:
+      - address: 192.18.0.5
+        asn: 64512
+        toReceive:
+          allowed:
+            prefixes:
+            - 10.0.2.0/16
+              le: 24
+              ge:24
+        toAdvertise:
+          allowed:
+            prefixes:
+            - 10.0.2.0/24
+      vrf: red
+      prefixes:
+         - 10.0.2.0/24
+  nodeSelector:
+     matchLabels:
+        kubernetes.io/hostname: ovn-worker
+----
+
+In this scenario, any filtering or selection of routes to receive must be done in the `FRRConfiguration` CR that defines peering relationships. An `FRRConfiguration` object is generated for each node selected by a `RouteAdvertisements` CR with the appropriate prefixes that apply to each node.

modules/nw-bgp-routeadvertisements-object.adoc

@@ -0,0 +1 @@
+// omit

modules/nw-bgp-routing-config.adoc

@@ -0,0 +1,59 @@
+// Module included in the following assemblies:
+//
+// * networking/bgp_routing/configuring-bgp-routing.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="nw-bgp-routing-config_{context}"]
+= Configuring BGP routing
+
+As a cluster administrator, you can enable or disable BGP routing support for your cluster on bare-metal infrastructure.
+
+If you are using BGP routing in conjunction with the MetalLB Operator, the necessary BGP routing support is enabled automatically. You do not need to manually enable BGP routing support.
+
+[id="enabling-bgp-routing-support_{context}"]
+== Enabling BGP routing support
+
+As a cluster administrator, you can enable Border Gateway Protocol (BGP) routing support for your cluster.
+
+.Prerequisites
+
+* Install the OpenShift CLI (`oc`).
+* Log in to the cluster with a user with `cluster-admin` privileges.
+* Cluster is installed on bare-metal infrastructure.
+
+.Procedure
+
+* To enable a dynamic routing provider, enter the following command:
++
+[source,terminal]
+----
+$ oc patch network.operator cluster -p '{
+  "spec": {
+    "additionalRoutingCapabilities": ["FRR"]
+  }
+}'
+----
+
+[id="disabling-bgp-routing-support_{context}"]
+== Disabling BGP routing support
+
+As a cluster administrator, you can disable Border Gateway Protocol (BGP) routing support for your cluster.
+
+.Prerequisites
+
+* Install the OpenShift CLI (`oc`).
+* Log in to the cluster with a user with `cluster-admin` privileges.
+* Cluster is installed on bare-metal infrastructure.
+
+.Procedure
+
+* To disable dynamic routing, enter the following command:
++
+[source,terminal]
+----
+$ oc patch network.operator cluster -p '{
+  "spec": {
+    "additionalRoutingCapabilities": null
+  }
+}'
+----