Merge pull request #93001 from JoeAldinger/OSDOCS-14169

OSDOCS-14169:CUDN localnet

Author: JoeAldinger

modules/nw-cudn-cr.adoc

@@ -28,7 +28,7 @@ $ cat << EOF | oc apply -f -
 apiVersion: v1
 kind: Namespace
 metadata:
-  name: <cudn_namespace_name>      
+  name: <cudn_namespace_name>
   labels:
     k8s.ovn.org/primary-user-defined-network: ""
 EOF
@@ -59,7 +59,7 @@ spec:
 ----
 <1> Name of your `ClusterUserDefinedNetwork` CR.
 <2> A label query over the set of namespaces that the cluster UDN CR applies to. Uses the standard Kubernetes `MatchLabel` selector. Must not point to `default` or `openshift-*` namespaces.
-<3> Uses the `matchLabels` selector type, where terms are evaluated with an `AND` relationship. 
+<3> Uses the `matchLabels` selector type, where terms are evaluated with an `AND` relationship.
 <4> Because the `matchLabels` selector type is used, provisions namespaces that contain both `<label_1_key>=<label_1_value>` and `<label_2_key>=<label_2_value>` labels.
 <5> Describes the network configuration.
 <6> The `topology` field describes the network configuration; accepted values are `Layer2` and `Layer3`. Specifying a `Layer2` topology type creates one logical switch that is shared by all nodes.
@@ -96,7 +96,7 @@ spec:
 ----
 <1> Name of your `ClusterUserDefinedNetwork` CR.
 <2> A label query over the set of namespaces that the cluster UDN applies to. Uses the standard Kubernetes `MatchLabel` selector. Must not point to `default` or `openshift-*` namespaces.
-<3> Uses the `matchExpressions` selector type, where terms are evaluated with an `OR` relationship. 
+<3> Uses the `matchExpressions` selector type, where terms are evaluated with an `OR` relationship.
 <4> Specifies the label key to match.
 <5> Specifies the operator. Valid values include: `In`, `NotIn`, `Exists`, and `DoesNotExist`.
 <6> Because the `matchExpressions` type is used, provisions namespaces matching either `<example_namespace_one>` or `<example_namespace_two>`.

modules/nw-cudn-localnet.adoc

@@ -0,0 +1,114 @@
+//module included in the following assembly:
+//
+// * networking/multiple_networks/primary_networks/about-user-defined-networks.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="nw-cudn-localnet_{context}"]
+= Creating a ClusterUserDefinedNetwork CR for a Localnet topology
+
+A `Localnet` topology connects the secondary network to the physical underlay. This enables both east-west cluster traffic and access to services running outside the cluster. This topology type requires the additional configuration of the underlying Open vSwitch (OVS) system on cluster nodes.
+
+.Prerequisites
+
+* You are logged in as a user with `cluster-admin` privileges.
+
+* You created and configured the Open vSwitch (OVS) bridge mapping to associate the logical OVN-Kubernetes network with the physical node network through the OVS bridge. For more information, see "Configuration for a localnet switched topology".
+
+.Procedure
+
+. Create a cluster-wide user-defined network with a `Localnet` topology:
+
+.. Create a YAML file, such as `cluster-udn-localnet.yaml`, to define your request for a `Localnet` topology as in the following example:
++
+[source, yaml]
+----
+apiVersion: k8s.ovn.org/v1
+kind: ClusterUserDefinedNetwork
+metadata:
+  name: <cudn_name> # <1>
+spec:
+  namespaceSelector: # <2>
+    matchLabels: # <3>
+      "<label_1_key>": "<label_1_value>" # <4>
+      "<label_2_key>": "<label_2_value>" # <4>
+  network: # <5>
+    topology: Localnet # <6>
+    localnet: # <7>
+      role: Secondary # <8>
+      physicalNetworkName: test
+      ipam: {lifecycle: Persistent}
+      subnets: ["192.168.0.0/16", "2001:dbb::/64"] # <9>
+----
+<1> Name of your `ClusterUserDefinedNetwork` (CUDN) CR.
+<2> A label query over the set of namespaces that the cluster CUDN CR applies to. Uses the standard Kubernetes `MatchLabel` selector. Must not point to `default`, `openshift-*`, or any other system namespaces.
+<3> Uses the `matchLabels` selector type, where terms are evaluated with an `AND` relationship.
+<4> In this example, the CUDN CR is deployed to namespaces that contain both `<label_1_key>=<label_1_value>` and `<label_2_key>=<label_2_value>` labels.
+<5> Describes the network configuration.
+<6> Specifying a `Localnet` topology type creates one logical switch that is directly bridged to one provider network.
+<7> This field specifies the `localnet` topology.
+<8> Specifies the `role` for the network configuration. `Secondary` is the only `role` specification supported for the `localnet` topology.
+<9> For `Localnet` topology types the following specifies config details for the `subnet` field:
++
+* The subnets field is optional.
+* The subnets field is of type `string` and accepts standard CIDR formats for both IPv4 and IPv6.
+* The subnets field accepts one or two items. For two items, they must be of a different IP family. For example, subnets values of `10.100.0.0/16` and `2001:db8::/64`.
+* `localnet` subnets can be omitted. If omitted, users must configure static IP addresses for the pods. As a consequence, port security only prevents MAC spoofing. For more information, see "Configuring pods with a static IP address".
+
+. Apply your request by running the following command:
++
+[source,terminal]
+----
+$ oc create --validate=true -f <example_cluster_udn>.yaml
+----
+where:
+`<example_cluster_udn>.yaml`:: Is the name of your `Localnet` configuration file.
+
+. Verify that your request is successful by running the following command:
++
+[source,terminal]
+----
+$ oc get clusteruserdefinednetwork <cudn_name> -o yaml
+----
+where:
+`<cudn_name>`:: Is the name you created of your cluster-wide user-defined network.
+
+.Example output
+[%collapsible]
+====
+[source,yaml]
+----
+apiVersion: k8s.ovn.org/v1
+kind: ClusterUserDefinedNetwork
+metadata:
+  creationTimestamp: "2025-05-28T19:30:38Z"
+  finalizers:
+  - k8s.ovn.org/user-defined-network-protection
+  generation: 1
+  name: cudn-test
+  resourceVersion: "140936"
+  uid: 7ff185fa-d852-4196-858a-8903b58f6890
+spec:
+  namespaceSelector:
+    matchLabels:
+      "1": "1"
+      "2": "2"
+  network:
+    localnet:
+      ipam:
+        lifecycle: Persistent
+      physicalNetworkName: test
+      role: Secondary
+      subnets:
+      - 192.168.0.0/16
+      - 2001:dbb::/64
+    topology: Localnet
+status:
+  conditions:
+  - lastTransitionTime: "2025-05-28T19:30:38Z"
+    message: 'NetworkAttachmentDefinition has been created in following namespaces:
+      [test1, test2]'
+    reason: NetworkAttachmentDefinitionCreated
+    status: "True"
+    type: NetworkCreated
+----
+====

modules/nw-udn-additional-config-details.adoc

@@ -21,6 +21,13 @@ The following table explains additional configurations for `ClusterUserDefinedNe
 
 The `joinSubnets` field configures the routing between different segments within a user-defined network. Dual-stack clusters can set 2 subnets, one for each IP family; otherwise, only 1 subnet is allowed. This field is only allowed for the `Primary` network.
 
+|`spec.network.<topology>.excludeSubnets`
+|`spec.<topology>.exlcudeSubnets`
+|string
+|Specifies a list of CIDRs to be removed from the specified CIDRs in the `subnets` field. The CIDRs in this list must be in range of at least one subnet specified in `subnets`. When omitted, no IP addresses are excluded, and all IP addresses specified in the `subnets` field are subject to assignment. You must use standard CIDR notation. For example, `10.128.0.0/16`. This field must be omitted if the `subnets` field is not set or if the `ipam.mode` field is set to `Disabled`.
+
+When deploying a secondary network with `Localnet` topology, the IP ranges used in your physical network must be explicitly listed in the `excludeSubnets` field to prevent IP duplication in your subnet.
+
 |`spec.network.<topology>.ipam.lifecycle`
 |`spec.<topology>.ipam.lifecycle`
 |object
@@ -29,7 +36,7 @@ The `joinSubnets` field configures the routing between different segments within
 Setting a value of Persistent is only supported when `ipam.mode` parameter is set to `Enabled`.
 
 |`spec.network.<topology>.ipam.mode`
-|`spec.network.<topology>.ipam.mode`
+|`spec.<topology>`ipam.mode`
 |object
 |The `mode` parameter controls how much of the IP configuration is managed by OVN-Kubernetes. The following options are available:
 
@@ -43,8 +50,25 @@ When disabled, OVN-Kubernetes only assigns MAC addresses and provides layer 2 co
 |`spec.<topology>.mtu`
 |integer
 |The maximum transmission units (MTU). The default value is `1400`. The boundary for IPv4 is `576`, and for IPv6 it is `1280`.
+
+|`spec.network.localnet.vlan`
+|N/A
+|object
+|This field is optional and configures the virtual local area network (VLAN) tagging and allows you to segment the physical network into multiple independent broadcast domains.
+
+|`spec.network.localnet.vlan.mode`
+|N/A
+|object
+|Acceptable values are `Access`. A value of `Access` specifies that the network interface belongs to a single VLAN and all traffic will be labelled with an `id` that is configured in the `spec.network.localnet.vlan.mode.access.id` field. The `id` specifies the VLAN `id` (VID) for access ports. Values must be an integer between 1 and 4094.
+
+|`spec.network.localnet.physicalNetworkName`
+|N/A
+|string
+|Specifies the name for a physical network interface. The value you specify must match the `network-name` parameter that you provided in your Open vSwitch (OVS) bridge mapping.
 |====
 
 where:
 
-`<topology>`:: Is one of `layer2` or `layer3`.
+`<topology>`:: Can be either `layer2` or `layer3` for the `UserDefinedNetwork` CR. For the `ClusterUserDefinedNetwork` CR the topology can also be `Localnet`.
+
+

modules/support-matrix-for-udn-nad.adoc

@@ -12,7 +12,7 @@ User-defined networks and network attachment definitions can serve as both the p
 
 [NOTE]
 ====
-As of {product-title} 4.18, the Localnet topology is unavailable for use with the `UserDefinedNetwork` and `ClusterUserDefinedNetwork` CRs. It is only available for `NetworkAttachmentDefinition` CRs that leverage secondary networks.
+As of {product-title} 4.19, the `Localnet` topology is generally available for the `ClusterUserDefinedNetwork` CRs and is the preferred method for connecting physical networks to virtual networks. Alternatively, the `NetworkAttachmentDefinition` CR can also be used to create secondary networks with `Localnet` topologies.
 ====
 
 The following section highlights the supported features of the `UserDefinedNetwork` and `NetworkAttachmentDefinition` CRs when they are used as either the primary or secondary network. A separate table for the `ClusterUserDefinedNetwork` CR is also included.
@@ -116,45 +116,54 @@ The following section highlights the supported features of the `UserDefinedNetwo
 1. The Localnet topology is unavailable for use with the `UserDefinedNetwork` CR. It is only supported on secondary networks for `NetworkAttachmentDefinition` CRs.
 
 .Support matrix for `ClusterUserDefinedNetwork` CRs
-[cols="1a,1a,1a, options="header"]
+[cols="1a,1a,1a,1a, options="header"]
 |===
-^| Network feature ^| Layer2 topology ^|Layer3 topology
+^| Network feature ^| Layer2 topology ^|Layer3 topology ^|Localnet topology
 
 ^| east-west traffic
 ^| ✓
 ^| ✓
+^| ✓
 
 ^| north-south traffic
 ^| ✓
 ^| ✓
+^| ✓
 
 ^| Persistent IPs
 ^| ✓
 ^| X
+^| ✓
 
 ^| Services
 ^| ✓
 ^| ✓
+^|
 
 ^| Routes
 ^| X
 ^| X
+^|
 
 ^| `EgressIP` resource
 ^| ✓
 ^| ✓
+^|
 
 ^| Multicast ^[1]^
 ^| X
 ^| ✓
+^|
 
 ^| `MultinetworkPolicy` resource
 ^| X
 ^| X
+^| ✓
 
 ^| `NetworkPolicy` resource ^[2]^
 ^| ✓
 ^| ✓
+^|
 
 |===
 1. Multicast must be enabled in the namespace, and it is only available between OVN-Kubernetes network pods. For more information, see "About multicast".

networking/multiple_networks/primary_networks/about-user-defined-networks.adoc

@@ -34,6 +34,13 @@ include::modules/nw-cudn-best-practices.adoc[leveloffset=+2]
 //How to implement the CUDN API on a cluster by using the CLI.
 include::modules/nw-cudn-cr.adoc[leveloffset=+2]
 
+//How to implement the CUDN API for localnet using the CLI.
+include::modules/nw-cudn-localnet.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../../../networking/multiple_networks/secondary_networks/creating-secondary-nwt-ovnk#configuration-localnet-switched-topology_configuring-additional-network-ovnk[Configuration for a localnet switched topology]
+
 //How to implement the CUDN API on a cluster by using the UI.
 include::modules/nw-cudn-cr-ui.adoc[leveloffset=+2]
 
@@ -65,12 +72,3 @@ include::modules/cudn-status-conditions.adoc[leveloffset=+1]
 
 include::modules/opening-default-network-ports-udn.adoc[leveloffset=+1]
 
-//Support matrix for UDN
-//include::modules
-
-//Examples for Layer2 and Layer3
-//include::modules/nw-udn-examples.adoc[leveloffset=+2]
-
-//[role="_additional-resources"]
-//== Additional resources
-// * xr3f../virtual docs that point to live migration of vms for 4.18's GA.