openshift · jab-rh · Aug 22, 2024 · Feb 18, 2025 · Feb 18, 2025 · Feb 18, 2025
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -1721,6 +1721,17 @@ 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: Enabling BGP routing
+    File: enabling-bgp-routing
+  - Name: Disabling BGP routing
+    File: disabling-bgp-routing
+  - Name: Migrating FRR-K8s custom resources
+    File: migrating-frr-k8s-resources
 ---
 Name: Storage
 Dir: storage

diff --git a/modules/nw-bgp-about.adoc b/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_routing_{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, UNIX, and similar operating systems. 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
+
+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 these existing `FRRConfiguration` CRs are copied to the `openshift-frr-k8s` namespace.
+- Ensure that the third-party cluster components use the new namespace for the `FRRConfiguration` CRs that they create.
+====
+
+[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.
diff --git a/modules/nw-bgp-frr-k8s-migration.adoc b/modules/nw-bgp-frr-k8s-migration.adoc
@@ -0,0 +1,57 @@
+// 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 `FRRConfiguration` custom resources from the `metallb-system` namespace to the `openshift-frr-k8s` namespace.
+
+.Prerequisites
+
+* You have installed the {oc-first}.
+* You are logged in to the cluster as a user with the `cluster-admin` role.
+
+.Procedure
+
+When upgrading from an earlier version of {product-title} with the Metal LB Operator deployed, you must manually migrate your custom `FRRConfiguration` 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 shell script named `migrate.sh` with the following contents:
++
+[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
+----
+
+.Verification
+
+* 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 `FRRConfiguration` custom resources from the `metallb-system` namespace.
diff --git a/modules/nw-bgp-routing-disable.adoc b/modules/nw-bgp-routing-disable.adoc
@@ -0,0 +1,33 @@
+// Module included in the following assemblies:
+//
+// * networking/bgp_routing/disabling-bgp-routing.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="nw-bgp-routing-config_{context}"]
+= Disabling Border Gateway Protocol (BGP) routing
+
+As a cluster administrator, you can disable Border Gateway Protocol (BGP) routing support for your cluster on bare-metal infrastructure.
+
+[id="enabling-bgp-routing-support_{context}"]
+== Enabling BGP routing support
+
+As a cluster administrator, you can disable BGP routing support for your cluster.
+
+.Prerequisites
+
+* You have installed the {oc-first}.
+* You are logged in to the cluster as a user with the `cluster-admin` role.
+* The 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
+  }
+}'
+----
diff --git a/modules/nw-bgp-routing-enable.adoc b/modules/nw-bgp-routing-enable.adoc
@@ -0,0 +1,35 @@
+// Module included in the following assemblies:
+//
+// * networking/bgp_routing/enabling-bgp-routing.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="nw-bgp-routing-config_{context}"]
+= Enabling Border Gateway Protocol (BGP) routing
+
+As a cluster administrator, you can enable 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
+
+* You have installed the {oc-first}.
+* You are logged in to the cluster as a user with the `cluster-admin` role.
+* The 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"]
+  }
+}'
+----
diff --git a/modules/nw-operator-cr.adoc b/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`
 |

diff --git a/networking/bgp_routing/_attributes b/networking/bgp_routing/_attributes
@@ -0,0 +1 @@
+../../_attributes
diff --git a/networking/bgp_routing/about-bgp-routing.adoc b/networking/bgp_routing/about-bgp-routing.adoc
@@ -0,0 +1,23 @@
+:_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.
+
+[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 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]
diff --git a/networking/bgp_routing/disabling-bgp-routing.adoc b/networking/bgp_routing/disabling-bgp-routing.adoc
@@ -0,0 +1,11 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="disabling-bgp-routing"]
+= Disabling BGP routing
+include::_attributes/common-attributes.adoc[]
+:context: disable-bgp-routing
+
+toc::[]
+
+As a cluster administrator, you can enable OVN-Kubernetes Border Gateway Protocol (BGP) routing support for your cluster.
+
+include::modules/nw-bgp-routing-disable.adoc[leveloffset=+1]
diff --git a/networking/bgp_routing/enabling-bgp-routing.adoc b/networking/bgp_routing/enabling-bgp-routing.adoc
@@ -0,0 +1,11 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="enabling-bgp-routing"]
+= Enabling BGP routing
+include::_attributes/common-attributes.adoc[]
+:context: enabling-bgp-routing
+
+toc::[]
+
+As a cluster administrator, you can enable OVN-Kubernetes Border Gateway Protocol (BGP) routing support for your cluster.
+
+include::modules/nw-bgp-routing-enable.adoc[leveloffset=+1]
diff --git a/networking/bgp_routing/images b/networking/bgp_routing/images
@@ -0,0 +1 @@
+../../images
diff --git a/networking/bgp_routing/migrating-frr-k8s-resources.adoc b/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]
diff --git a/networking/bgp_routing/modules b/networking/bgp_routing/modules
@@ -0,0 +1 @@
+../../modules
diff --git a/networking/bgp_routing/snippets b/networking/bgp_routing/snippets
@@ -0,0 +1 @@
+../../snippets