openshift · JoeAldinger · Mar 5, 2026 · Mar 5, 2026 · Mar 5, 2026 · Apr 7, 2026
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -1857,6 +1857,8 @@ Topics:
       File: enabling-bgp-routing
     - Name: Disabling BGP routing
       File: disabling-bgp-routing
+    - Name: Improve east-west performance by routing pods on the underlay with BGP
+      File: no-overlay-mode-bgp-routing
     - Name: Migrating FRR-K8s custom resources
       File: migrating-frr-k8s-resources
   - Name: Route advertisements

diff --git a/modules/nw-no-overlay-configure-bgp-infrastructure.adoc b/modules/nw-no-overlay-configure-bgp-infrastructure.adoc
@@ -0,0 +1,69 @@
+// Module included in the following assemblies:
+//
+// * networking/advanced_networking/bgp_routing/no-overlay-mode-bgp-routing.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="nw-no-overlay-configure-bgp-infrastructure_{context}"]
+= Set up BGP and FRR-K8s for underlay pod routing
+
+[role="_abstract"]
+Configure BGP peers and FRR-K8s so nodes can exchange pod subnet routes for no-overlay networks.
+
+.Prerequisites
+* You have cluster-admin privileges.
+* Your cluster is installed on bare-metal infrastructure with single-node zone interconnect mode.
+* You enabled BGP routing support for the cluster.
+* You deployed FRR-K8s on cluster nodes.
+
+.Procedure
+. Verify that the FRR-K8s pods are running by entering the following command:
++
+[source,terminal]
+----
+$ oc get pods -n openshift-frr-k8s
+----
+
+. If you plan to use unmanaged routing, create an `FRRConfiguration` custom resource (CR) that defines your BGP peers. The following example shows an external peer:
++
+.Example `FRRConfiguration` CR
+[source,yaml]
+----
+apiVersion: frrk8s.metallb.io/v1beta1
+kind: FRRConfiguration
+metadata:
+  name: external-peer
+  namespace: openshift-frr-k8s
+spec:
+  bgp:
+    routers:
+    - asn: 64512
+      neighbors:
+      - address: 192.0.2.1
+        asn: 64513
+        toReceive:
+          allowed:
+            mode: all
+----
+
+.. Apply the `FRRConfiguration` CR by entering the following command:
++
+[source,terminal]
+----
+$ oc apply -f <frrconfiguration_file>.yaml
+----
++
+Replace `<frrconfiguration_file>.yaml` with the name of your `FRRConfiguration` CR file.
+
+.. Verify that the `FRRConfiguration` CR you created is deployed by running the following command:
++
+[source,terminal]
+----
+$ oc get frrconfiguration -n openshift-frr-k8s
+----
+
+.. Confirm that BGP sessions are established by reviewing FRR-K8s logs with the following command:
++
+[source,terminal]
+----
+$ oc logs -n openshift-frr-k8s -l app=frr-k8s
+----
diff --git a/modules/nw-no-overlay-cudn-config-ref.adoc b/modules/nw-no-overlay-cudn-config-ref.adoc
@@ -0,0 +1,52 @@
+// Module included in the following assemblies:
+//
+// * networking/advanced_networking/bgp_routing/no-overlay-mode-bgp-routing.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="nw-no-overlay-cudn-config-ref_{context}"]
+= Reference for ClusterUserDefinedNetwork underlay routing settings
+
+[role="_abstract"]
+Review the no-overlay fields for a ClusterUserDefinedNetwork so you can define transport, routing mode, and outbound SNAT behavior.
+
+`transport`::
+Specifies the transport type for the network. Use `NoOverlay` to disable Geneve encapsulation.
+
+`noOverlayOptions`::
+Required when `transport` is `NoOverlay`. This object contains `routing` and `outboundSNAT` settings.
+
+`noOverlayOptions.routing`::
+Specifies the routing mode for the network. Use `Managed` for an OVN-Kubernetes-managed fabric or `Unmanaged` to manage routing externally.
+
+`noOverlayOptions.outboundSNAT`::
+Specifies whether outbound pod traffic is SNATed. Use `Enabled` when pod IPs are not routable on the external network and `Disabled` when they are routable.
+
+`status.conditions[type="TransportAccepted"]`::
+Indicates whether no-overlay transport is configured and accepted for the network.
+
+.Example `ClusterUserDefinedNetwork` CR for no-overlay mode
+[source,yaml]
+----
+apiVersion: k8s.ovn.org/v1
+kind: ClusterUserDefinedNetwork
+metadata:
+  name: high-perf-network
+spec:
+  namespaceSelector:
+    matchLabels:
+      app: performance-sensitive
+  network:
+    topology: Layer3
+    layer3:
+      role: Primary
+      mtu: 1500
+      subnets:
+      - cidr: 10.200.0.0/16
+        hostSubnet: 24
+    transport: "NoOverlay"
+    noOverlayOptions:
+      outboundSNAT: "Disabled"
+      routing: "Unmanaged"
+----
++
+The `spec` field of a `ClusterUserDefinedNetwork` CR is immutable. You cannot change the `transport` configuration after the CR is created.
diff --git a/modules/nw-no-overlay-default-network-config-ref.adoc b/modules/nw-no-overlay-default-network-config-ref.adoc
@@ -0,0 +1,42 @@
+// Module included in the following assemblies:
+//
+// * networking/advanced_networking/bgp_routing/no-overlay-mode-bgp-routing.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="nw-no-overlay-default-network-config-ref_{context}"]
+= Reference for default network underlay routing settings
+
+[role="_abstract"]
+Review the OVN-Kubernetes no-overlay settings for the default network to choose routing mode and outbound SNAT behavior.
+
+The no-overlay configuration for the default network is set in the OVN-Kubernetes configuration file.
+
+`transport` in `[default]` section::
+Specifies the transport type for the default network. Use `no-overlay` to disable Geneve encapsulation.
+
+`routing` in `[no-overlay]` section::
+Specifies the routing mode for no-overlay traffic. Use `managed` for a full-mesh BGP fabric or `unmanaged` to manage routing externally.
+
+`outbound-snat` in `[no-overlay]` section::
+Specifies whether outbound pod traffic to the external network is SNATed to the node IP. Use `enabled` when pod IPs are not routable on the external network and `disabled` when they are routable. Pod-to-pod traffic within the cluster is never SNATed; traffic to node IPs, the Kubernetes API server, and DNS is always SNATed.
+
+`topology` in `[bgp-managed]` section::
+Specifies the internal BGP topology when `routing = managed`. The supported value is `full-mesh`.
+
+`as-number` in `[bgp-managed]` section::
+Specifies the BGP autonomous system number for managed routing. If not set, the default is `64512`.
+
+.Example no-overlay configuration for the default network
+[source,ini]
+----
+[default]
+transport = no-overlay
+
+[no-overlay]
+routing = managed
+outbound-snat = enabled
+
+[bgp-managed]
+topology = full-mesh
+as-number = 64512
+----
diff --git a/modules/nw-no-overlay-enable-cudn.adoc b/modules/nw-no-overlay-enable-cudn.adoc
@@ -0,0 +1,134 @@
+// Module included in the following assemblies:
+//
+// * networking/advanced_networking/bgp_routing/no-overlay-mode-bgp-routing.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="nw-no-overlay-enable-cudn_{context}"]
+= Create a ClusterUserDefinedNetwork that uses underlay routing
+
+[role="_abstract"]
+Create a layer-3 `ClusterUserDefinedNetwork` custom resource (CR) with no-overlay transport so pods use BGP routes instead of encapsulation for east-west traffic. You can use managed routing (full-mesh BGP between cluster nodes only, no external BGP routers) or unmanaged routing (advertise pod subnets to external BGP infrastructure).
+
+.Prerequisites
+* You have cluster-admin privileges.
+* Your cluster is installed on bare-metal infrastructure with single-node zone interconnect mode.
+* You enabled BGP routing support for the cluster.
+* You deployed FRR-K8s on cluster nodes.
+
+.Procedure
+. Create a `ClusterUserDefinedNetwork` CR that uses no-overlay transport.
++
+[NOTE]
+====
+For a primary layer-3 `ClusterUserDefinedNetwork`, every namespace that matches `spec.namespaceSelector` must include the `k8s.ovn.org/primary-user-defined-network` label before workloads can use the network; that label can only be set when the namespace is created.
+====
++
+[NOTE]
+====
+For a primary layer-3 `ClusterUserDefinedNetwork`, every namespace that matches `spec.namespaceSelector` must include the `k8s.ovn.org/primary-user-defined-network` label before workloads can use the network; that label can only be set when the namespace is created.
+====
++
+* For managed routing (intra-cluster traffic only, no external BGP routers), set `routing: "Managed"`. You do not need to create a `RouteAdvertisements` CR; skip the steps that follow for RouteAdvertisements.
+* For unmanaged routing (advertise pod subnets to external BGP), set `routing: "Unmanaged"` and create a `RouteAdvertisements` CR in a later step.
++
+.Example `ClusterUserDefinedNetwork` CR for no-overlay mode with managed routing (no external BGP)
+[source,yaml]
+----
+apiVersion: k8s.ovn.org/v1
+kind: ClusterUserDefinedNetwork
+metadata:
+  name: high-perf-network
+spec:
+  namespaceSelector:
+    matchLabels:
+      app: performance-sensitive
+  network:
+    topology: Layer3
+    layer3:
+      role: Primary
+      mtu: 1500
+      subnets:
+      - cidr: 10.200.0.0/16
+        hostSubnet: 24
+    transport: "NoOverlay"
+    noOverlayOptions:
+      outboundSNAT: "Enabled"
+      routing: "Managed"
+----
++
+.Example `ClusterUserDefinedNetwork` CR for no-overlay mode with unmanaged routing
+[source,yaml]
+----
+apiVersion: k8s.ovn.org/v1
+kind: ClusterUserDefinedNetwork
+metadata:
+  name: high-perf-network
+  labels:
+    network: high-perf-network
+spec:
+  namespaceSelector:
+    matchLabels:
+      app: performance-sensitive
+  network:
+    topology: Layer3
+    layer3:
+      role: Primary
+      mtu: 1500
+      subnets:
+      - cidr: 10.200.0.0/16
+        hostSubnet: 24
+    transport: "NoOverlay"
+    noOverlayOptions:
+      outboundSNAT: "Disabled"
+      routing: "Unmanaged"
+----
+
+. Apply the `ClusterUserDefinedNetwork` CR by entering the following command:
++
+[source,terminal]
+----
+$ oc apply -f <cudn_file>.yaml
+----
++
+Replace `<cudn_file>.yaml` with the name of your `ClusterUserDefinedNetwork` CR file.
+
+. If you use unmanaged routing, create a `RouteAdvertisements` CR to advertise the CUDN pod subnets to your external BGP infrastructure:
++
+.Example `RouteAdvertisements` CR for a CUDN
+[source,yaml]
+----
+apiVersion: k8s.ovn.org/v1
+kind: RouteAdvertisements
+metadata:
+  name: high-perf-network
+spec:
+  nodeSelector: {}
+  frrConfigurationSelector:
+    matchLabels:
+      network: high-perf-network
+  networkSelectors:
+  - networkSelectionType: ClusterUserDefinedNetworks
+    clusterUserDefinedNetworkSelector:
+      networkSelector:
+        matchLabels:
+          network: high-perf-network
+  advertisements:
+  - PodNetwork
+----
+
+. Apply the `RouteAdvertisements` CR by entering the following command:
++
+[source,terminal]
+----
+$ oc apply -f <routeadvertisements_file>.yaml
+----
++
+Replace `<routeadvertisements_file>.yaml` with the name of your `RouteAdvertisements` CR file.
+
+. Verify that the no-overlay transport was accepted by entering the following command:
++
+[source,terminal]
+----
+$ oc get clusteruserdefinednetwork high-perf-network -o yaml
+----
+