From f022801509b3be94efaa584530fbf9adabac4b76 Mon Sep 17 00:00:00 2001 From: JoeAldinger Date: Wed, 23 Apr 2025 14:59:49 -0400 Subject: [PATCH] OSDOCS-14169:CUDN localnet updates the matchLabels adds Trunk --- modules/nw-cudn-cr.adoc | 6 +- modules/nw-cudn-localnet.adoc | 114 ++++++++++++++++++ modules/nw-udn-additional-config-details.adoc | 28 ++++- modules/support-matrix-for-udn-nad.adoc | 15 ++- .../about-user-defined-networks.adoc | 16 ++- 5 files changed, 162 insertions(+), 17 deletions(-) create mode 100644 modules/nw-cudn-localnet.adoc diff --git a/modules/nw-cudn-cr.adoc b/modules/nw-cudn-cr.adoc index 9b161e6261fc..8c20a2b5c85d 100644 --- a/modules/nw-cudn-cr.adoc +++ b/modules/nw-cudn-cr.adoc @@ -28,7 +28,7 @@ $ cat << EOF | oc apply -f - apiVersion: v1 kind: Namespace metadata: - name: + 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 `=` and `=` 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 `` or ``. diff --git a/modules/nw-cudn-localnet.adoc b/modules/nw-cudn-localnet.adoc new file mode 100644 index 000000000000..c8c3cdff158e --- /dev/null +++ b/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: # <1> +spec: + namespaceSelector: # <2> + matchLabels: # <3> + "": "" # <4> + "": "" # <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 `=` and `=` 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 .yaml +---- +where: +`.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 -o yaml +---- +where: +``:: 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 +---- +==== diff --git a/modules/nw-udn-additional-config-details.adoc b/modules/nw-udn-additional-config-details.adoc index aa6bda2c1932..0e67cfbb83b4 100644 --- a/modules/nw-udn-additional-config-details.adoc +++ b/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..excludeSubnets` +|`spec..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..ipam.lifecycle` |`spec..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..ipam.mode` -|`spec.network..ipam.mode` +|`spec.`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..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: -``:: Is one of `layer2` or `layer3`. \ No newline at end of file +``:: Can be either `layer2` or `layer3` for the `UserDefinedNetwork` CR. For the `ClusterUserDefinedNetwork` CR the topology can also be `Localnet`. + + diff --git a/modules/support-matrix-for-udn-nad.adoc b/modules/support-matrix-for-udn-nad.adoc index 607e5df87421..61cf6ff0652a 100644 --- a/modules/support-matrix-for-udn-nad.adoc +++ b/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". diff --git a/networking/multiple_networks/primary_networks/about-user-defined-networks.adoc b/networking/multiple_networks/primary_networks/about-user-defined-networks.adoc index ac251ddb88a6..a7654adcd02c 100644 --- a/networking/multiple_networks/primary_networks/about-user-defined-networks.adoc +++ b/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.