diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index e02b042ee84b..503521171ead 100644 --- 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 new file mode 100644 index 000000000000..a8499dfabcdd --- /dev/null +++ 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 new file mode 100644 index 000000000000..a28c731a8288 --- /dev/null +++ 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 new file mode 100644 index 000000000000..cd34a7635917 --- /dev/null +++ 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 new file mode 100644 index 000000000000..8ab6ee86f8cd --- /dev/null +++ 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 index 0e0e51cc22e6..60fda1b7e297 100644 --- 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 new file mode 120000 index 000000000000..5b32de1e01e7 --- /dev/null +++ b/networking/bgp_routing/_attributes @@ -0,0 +1 @@ +../../_attributes \ No newline at end of file diff --git a/networking/bgp_routing/about-bgp-routing.adoc b/networking/bgp_routing/about-bgp-routing.adoc new file mode 100644 index 000000000000..0ce671977b16 --- /dev/null +++ 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 new file mode 100644 index 000000000000..4d5f239de7f7 --- /dev/null +++ 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 new file mode 100644 index 000000000000..9d318b2a770c --- /dev/null +++ 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 new file mode 120000 index 000000000000..5fa6987088da --- /dev/null +++ b/networking/bgp_routing/images @@ -0,0 +1 @@ +../../images \ No newline at end of file diff --git a/networking/bgp_routing/migrating-frr-k8s-resources.adoc b/networking/bgp_routing/migrating-frr-k8s-resources.adoc new file mode 100644 index 000000000000..37bf02f6a82c --- /dev/null +++ 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 new file mode 120000 index 000000000000..8b0e8540076d --- /dev/null +++ b/networking/bgp_routing/modules @@ -0,0 +1 @@ +../../modules \ No newline at end of file diff --git a/networking/bgp_routing/snippets b/networking/bgp_routing/snippets new file mode 120000 index 000000000000..7bf6da9a51d0 --- /dev/null +++ b/networking/bgp_routing/snippets @@ -0,0 +1 @@ +../../snippets \ No newline at end of file