Addresses ocpbugs48423--commit two

Author: Steven Smith

modules/nw-udn-benefits.adoc

@@ -29,4 +29,9 @@ 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. 
+. Optional: An administrator grants a non-administrator user `admin` privileges on the user-defined network namespace.
+. The `UserDefinedNetwork` CR is created
+. The administrator or user with `admin` privileges 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,25 @@ Before setting up a `UserDefinedNetwork` (UDN) resource, users should consider t
 
 * `openshift-*` namespaces should not be used to set up a UDN.
 
+* {product-title} administrators should be aware that empty `matchLabel` selectors results in selecting all namespaces of 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 will not be 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 will be 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 will not be created until the UDN is created.
+
+* If the user-defined network is intended to be used by a non-administrator user, you must grant the `admin` role to the non-administrator user on the user-defined namespace. For example:
++
+[source,terminal]
+----
+$ oc adm policy add-role-to-user admin <non_administrator_username> -n <udn_namespace>
+----
+
 * 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,16 +48,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".
-
-* {product-title} administrators should be aware that empty `matchLabel` selectors results in selecting all namespaces of 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 will not be 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 will be 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 will not be created until the UDN is created.
+* 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".

modules/nw-udn-cr.adoc

@@ -14,11 +14,28 @@ The following procedure creates a user-defined network that is namespace scoped.
 //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`.
 //====
 
-.Prerequisites
+.Procedure
 
-* You have created a namespace with the `k8s.ovn.org/primary-user-defined-network` label.
+. 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
+----
 
-.Procedure
+. Optional: If the user-defined network is intended to be used by a non-administrator user, grant the non-administrator user `admin` permissions on the namespace by entering the following command:
++
+[source,terminal]
+----
+$ oc adm policy add-role-to-user admin <non_administrator_username> -n <udn_namespace>
+----
 
 . Create a request for either a `Layer2` or `Layer3` topology type user-defined network: