Merge pull request #86845 from stevsmit/udn-namespace-ocpbugs-48218

Updates UDN docs to include required NS label

Author: stevsmit

modules/nw-udn-benefits.adoc

@@ -29,4 +29,8 @@ User-defined networks provide the following benefits:
 +
 * **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.
 
-Developers and administrators can create a user-defined network that is namespace scoped using the custom resource. An overview of the process is: create a namespace, create and configure the custom resource, create pods in the namespace.
+Developers and administrators can create a user-defined network that is namespace scoped using the custom resource. An overview of the process is as follows:
+
+. An administrator creates a namespace for a user-defined network with the `k8s.ovn.org/primary-user-defined-network` label. 
+. The `UserDefinedNetwork` CR is created by either the cluster administrator or the user.
+. The user creates pods in the namespace.

modules/nw-udn-best-practices.adoc

@@ -6,7 +6,7 @@
 [id="considerations-for-udn_{context}"]
 = Best practices for UserDefinedNetwork
 
-Before setting up a `UserDefinedNetwork` (UDN) resource, users should consider the following information:
+Before setting up a `UserDefinedNetwork` (UDN) resource, you should consider the following information:
 
 //These will not go live till 4.18 GA
 //* To eliminate errors and ensure connectivity, you should create a namespace scoped UDN CR before creating any workload in the namespace.
@@ -15,6 +15,18 @@ Before setting up a `UserDefinedNetwork` (UDN) resource, users should consider t
 
 * `openshift-*` namespaces should not be used to set up a UDN.
 
+* `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.
+
+* 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:
+
+** 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 UDN CR is created that matches the namespace, the UDN 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 UDN already exists, a pod in the namespace is created and attached to the default network.
+
+** 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.
+
 * 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.
 +
 [IMPORTANT]
@@ -29,5 +41,4 @@ Before setting up a `UserDefinedNetwork` (UDN) resource, users should consider t
 
 * 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 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 networ, you must override it by setting the `joinSubnets` field. For more information, see "Additional configuration details for a UserDefinedNetworks CR".

modules/nw-udn-cr.adoc

@@ -16,6 +16,20 @@ The following procedure creates a user-defined network that is namespace scoped.
 
 .Procedure
 
+. Optional: For a `UserDefinedNetwork` 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: <udn_namespace_name>      
+  labels:
+    k8s.ovn.org/primary-user-defined-network: ""
+EOF
+----
+
 . 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:
@@ -123,5 +137,5 @@ status:
     message: NetworkAttachmentDefinition has been created
     reason: NetworkAttachmentDefinitionReady
     status: "True"
-    type: NetworkReady
+    type: NetworkCreated
 ----