Skip to content

Commit 0854c94

Browse files
kalexand-rhkalexand-rh
authored
Merge pull request #81383 from JoeAldinger/OSDOCS-11661-tp
OSDOCS-11661:UDN TP docs for 4.17
2 parents 35cb392 + 5ab7314 commit 0854c94

File tree

6 files changed

+281
-0
lines changed

6 files changed

+281
-0
lines changed

‎_topic_maps/_topic_map.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1456,6 +1456,8 @@ Topics:
14561456
Topics:
14571457
- Name: Understanding multiple networks
14581458
File: understanding-multiple-networks
1459+
- Name: Understanding user defined networks
1460+
File: understanding-user-defined-network
14591461
- Name: Configuring an additional network
14601462
File: configuring-additional-network
14611463
- Name: About virtual routing and forwarding

‎modules/nw-udn-best-practices.adoc‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
//module included in the following assembly:
2+
//
3+
// *networkking/multiple_networks/understanding-user-defined-networks.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="considerations-for-udn_{context}"]
7+
= Best practices for UserDefinedNetwork
8+
9+
Before setting up a `UserDefinedNetwork` (UDN) resource, users should consider the following information:
10+
11+
//These will not go live till 4.18 GA
12+
//* To eliminate errors and ensure connectivity, you should create a namespace scoped UDN CR before creating any workload in the namespace.
13+
14+
//* You might want to allow access to any Kubernetes services on the cluster default network. By default, KAPI and DNS are accessible.
15+
16+
* `openshift-*` namespaces should not be used to set up a UDN.
17+
18+
* 2 masquerade IPs are required for user defined networks. You must reconfigure your masquerade subnet to be large enough to hold the required number of networks. For {product-title} 4.17 and later versions, clusters use `169.254.0.0/17` for IPv4 and `fd69::/112` for IPv6 as the default masquerade subnet. These ranges should also be avoided by users. For upgraded clusters, there is no change to the default masquerade subnet.
19+
// May be something that is downstream only.
20+
//* No active primary UDN managed pod can also be a candidate for `v1.multus-cni.io/default-network`
21+
22+
* Ensure tenants are using the `UserDefinedNetwork` resource and not the `NetworkAttachmentDefinition` (NAD) resource. This can create security risks between tenants.
23+
24+
* When creating network segmentation, you should only use the NAD resource if user-defined network segmentation cannot be completed using the UDN resource.
25+
26+
* 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.
27+
+
28+
[IMPORTANT]
29+
====
30+
For {product-title} 4.17 and later versions, clusters use `169.254.0.0/17` for IPv4 and `fd69::/112` for IPv6 as the default masquerade subnet. These ranges should also be avoided by users. For upgraded clusters, there is no change to the default masquerade subnet.
31+
====
32+
33+
* When setting up primary networks, you might consider reviewing the support matrix for creating primary networks using the UDN resource and Network Attachment Definition (NAD). For more information on feature support, see the "Support matrix".

‎modules/nw-udn-cr.adoc‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
//module included in the following assembly:
2+
//
3+
// *networking/multiple_networks/understanding-user-defined-networks.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="nw-udn-cr_{context}"]
7+
= Creating a UserDefinedNetwork custom resource
8+
9+
The following procedure sets up a user-defined network that is namespace scoped.
10+
11+
//We won't have these pieces till GA in 4.18.
12+
//[NOTE]
13+
//====
14+
//If any cluster default networked pods exist before the user-defined network is created, any further pods created in this namespace will return an error message: `What_is_this`.
15+
//====
16+
17+
.Procedure
18+
19+
. Create a request for a user-defined network:
20+
21+
.. Create a YAML file, such as `my-udn-request.yaml`, to define your request with content as in the following example:
22+
+
23+
[source, yaml]
24+
----
25+
apiVersion: k8s.ovn.org/v1
26+
kind: UserDefinedNetwork
27+
metadata:
28+
name: udn-1 # <1>
29+
namespace: <some_custom_namespace>
30+
spec:
31+
topology: Layer2 # <2>
32+
layer2: <3>
33+
role: Primary # <4>
34+
mtu: 9000 # <5>
35+
subnets:
36+
- "10.0.0.0/24"
37+
- "2001:db8::/64" # <6>
38+
JoinSubnets: [] # <7>
39+
IPAMLifecycle: Persistent # <8>
40+
----
41+
<1> Name of your `UserDefinedNetwork` resource. This should not be `default` or duplicate any global namespaces created by the Cluster Network Operator (CNO).
42+
<2> The `topology` field describes the network configuration, accepted values are `Layer2` and `Layer3`. `Layer3` topology creates a layer 2 segment per node, each with a different subnet. Layer 3 routing is used to interconnect node subnets. `Layer2` topology creates one logical switch shared by all nodes.
43+
<3> This field specifies the topology configuration, it can be `layer2` or `layer3`.
44+
<4> Specifies `Primary` or `Secondary`. `Primary` is the only `role` specification supported in {product-version}.
45+
<5> The maximum transmission units (MTU) is an optional field. The default value is `1400`. The boundary for IPv4 is 574, and for IPv6 it is 1280.
46+
<6> Specifies the subnet to be used for the network across the cluster. Supports both IPv6 and dual-stack. For example, `192.168.100.0/24`,`2001:DBB::/64`. Dual-stack may set two subnets otherwise only one is allowed. When the `topology` field is set to `Layer3`, the subnet is split into smaller subnets for every node. Accepted format for subnets when `Layer3` is set are: `172.16.0.0/16/24`. For `Layer2` values in `topology` field, standard CIDR ranges are accepted. If omitted the network only provides `Layer2` communication and you must configure IP addresses.
47+
<7> Specifies the `subnets` used inside the OVN-Kubernetes network topology. If omitted, the OVN-Kubernetes network plugin assigns one, which is subject to change over time.
48+
<8> Specifies the IP address management system (IPAM). This field is optional and allowed when `topology` is `layer2`. The
49+
`subnets` field must be specified when this field is specified. The `Persistent` value specifies that workloads have persistent IP addresses. Assigned by the container network interface (CNI) and used by OVN-Kubernetes to program pod IP addresses. You must not change this for pod annotations.
50+
51+
.. Apply your request by running the following command:
52+
+
53+
[source,terminal]
54+
----
55+
$ oc apply -f my-udn-request.yaml
56+
----
57+
58+
. Verify that your request is successful by running the following command:
59+
+
60+
[source, terminal]
61+
----
62+
$ oc get userdefinednetworks udn-1 -n default -o yaml
63+
----
64+
+
65+
.Example output
66+
[source,terminal]
67+
----
68+
apiVersion: k8s.ovn.org/v1
69+
kind: UserDefinedNetwork
70+
metadata:
71+
creationTimestamp: "2024-08-28T17:18:47Z"
72+
finalizers:
73+
- k8s.ovn.org/user-defined-network-protection
74+
generation: 1
75+
name: udn-1
76+
namespace: some-custom-namespace
77+
resourceVersion: "53313"
78+
uid: f483626d-6846-48a1-b88e-6bbeb8bcde8c
79+
spec:
80+
layer2:
81+
mtu: 9000
82+
role: Primary
83+
subnets:
84+
- 10.0.0.0/24
85+
topology: Layer2
86+
status:
87+
conditions:
88+
- lastTransitionTime: "2024-08-28T17:18:47Z"
89+
message: NetworkAttachmentDefinition has been created
90+
reason: NetworkAttachmentDefinitionReady
91+
status: "True"
92+
type: NetworkReady
93+
----
94+

‎modules/nw-udn-examples.adoc‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
//module included in the following assembly:
2+
//
3+
// *networking/multiple_networks/understanding-user-defined-networks.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="nw-udn-examples_{context}"]
7+
= Configuration details and examples of UserDefinedNetworks
8+
9+
The following sections includes configuration details and examples for creating user-defined networks (UDN) using the custom resource definition.
10+
11+
[id=configuration-details-layer-two_{context}]
12+
== Configuration details for Layer2 topology
13+
The following rules apply when creating a UDN with a `Layer2` topology:
14+
15+
* The `subnets` field is optional.
16+
* The `subnets` field is of type `string` and accepts standard CIDR formats for both IPv4 and IPv6.
17+
* The `subnets` field accepts one or two items. For two items, they must be of a different family. For example, `subnets` values of `10.100.0.0/16` and `2001:db8::/64`.
18+
* `Layer2` subnets may be omitted. If omitted, users must configure IP addresses for the pods. As a consequence, port security only prevents MAC spoofing.
19+
* The `Layer2` `subnets` field is mandatory when `ipamLifecycle` is specified.
20+
21+
.Example of UDN over `Layer2` topology
22+
[%collapsible]
23+
====
24+
[source,terminal]
25+
----
26+
apiVersion: k8s.ovn.org/v1
27+
kind: UserDefinedNetwork
28+
metadata:
29+
name: udn-network-primary
30+
namespace: <example_namespace2>
31+
spec:
32+
topology: Layer2
33+
layer2:
34+
role: Primary
35+
subnets: ["10.150.0.0/16"]
36+
----
37+
====
38+
39+
[id=configuration-details-layer-three_{context}]
40+
== Configuration details for Layer3 topology
41+
The following rules apply when creating a UDN with a `Layer3` topology:
42+
43+
* The `subnets` field is mandatory.
44+
* The type for `subnets` field is `cidr` and `hostsubnet`:
45+
+
46+
** `cidr` is the cluster subnet and accepts a string value.
47+
** `hostSubnet` specifies the nodes subnet prefix that the cluster subnet is split to.
48+
49+
.Example of UDN over `Layer3` topology
50+
[%collapsible]
51+
====
52+
[source,terminal]
53+
----
54+
apiVersion: k8s.ovn.org/v1
55+
kind: UserDefinedNetwork
56+
metadata:
57+
name: udn-network-primary
58+
namespace: <example_namespace>
59+
spec:
60+
topology: Layer3
61+
layer3:
62+
role: Primary
63+
subnets:
64+
- cidr: 10.150.0.0/16
65+
hostsubnet: 24
66+
----
67+
====

‎modules/nw-udn-limitations.adoc‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
//module included in the following assembly:
2+
//
3+
// *networkking/multiple_networks/understanding-user-defined-networks.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="limitations-for-udn_{context}"]
7+
= Limitations for UserDefinedNetwork custom resource
8+
9+
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.
10+
11+
//Check on the removal of the DNS limitation for 4.18 or 4.17.z.
12+
* *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.
13+
14+
* *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.
15+
16+
//Check in 4.18 or 4.17.z for this capability.
17+
//* *Service reachability*: Services created in namespaces that are served by the UDN are only accessible by namespaces connected to the UDN. Services in a UDN are reachable by other namespaces that share the same network. This can limit the flexibility of services across different networks.
18+
19+
* *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.
20+
21+
* *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.

‎networking/multiple_networks/understanding-user-defined-network.adoc‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="understanding-user-defined-networks"]
3+
= Understanding user-defined networks
4+
include::_attributes/common-attributes.adoc[]
5+
:context: understanding-user-defined-networks
6+
7+
toc::[]
8+
9+
:featurename: {`UserDefinedNetwork`}
10+
include::snippets/technology-preview.adoc[]
11+
12+
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.
13+
14+
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.
15+
16+
User-defined networks provide the following benefits:
17+
18+
. Enhanced network isolation
19+
+
20+
* **Tenant isolation**: Namespaces can have their own isolated primary network, similar to how tenants are isolated in {rh-openstack-first}. This improves security by reducing the risk of cross-tenant traffic.
21+
22+
. Network flexibility
23+
+
24+
* **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.
25+
26+
. Simplified network management
27+
+
28+
* **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.
29+
30+
. Advanced capabilities
31+
+
32+
* **Consistent and selectable IP addressing**: Users can specify and reuse IP subnets across different namespaces and clusters, providing a consistent networking environment.
33+
+
34+
* **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.
35+
36+
. Simplification of application migration from {rh-openstack-first}
37+
+
38+
* **Network parity**: With user-defined networking, the migration of applications from OpenStack to {product-title} is simplified by providing similar network isolation and configuration options.
39+
40+
// Looks like this may be out for 4.17, but in for 4.18 as of 8/19/24
41+
//. Ingress and egress support
42+
//+
43+
//* **Support for ingress and egress traffic**: Cluster ingress and egress traffic is supported for both primary and secondary networks.
44+
//* **Support for ingress and egress features**: User-defined networks support support the following ingress and egress features:
45+
//+
46+
//** EgressQoS
47+
//** EgressService
48+
//** EgressIP
49+
//** Load balancer and NodePort services, as well as services with external IPs.
50+
51+
//Limitations that users should consider for UDN.
52+
include::modules/nw-udn-limitations.adoc[leveloffset=+1]
53+
54+
//Best practices for using UDN.
55+
include::modules/nw-udn-best-practices.adoc[leveloffset=+1]
56+
57+
//How to implement the UDN API on a cluster.
58+
include::modules/nw-udn-cr.adoc[leveloffset=+1]
59+
60+
//Support matrix for UDN
61+
//include::modules
62+
63+
//Examples for Layer2 and Layer3
64+
include::modules/nw-udn-examples.adoc[leveloffset=+2]

0 commit comments

Comments
 (0)