Skip to content

Commit 2959bb1

Browse files
authored
Merge pull request #89000 from stevsmit/udn-cr-updates
Updates a few minor things for 418 GA in UDN docs
2 parents 79dbb7b + 9e5a199 commit 2959bb1

File tree

7 files changed

+25
-32
lines changed

7 files changed

+25
-32
lines changed

modules/nw-cudn-best-practices.adoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,8 @@ Before setting up a `ClusterUserDefinedNetwork` custom resource (CR), users shou
2424
2525
** If the namespace is missing the `k8s.ovn.org/primary-user-defined-network` label and a pod is created, the pod attaches itself to the default network.
2626

27-
** If the namespace is missing the `k8s.ovn.org/primary-user-defined-network` label and a primary `ClusterUserDefinedNetwork` CR is created that matches the namespace, the CUDN reports an error status and the network is not created.
27+
** If the namespace is missing the `k8s.ovn.org/primary-user-defined-network` label and a primary `ClusterUserDefinedNetwork` CR is created that matches the namespace, an error is reported and the network is not created.
2828

29-
** If the namespace is missing the `k8s.ovn.org/primary-user-defined-network` label and a primary `CluserUserDefinedNetwork` CR already exists, a pod in the namespace is created and attached to the default network.
29+
** If the namespace is missing the `k8s.ovn.org/primary-user-defined-network` label and a primary `ClusterUserDefinedNetwork` CR already exists, a pod in the namespace is created and attached to the default network.
3030

3131
** If the namespace _has_ the label, and a primary `ClusterUserDefinedNetwork` CR does not exist, a pod in the namespace is not created until the `ClusterUserDefinedNetwork` CR is created.

modules/nw-cudn-cr.adoc

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,13 @@
44

55
:_mod-docs-content-type: PROCEDURE
66
[id="nw-cudn-cr_{context}"]
7-
= Creating a ClusterUserDefinedNetwork custom resource
7+
= Creating a ClusterUserDefinedNetwork CR
88

9-
The following procedure creates a `ClusterUserDefinedNetwork` custom resource definition (CRD). Based upon your use case, create your request using either the `cluster-layer-two-udn.yaml` example for a `Layer2` topology type or the `cluster-layer-three-udn.yaml` example for a `Layer3` topology type.
9+
The following procedure creates a `ClusterUserDefinedNetwork` custom resource (CR). Based upon your use case, create your request using either the `cluster-layer-two-udn.yaml` example for a `Layer2` topology type or the `cluster-layer-three-udn.yaml` example for a `Layer3` topology type.
1010

1111
[IMPORTANT]
1212
====
13-
* The `ClusterUserDefinedNetwork` CRD is intended for use by cluster administrators and should not be used by non-administrators. If used incorrectly, it might result in security issues with your deployment, cause disruptions, or break the cluster network.
13+
* The `ClusterUserDefinedNetwork` CR is intended for use by cluster administrators and should not be used by non-administrators. If used incorrectly, it might result in security issues with your deployment, cause disruptions, or break the cluster network.
1414
* {VirtProductName} only supports the `Layer2` topology.
1515
====
1616

@@ -57,8 +57,8 @@ spec:
5757
- "2001:db8::/64"
5858
- "10.100.0.0/16" # <9>
5959
----
60-
<1> Name of your `ClusterUserDefinedNetwork` custom resource.
61-
<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.
60+
<1> Name of your `ClusterUserDefinedNetwork` CR.
61+
<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.
6262
<3> Uses the `matchLabels` selector type, where terms are evaluated with an `AND` relationship.
6363
<4> Because the `matchLabels` selector type is used, provisions namespaces matching both `<example_namespace_one>` _and_ `<example_namespace_two>`.
6464
<5> Describes the network configuration.
@@ -94,9 +94,9 @@ spec:
9494
- cidr: 10.100.0.0/16
9595
hostSubnet: 64
9696
----
97-
<1> Name of your `ClusterUserDefinedNetwork` custom resource.
97+
<1> Name of your `ClusterUserDefinedNetwork` CR.
9898
<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.
99-
<3> Uses the `matchExpressions` selector type, where terms are evaluated with an _*OR*_ relationship.
99+
<3> Uses the `matchExpressions` selector type, where terms are evaluated with an `OR` relationship.
100100
<4> Specifies the label key to match.
101101
<5> Specifies the operator. Valid values include: `In`, `NotIn`, `Exists`, and `DoesNotExist`.
102102
<6> Because the `matchExpressions` type is used, provisions namespaces matching either `<example_namespace_one>` or `<example_namespace_two>`.

modules/nw-udn-best-practices.adoc

Lines changed: 10 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,46 +4,44 @@
44

55
:_mod-docs-content-type: CONCEPT
66
[id="considerations-for-udn_{context}"]
7-
= Best practices for UserDefinedNetwork
7+
= Best practices for UserDefinedNetwork CRs
88

9-
Before setting up a `UserDefinedNetwork` (UDN) resource, you should consider the following information:
9+
Before setting up a `UserDefinedNetwork` custom resource (CR), you should consider the following information:
1010

1111
//These will not go live till 4.18 GA
1212
//* To eliminate errors and ensure connectivity, you should create a namespace scoped UDN CR before creating any workload in the namespace.
1313

1414
//* You might want to allow access to any Kubernetes services on the cluster default network. By default, KAPI and DNS are accessible.
1515

16-
* `openshift-*` namespaces should not be used to set up a UDN.
16+
* `openshift-*` namespaces should not be used to set up a `UserDefinedNetwork` CR.
1717
1818
* `UserDefinedNetwork` CRs should not be created in the default namespace. This can result in no isolation and, as a result, could introduce security risks to the cluster.
1919
2020
* For primary networks, the namespace used for the `UserDefinedNetwork` CR must include the `k8s.ovn.org/primary-user-defined-network` label. This label cannot be updated, and can only be added when the namespace is created. The following conditions apply with the `k8s.ovn.org/primary-user-defined-network` namespace label:
2121
2222
** If the namespace is missing the `k8s.ovn.org/primary-user-defined-network` label and a pod is created, the pod attaches itself to the default network.
2323

24-
** If the namespace is missing the `k8s.ovn.org/primary-user-defined-network` label and a primary UDN CR is created that matches the namespace, the UDN reports an error status and the network is not created.
24+
** If the namespace is missing the `k8s.ovn.org/primary-user-defined-network` label and a primary `UserDefinedNetwork` CR is created that matches the namespace, a status error is reported and the network is not created.
2525

26-
** If the namespace is missing the `k8s.ovn.org/primary-user-defined-network` label and a primary UDN already exists, a pod in the namespace is created and attached to the default network.
26+
** If the namespace is missing the `k8s.ovn.org/primary-user-defined-network` label and a primary `UserDefinedNetwork` CR already exists, a pod in the namespace is created and attached to the default network.
2727

28-
** If the namespace _has_ the label, and a primary UDN does not exist, a pod in the namespace is not created until the UDN is created.
28+
** If the namespace _has_ the label, and a primary `UserDefinedNetwork` CR does not exist, a pod in the namespace is not created until the `UserDefinedNetwork` CR is created.
2929

3030
* 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.
3131
+
3232
[IMPORTANT]
3333
====
3434
* For {product-title} 4.17 and later, clusters use `169.254.0.0/17` for IPv4 and `fd69::/112` for IPv6 as the default masquerade subnet. These ranges should be avoided by users. For updated clusters, there is no change to the default masquerade subnet.
35-
* Changing the cluster's masquerade subnet is unsupported after a user-defined network has been configured for a project. Attempting to modify the masquerade subnet after a UDN has been set up can disrupt the network connectivity and cause configuration issues.
35+
* Changing the cluster's masquerade subnet is unsupported after a user-defined network has been configured for a project. Attempting to modify the masquerade subnet after a `UserDefinedNetwork` CR has been set up can disrupt the network connectivity and cause configuration issues.
3636
====
3737
// May be something that is downstream only.
3838
//* No active primary UDN managed pod can also be a candidate for `v1.multus-cni.io/default-network`
3939
40-
* Ensure tenants are using the `UserDefinedNetwork` resource and not the `NetworkAttachmentDefinition` (NAD) resource. This can create security risks between tenants.
40+
* Ensure tenants are using the `UserDefinedNetwork` resource and not the `NetworkAttachmentDefinition` (NAD) CR. This can create security risks between tenants.
4141
42-
* When creating network segmentation, you should only use the NAD resource if user-defined network segmentation cannot be completed using the UDN resource.
42+
* When creating network segmentation, you should only use the `NetworkAttachmentDefinition` CR if user-defined network segmentation cannot be completed using the `UserDefinedNetwork` CR.
4343
44-
* 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 network for the cluster, you must override it by setting the `joinSubnets` field. For more information, see "Additional configuration details for a UserDefinedNetworks CR".
45-
46-
* 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 join subnet for the network, you must not use that value to configure a UDN `joinSubnets` field. If the default address values are used anywhere in the network for the cluster you must override the default values by setting the `joinSubnets` field. For more information, see "Additional configuration details for a UserDefinedNetworks CR".
44+
* The cluster subnet and services CIDR for a `UserDefinedNetwork` CR cannot overlap with the default cluster subnet CIDR. OVN-Kubernetes network plugin uses `100.64.0.0/16` as the default join subnet for the network. You must not use that value to configure a `UserDefinedNetwork` CR's `joinSubnets` field. If the default address values are used anywhere in the network for the cluster you must override the default values by setting the `joinSubnets` field. For more information, see "Additional configuration details for user-defined networks".
4745
4846
* A layer 2 topology creates a virtual switch that is distributed across all nodes in a cluster. Virtual machines and pods connect to this virtual switch so that all these components can communicate with each other within the same subnet. If you decide not to specify a layer 2 subnet, then you must manually configure IP addresses for each pod in your cluster. When not specifying a layer 2 subnet, port security is limited to preventing Media Access Control (MAC) spoofing only, and does not include IP spoofing. A layer 2 topology creates a single broadcast domain that can be challenging in large network environments, whereby the topology might cause a broadcast storm that can degrade network performance.
4947

modules/nw-udn-cr.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
[id="nw-udn-cr_{context}"]
77
= Creating a UserDefinedNetwork custom resource
88

9-
The following procedure creates a user-defined network that is namespace scoped. Based upon your use case, create your request by 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.
9+
The following procedure creates a `UserDefinedNetwork` CR that is namespace scoped. Based upon your use case, create your request by 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.
1010

1111
//We won't have these pieces till GA in 4.18.
1212
//[NOTE]

modules/nw-udn-limitations.adoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@
44

55
:_mod-docs-content-type: CONCEPT
66
[id="limitations-for-udn_{context}"]
7-
= Limitations for UserDefinedNetwork custom resource
7+
= Limitations of a user-defined network
88

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.
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 UDN.
1010

1111
//Check on the removal of the DNS limitation for 4.18 or 4.17.z.
1212
* *DNS limitations*:

modules/opening-default-network-ports-udn.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
[id="opening-default-network-ports-udn_{context}"]
77
= Opening default network ports on user-defined network pods
88

9-
By default, pods on a user-defined network are isolated from the default network. This means that default network pods, such as those running monitoring services (Prometheus or Alertmanager) or the {product-title} image registry, cannot initiate connections to UDN pods.
9+
By default, pods on a user-defined network (UDN) are isolated from the default network. This means that default network pods, such as those running monitoring services (Prometheus or Alertmanager) or the {product-title} image registry, cannot initiate connections to UDN pods.
1010

1111
To allow default network pods to connect to a user-defined network pod, you can use the `k8s.ovn.org/open-default-ports` annotation. This annotation opens specific ports on the user-defined network pod for access from the default network.
1212

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

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -15,18 +15,13 @@ The following diagram shows four cluster namespaces, where each namespace has a
1515

1616
image::527-OpenShift-UDN-isolation-012025.png[The namespace isolation concept in a user-defined network (UDN)]
1717

18-
[NOTE]
19-
====
20-
Support for the Localnet topology on both primary and secondary networks will be added in a future version of {product-title}.
21-
====
22-
2318
A cluster administrator can use a user-defined network to create and define additional networks that span multiple namespaces at the cluster level by leveraging the `ClusterUserDefinedNetwork` custom resource (CR). Additionally, a cluster administrator or a cluster user can use a user-defined network to define additional networks at the namespace level with the `UserDefinedNetwork` CR.
2419

25-
The following diagram shows tenant isolation that a cluster administrator created by defining a `ClusterUserDefinedNetwork` (CR) for each tenant. This network configuration allows a network to span across many namespaces. In the diagram, the `udn-1` disconnected network selects `namespace-1` and `namespace-2`, while the `udn-2` disconnected network selects `namespace-3` and `namespace-4`. A tenant acts as a disconnected network that is isolated from other tenants' networks. Pods from a namespace can communicate with pods in another namespace only if those namespaces exist in the same tenant network.
20+
The following diagram shows tenant isolation that a cluster administrator created by defining a `ClusterUserDefinedNetwork` CR for each tenant. This network configuration allows a network to span across many namespaces. In the diagram, the `udn-1` disconnected network selects `namespace-1` and `namespace-2`, while the `udn-2` disconnected network selects `namespace-3` and `namespace-4`. A tenant acts as a disconnected network that is isolated from other tenants' networks. Pods from a namespace can communicate with pods in another namespace only if those namespaces exist in the same tenant network.
2621

2722
image::528-OpenShift-multitenant-0225.png[The tenant isolation concept in a user-defined network (UDN)]
2823

29-
The following sections further emphasize the benefits and limitations of user-defined networks, the best practices when creating a `ClusterUserDefinedNetwork` or `UserDefinedNetwork` custom resource, how to create the custom resource, and additional configuration details that might be relevant to your deployment.
24+
The following sections further emphasize the benefits and limitations of user-defined networks, the best practices when creating a `ClusterUserDefinedNetwork` or `UserDefinedNetwork` CR, how to create the CR, and additional configuration details that might be relevant to your deployment.
3025

3126
//benefits of UDN
3227
include::modules/nw-udn-benefits.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)