OSDOCS-10810: Add BGP routing

_topic_maps/_topic_map.yml

@@ -1721,6 +1721,15 @@ 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: Migrating FRR-K8s custom resources
+    File: migrating-frr-k8s-resources
 ---
 Name: Storage
 Dir: storage

modules/nw-bgp-about.adoc

@@ -0,0 +1,49 @@
+// Module included in the following assemblies:
+//
+// * networking/bgp_routing/about-bgp-routing.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="nw-bgp-about_{context}"]
+= About Border Gateway Protocol (BGP) routing
+
+{product-title} supports BGP routing through FRRouting (FRR), a free, open source internet routing protocol suite for Linux and UNIX platforms. FRR-K8s is a Kubernetes based daemon set that exposes a subset of the FRR API in a Kubernetes-compliant manner. As a cluster administrator, you can use the FRRConfiguration custom resource (CR) to access FRR services.
+
+[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.
+
+Before upgrading to 4.18, any existing FRRConfiguration in the `metallb-system` namespace not managed by the MetalLB operator (added by a cluster administrator or any other component) needs to be copied to the `openshift-frr-k8s` namespace manually, creating the namespace if necessary.
+
+[IMPORTANT]
+====
+If you are using the MetalLB Operator and there are existing `FRRConfiguration` CRs in the `metallb-system` namespace created by cluster administrators or third-party cluster components other than MetalLB Operator, you must ensure that they are copied to the `openshift-frr-k8s` namespace or that those third-party cluster components use the new namespace.
+====
+
+[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-frr-k8s-migration.adoc

@@ -0,0 +1,55 @@
+// Module included in the following assemblies:
+//
+// * networking/bgp_routing/migrating-frr-k8s-resources.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="nw-bgp-frr-k8s-migration_{context}"]
+= Migrating FRR-K8s resources
+
+You can migrate the FRR-K8s custom resources from the `metallb-system` namespace to the `openshift-frr-k8s` namespace.
+
+.Prerequisites
+
+* Install the OpenShift CLI (`oc`).
+* Log in to the cluster with a user with `cluster-admin` privileges.
+
+.Procedure
+
+When upgrading from an earlier version of {product-title} with the Metal LB Operator deployed, you must manually migrate your custom frr-k8s configurations from the `metallb-system` namespace to the `openshift-frr-k8s` namespace. To move these CRs, enter the following commands:
+
+. To create the `openshift-frr-k8s` namespace, enter the following command:
++
+[source,terminal]
+----
+$ oc create namespace openshift-frr-k8s
+----
+
+. To automate the migration, create a `migrate.sh` with the following content:
++
+[source,bash]
+----
+#!/bin/bash
+OLD_NAMESPACE="metallb-system"
+NEW_NAMESPACE="openshift-frr-k8s"
+FILTER_OUT="metallb-"
+oc get frrconfigurations.frrk8s.metallb.io -n "${OLD_NAMESPACE}" -o json |\
+  jq -r '.items[] | select(.metadata.name | test("'"${FILTER_OUT}"'") | not)' |\
+  jq -r '.metadata.namespace = "'"${NEW_NAMESPACE}"'"' |\
+  oc create -f -
+----
+
+. To execute the migration, run the following command:
++
+[source,terminal]
+----
+$ bash migrate.sh
+----
+
+. To confirm that the migration succeeded, run the following command:
++
+[source,terminal]
+----
+$ oc get frrconfigurations.frrk8s.metallb.io -n openshift-frr-k8s
+----
+
+After the migration is complete, you can remove the FRR-K8s custom resources from the `metallb-system` namespace.

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 Border Gateway Protocol (BGP) routing
+
+As a cluster administrator, you can enable or disable Border Gateway Protocol (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 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 compatible 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 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 compatible infrastructure.
+
+.Procedure
+
+* To disable dynamic routing, enter the following command:
++
+[source,terminal]
+----
+$ oc patch network.operator cluster -p '{
+  "spec": {
+    "additionalRoutingCapabilities": null
+  }
+}'
+----

modules/nw-operator-cr.adoc

@@ -110,6 +110,22 @@ endif::operator[]
 |`object`
 |Configures the network plugin for the cluster network.
 
+|`spec.additionalRoutingCapabilities.providers`
+|`array`
+|This setting enables a dynamic routing provider. The FRR routing capability provider is required for the route advertisement feature. The only supported value is `FRR`.
+
+--
+- `FRR`: The FRR routing provider
+--
+
+[source,yaml]
+----
+spec:
+  additionalRoutingCapabilities:
+    providers:
+    - FRR
+----
+
 |`spec.kubeProxyConfig`
 |`object`
 |

networking/bgp_routing/_attributes

@@ -0,0 +1 @@
+../../_attributes

networking/bgp_routing/about-bgp-routing.adoc

@@ -0,0 +1,20 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="about-bgp-routing"]
+= About BGP routing
+include::_attributes/common-attributes.adoc[]
+:context: about-bgp-routing
+
+toc::[]
+
+This feature provides native Border Gateway Protocol (BGP) routing capabilities for the cluster.
+
+If you are using the MetalLB Operator and there are existing `FRRConfiguration` CRs in the `metallb-system` namespace created by cluster administrators or third-party cluster components other than the MetalLB Operator, you must ensure that they are copied to the `openshift-frr-k8s` namespace or that those third-party cluster components use the new namespace. For more information, see xref:../../networking/bgp_routing/migrating-frr-k8s-resources.adoc#migrating-frr-k8s-resources[Migrating FRR-K8s resources].
+
+include::modules/nw-bgp-about.adoc[leveloffset=+1]
+include::modules/nw-metallb-frr-k8s-configuration-crd.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+[id="additional-resources_about-bgp-routing"]
+== Additional resources
+
+- link:https://docs.frrouting.org/en/latest/bgp.html[FRRouting User Guide: BGP]

networking/bgp_routing/configuring-bgp-routing.adoc

@@ -0,0 +1,11 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="configuring-bgp-routing"]
+= Configuring BGP routing
+include::_attributes/common-attributes.adoc[]
+:context: configuring-bgp-routing
+
+toc::[]
+
+As a cluster administrator, you can configure OVN-Kubernetes Border Gateway Protocol (BGP) routing support for your cluster.
+
+include::modules/nw-bgp-routing-config.adoc[leveloffset=+1]

networking/bgp_routing/images

@@ -0,0 +1 @@
+../../images

networking/bgp_routing/migrating-frr-k8s-resources.adoc

@@ -0,0 +1,11 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="migrating-frr-k8s-resources"]
+= Migrating FRR-K8s resources
+include::_attributes/common-attributes.adoc[]
+:context: migrating-frr-k8s-resources
+
+toc::[]
+
+All user-created FRR-K8s custom resources (CRs) in the `metallb-system` namespace under {product-title} 4.17 and earlier releases must be migrated to the `openshift-frr-k8s` namespace. As a cluster administrator, complete the steps in this procedure to migrate your FRR-K8s custom resources.
+
+include::modules/nw-bgp-frr-k8s-migration.adoc[leveloffset=+1]

networking/bgp_routing/modules

@@ -0,0 +1 @@
+../../modules

networking/bgp_routing/snippets

@@ -0,0 +1 @@
+../../snippets