apiVersion: k8s.ovn.org/v1
kind: UserDefinedNetwork
metadata:
name: udn-1 (1)
namespace: <some_custom_namespace>
spec:
topology: Layer2 (2)
layer2: (3)
role: Primary (4)
subnets:
- "10.0.0.0/24"
- "2001:db8::/60" (5)
For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope. |
The OVN-Kubernetes CNI plugin supports layer2
, layer3
, and localnet
topologies for secondary pod networks. However, for the primary network, or the main network that all pods are attached to, only a layer3
topology is supported. This allows for network models where all pods in the cluster were part of the same global layer3
network, but restricts the ability to customize primary network configurations.
With user-defined networks, cluster administrators and users are offered highly customizable network configuration options that provide users with the ability to define their own network topologies, ensure network isolation, manage IP addressing for the workloads, and leverage advanced networking features. User-defined networks help enhance networking flexibility, security, and performance.
User-defined networks provide the following benefits:
Enhanced network isolation
Tenant isolation: Namespaces can have their own isolated primary network, similar to how tenants are isolated in Red Hat OpenStack Platform (RHOSP). This improves security by reducing the risk of cross-tenant traffic.
Network flexibility
Layer 2 and layer 3 support: Cluster administrators can configure primary networks as layer 2 or layer 3 network types. This provides the flexibility of a secondary network to the primary network.
Simplified network management
Reduced network configuration complexity: With user-defined networks, the need for complex network policies are eliminated because isolation can be achieved by grouping workloads in different networks.
Advanced capabilities
Consistent and selectable IP addressing: Users can specify and reuse IP subnets across different namespaces and clusters, providing a consistent networking environment.
Support for multiple networks: The user-defined networking feature allows administrators to connect multiple namespaces to a single network, or to create distinct networks for different sets of namespaces.
Simplification of application migration from Red Hat OpenStack Platform (RHOSP)
Network parity: With user-defined networking, the migration of applications from OpenStack to OpenShift Container Platform is simplified by providing similar network isolation and configuration options.
While user-defined networks (UDN) offer highly customizable network configuration options, there are limitations that cluster administrators and developers should be aware of when implementing and managing these networks. Consider the following limitations before implementing a user-defined network.
DNS limitations: DNS lookups for pods resolve to the pod’s IP address on the cluster default network. Even if a pod is part of a user-defined network, DNS lookups will not resolve to the pod’s IP address on that user-defined network.
Initial network assignment: You must create the namespace and network before creating pods. Assigning a namespace with pods to a new network or creating a UDN in an existing namespace will not be accepted by OVN-Kubernetes.
Health check limitations: Kubelet health checks are performed by the cluster default network, which does not confirm the network connectivity of the primary interface on the pod. Consequently, scenarios where a pod appears healthy by the default network, but has broken connectivity on the primary interface, are possible with user-defined networks.
Network policy limitations: Network policies that enable traffic between namespaces connected to different user-defined primary networks are not effective. These traffic policies do not take effect because there is no connectivity between these isolated networks.
Before setting up a UserDefinedNetwork
(UDN) resource, users should consider the following information:
openshift-*
namespaces should not be used to set up a UDN.
2 masquerade IP addresses are required for user defined networks. You must reconfigure your masquerade subnet to be large enough to hold the required number of networks.
For OpenShift Container Platform 4.17 and later, clusters use |
Ensure tenants are using the UserDefinedNetwork
resource and not the NetworkAttachmentDefinition
(NAD) resource. This can create security risks between tenants.
When creating network segmentation, you should only use the NAD resource if user-defined network segmentation cannot be completed using the UDN resource.
The cluster subnet and services CIDR for a UDN cannot overlap with the default cluster subnet CIDR. OVN-Kubernetes network plugin uses 100.64.0.0/16
as the default network’s join subnet, you must not use that value to configure a UDN joinSubnets
field. If the default address values are used anywhere in the cluster’s network you must override it by setting the joinSubnets
field. For more information, see "Additional configuration details for a UserDefinedNetworks CR".
The following procedure creates a user-defined network that is namespace scoped. Based upon your use case, create your request using either the my-layer-two-udn.yaml
example for a Layer2
topology type or the my-layer-three-udn.yaml
example for a Layer3
topology type.
Create a request for either a Layer2
or Layer3
topology type user-defined network:
Create a YAML file, such as my-layer-two-udn.yaml
, to define your request for a Layer2
topology as in the following example:
apiVersion: k8s.ovn.org/v1
kind: UserDefinedNetwork
metadata:
name: udn-1 (1)
namespace: <some_custom_namespace>
spec:
topology: Layer2 (2)
layer2: (3)
role: Primary (4)
subnets:
- "10.0.0.0/24"
- "2001:db8::/60" (5)
1 | Name of your UserDefinedNetwork resource. This should not be default or duplicate any global namespaces created by the Cluster Network Operator (CNO). |
2 | 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. |
3 | This field specifies the topology configuration. It can be layer2 or layer3 . |
4 | Specifies Primary or Secondary . Primary is the only role specification supported in 4.17. |
5 | For Layer2 topology types the following specifies config details for the subnet field:
|
Create a YAML file, such as my-layer-three-udn.yaml
, to define your request for a Layer3
topology as in the following example:
apiVersion: k8s.ovn.org/v1
kind: UserDefinedNetwork
metadata:
name: udn-2-primary (1)
namespace: <some_custom_namespace>
spec:
topology: Layer3 (2)
layer3: (3)
role: Primary (4)
subnets: (5)
- cidr: 10.150.0.0/16
hostSubnet: 24
- cidr: 2001:db8::/60
hostSubnet: 64
1 | Name of your UserDefinedNetwork resource. This should not be default or duplicate any global namespaces created by the Cluster Network Operator (CNO). |
2 | The topology field describes the network configuration; accepted values are Layer2 and Layer3 . Specifying a Layer3 topology type creates a layer 2 segment per node, each with a different subnet. Layer 3 routing is used to interconnect node subnets. |
3 | This field specifies the topology configuration. Valid values are layer2 or layer3 . |
4 | Specifies a Primary or Secondary role. Primary is the only role specification supported in 4.17 . |
5 | For Layer3 topology types the following specifies config details for the subnet field:
|
Apply your request by running the following command:
$ oc apply -f <my_layer_two_udn.yaml>
Where <my_layer_two_udn.yaml>
is the name of your Layer2
or Layer3
configuration file.
Verify that your request is successful by running the following command:
$ oc get userdefinednetworks udn-1 -n <some_custom_namespace> -o yaml
Where some_custom_namespace
is the namespace you created for your user-defined network.
apiVersion: k8s.ovn.org/v1
kind: UserDefinedNetwork
metadata:
creationTimestamp: "2024-08-28T17:18:47Z"
finalizers:
- k8s.ovn.org/user-defined-network-protection
generation: 1
name: udn-1
namespace: some-custom-namespace
resourceVersion: "53313"
uid: f483626d-6846-48a1-b88e-6bbeb8bcde8c
spec:
layer2:
role: Primary
subnets:
- 10.0.0.0/24
- 2001:db8::/60
topology: Layer2
status:
conditions:
- lastTransitionTime: "2024-08-28T17:18:47Z"
message: NetworkAttachmentDefinition has been created
reason: NetworkAttachmentDefinitionReady
status: "True"
type: NetworkReady
The following table explains additional configurations for UDN that are optional. It is not recommended to set these fields without explicit need and understanding of OVN-Kubernetes network topology.
Field | Type | Description |
---|---|---|
|
object |
When omitted, the platform sets default values for the The |
|
object |
The |
|
integer |
The maximum transmission units (MTU). The default value is |