Adds cudn docs

modules/cudn-status-conditions.adoc

@@ -0,0 +1,84 @@
+//module included in the following assembly:
+//
+// * networking/multiple_networks/primary_networks/about-user-defined-networks.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="cudn-status-conditions_{context}"]
+= ClusterUserDefinedNetwork status condition types
+
+The following tables explain the status condition types returned for `ClusterUserDefinedNetwork` CRs when describing the resource. These conditions can be used to troubleshoot your deployment.
+
+//The following table is subject to change and will be updated accordingly.
+
+.NetworkCreated condition types
+[cols="2a,2a,3a,6a",options="header"]
+|===
+
+|Condition type
+|Status
+2+|Reason and Message
+
+.3+|`NetworkCreated`
+.3+| `True`
+2+|When `True`, the following reason and message is returned:
+h|Reason
+h|Message
+
+|`NetworkAttachmentDefinitionCreated`
+|'NetworkAttachmentDefinition has been created in following namespaces: [example-namespace-1, example-namespace-2, example-namespace-3]'`
+
+.9+|`NetworkCreated`
+.9+| `False`
+2+|When `False`, one of the following messages is returned:
+h|Reason
+h|Message
+
+|`SyncError`
+|`failed to generate NetworkAttachmentDefinition`
+
+|`SyncError`
+|`failed to update NetworkAttachmentDefinition`
+
+|`SyncError`
+|`primary network already exist in namespace "<namespace_name>": "<primary_network_name>"`
+
+|`SyncError`
+|`failed to create NetworkAttachmentDefinition: create NAD error`
+
+|`SyncError`
+|`foreign NetworkAttachmentDefinition with the desired name already exist`
+
+|`SyncError`
+|`failed to add finalizer to UserDefinedNetwork`
+
+|`NetworkAttachmentDefinitionDeleted`
+|`NetworkAttachmentDefinition is being deleted: [<namespace>/<nad_name>]`
+|===
+
+.NetworkAllocationSucceeded condition types
+[cols="2a,2a,3a,6a",options="header"]
+|===
+
+|Condition type
+|Status
+2+|Reason and Message
+
+.3+|`NetworkAllocationSucceeded`
+.3+| `True`
+2+|When `True`, the following reason and message is returned:
+h|Reason
+h|Message
+
+|`NetworkAllocationSucceeded`
+|`Network allocation succeeded for all synced nodes.`
+
+.3+|`NetworkAllocationSucceeded`
+.3+| `False`
+2+|When `False`, the following message is returned:
+h|Reason
+h|Message
+
+|`InternalError`
+|`Network allocation failed for at least one node: [<node_name>], check UDN events for more info.`
+
+|===

modules/nw-cudn-best-practices.adoc

@@ -0,0 +1,31 @@
+//module included in the following assembly:
+//
+// * networking/multiple_networks/primary_networks/about-user-defined-networks.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="considerations-for-cudn_{context}"]
+= Best practices for ClusterUserDefinedNetwork CRs
+
+Before setting up a `ClusterUserDefinedNetwork` custom resource (CR), users should consider the following information:
+
+* A `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. 
+
+* `ClusterUserDefinedNetwork` 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.
+
+* `ClusterUserDefinedNetwork` CRs should not target `openshift-*` namespaces.
+
+* {product-title} administrators should be aware that all namespaces of a cluster are selected when one of the following conditions are met:
+
+** The `matchLabels` selector is left empty.
+** The `matchExpressions` selector is left empty.
+** The `namespaceSelector` is initialized, but does not specify `matchExpressions` or `matchLabel`. For example: `namespaceSelector: {}`.
+
+* For primary networks, the namespace used for the `ClusterUserDefinedNetwork` 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:
+
+** 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.
+
+** 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.
+
+** 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.
+
+** 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

@@ -0,0 +1,169 @@
+//module included in the following assembly:
+//
+// * networking/multiple_networks/primary_networks/about-user-defined-networks.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="nw-cudn-cr_{context}"]
+= Creating a ClusterUserDefinedNetwork custom resource
+
+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.
+
+[IMPORTANT]
+====
+* 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.
+* {VirtProductName} only supports the `Layer2` topology.
+====
+
+.Prerequisites
+
+* You have logged in as a user with `cluster-admin` privileges.
+
+.Procedure
+
+. Optional: For a `ClusterUserDefinedNetwork` CR that uses a primary network, create a namespace with the `k8s.ovn.org/primary-user-defined-network` label by entering the following command:
++
+[source,yaml]
+----
+$ cat << EOF | oc apply -f -
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: <cudn_namespace_name>      
+  labels:
+    k8s.ovn.org/primary-user-defined-network: ""
+EOF
+----
+
+. Create a request for either a `Layer2` or `Layer3` topology type cluster-wide user-defined network:
+
+.. Create a YAML file, such as `cluster-layer-two-udn.yaml`, to define your request for a `Layer2` 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>
+    - "<example_namespace_one>":"" # <4>
+    - "<example_namespace_two>":"" # <4>
+  network: # <5>
+    topology: Layer2 # <6>
+    layer2: # <7>
+      role: Primary # <8>
+      subnets:
+        - "2001:db8::/64"
+        - "10.100.0.0/16" # <9>
+----
+<1> Name of your `ClusterUserDefinedNetwork` custom resource.
+<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 `matchLabels` selector type, where terms are evaluated with an `AND` relationship. 
+<4> Because the `matchLabels` selector type is used, provisions namespaces matching both `<example_namespace_one>` _and_ `<example_namespace_two>`.
+<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.
+<7> This field specifies the topology configuration. It can be `layer2` or `layer3`.
+<8> Specifies `Primary` or `Secondary`. `Primary` is the only `role` specification supported in {product-version}.
+<9> For `Layer2` 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 family. For example, subnets values of `10.100.0.0/16` and `2001:db8::/64`.
+* `Layer2` 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".
++
+.. Create a YAML file, such as `cluster-layer-three-udn.yaml`, to define your request for a `Layer3` topology as in the following example:
++
+[source, yaml]
+----
+apiVersion: k8s.ovn.org/v1
+kind: ClusterUserDefinedNetwork
+metadata:
+  name: <cudn_name> # <1>
+spec:
+  namespaceSelector: # <2>
+    matchExpressions: # <3>
+    - key: kubernetes.io/metadata.name # <4>
+      operator: In # <5>
+      values: ["<example_namespace_one>, <example_namespace_two>"] # <6>
+  network: # <7>
+    topology: Layer3 # <8>
+    layer3: # <9>
+      role: Primary # <10>
+      subnets: # <11>
+        - cidr: 10.100.0.0/16
+          hostSubnet: 64
+----
+<1> Name of your `ClusterUserDefinedNetwork` custom resource.
+<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. 
+<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>`.
+<7> Describes the network configuration.
+<8> 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.
+<9> This field specifies the topology configuration. Valid values are `layer2` or `layer3`.
+<10> Specifies a `Primary` or `Secondary` role. `Primary` is the only `role` specification supported in {product-version}.
+<11> For `Layer3` topology types the following specifies config details for the `subnet` field:
++
+* The `subnets` field is mandatory.
+* The type for the `subnets` field is `cidr` and `hostSubnet`:
+** `cidr` is the cluster subnet and accepts a string value.
+** `hostSubnet` specifies the nodes subnet prefix that the cluster subnet is split to.
+** For IPv6, only a `/64` length is supported for `hostSubnet`.
++
+. 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 `Layer2` or `Layer3` 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
+[source,yaml]
+----
+apiVersion: k8s.ovn.org/v1
+kind: ClusterUserDefinedNetwork
+metadata:
+  creationTimestamp: "2024-12-05T15:53:00Z"
+  finalizers:
+  - k8s.ovn.org/user-defined-network-protection
+  generation: 1
+  name: my-cudn
+  resourceVersion: "47985"
+  uid: 16ee0fcf-74d1-4826-a6b7-25c737c1a634
+spec:
+  namespaceSelector:
+    matchExpressions:
+    - key: custom.network.selector
+      operator: In
+      values:
+      - example-namespace-1
+      - example-namespace-2
+      - example-namespace-3
+  network:
+    layer3:
+      role: Primary
+      subnets:
+      - cidr: 10.100.0.0/16
+    topology: Layer3
+status:
+  conditions:
+  - lastTransitionTime: "2024-11-19T16:46:34Z"
+    message: 'NetworkAttachmentDefinition has been created in following namespaces:
+      [example-namespace-1, example-namespace-2, example-namespace-3]'
+    reason: NetworkAttachmentDefinitionReady
+    status: "True"
+    type: NetworkCreated
+----

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

@@ -1,6 +1,6 @@
 //module included in the following assembly:
 //
-// *networking/multiple_networks/understanding-user-defined-networks.adoc
+// * networking/multiple_networks/primary_networks/about-user-defined-networks.adoc
 
 :_mod-docs-content-type: REFERENCE
 [id="nw-udn-additional-config-details_{context}"]

modules/nw-udn-best-practices.adoc

@@ -1,6 +1,6 @@
 //module included in the following assembly:
 //
-// *networkking/multiple_networks/understanding-user-defined-networks.adoc
+// * networking/multiple_networks/primary_networks/about-user-defined-networks.adoc
 
 :_mod-docs-content-type: CONCEPT
 [id="considerations-for-udn_{context}"]

modules/nw-udn-cr.adoc

@@ -1,6 +1,6 @@
 //module included in the following assembly:
 //
-// *networking/multiple_networks/understanding-user-defined-networks.adoc
+// * networking/multiple_networks/primary_networks/about-user-defined-networks.adoc
 
 :_mod-docs-content-type: PROCEDURE
 [id="nw-udn-cr_{context}"]
@@ -11,7 +11,7 @@ The following procedure creates a user-defined network that is namespace scoped.
 //We won't have these pieces till GA in 4.18.
 //[NOTE]
 //====
-//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`.
+//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`?
 //====
 
 .Procedure
@@ -82,10 +82,10 @@ spec:
 +
 [source,terminal]
 ----
-$ oc apply -f <my_layer_two_udn.yaml>
+$ oc apply -f <my_layer_two_udn>.yaml
 ----
 +
-Where `<my_layer_two_udn.yaml>` is the name of your `Layer2` or `Layer3` configuration file.
+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:
 +

modules/nw-udn-examples.adoc

@@ -1,6 +1,6 @@
 //module included in the following assembly:
 //
-// *networking/multiple_networks/understanding-user-defined-networks.adoc
+// * networking/multiple_networks/primary_networks/about-user-defined-networks.adoc
 
 :_mod-docs-content-type: REFERENCE
 [id="nw-udn-examples_{context}"]

modules/nw-udn-limitations.adoc

@@ -1,6 +1,6 @@
 //module included in the following assembly:
 //
-// *networkking/multiple_networks/understanding-user-defined-networks.adoc
+// * networking/multiple_networks/primary_networks/about-user-defined-networks.adoc
 
 :_mod-docs-content-type: CONCEPT
 [id="limitations-for-udn_{context}"]

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

@@ -39,6 +39,19 @@ include::modules/nw-udn-benefits.adoc[leveloffset=+1]
 //Limitations that users should consider for UDN.
 include::modules/nw-udn-limitations.adoc[leveloffset=+1]
 
+//Best practices for using CUDN.
+include::modules/nw-cudn-best-practices.adoc[leveloffset=+1]
+
+//How to implement the CUDN API on a cluster.
+include::modules/nw-cudn-cr.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:../../../networking/multiple_networks/secondary_networks/creating-secondary-nwt-ovnk.adoc#configuring-pods-static-ip_configuring-additional-network-ovnk[Configuring pods with a static IP address]
+
+//CUDN status conditions
+include::modules/cudn-status-conditions.adoc[leveloffset=+2]
+
 //Best practices for using UDN.
 include::modules/nw-udn-best-practices.adoc[leveloffset=+1]