OCPBUGS-18565: Specifiying best practices for NNCP policy applications

Author: rohennes

modules/virt-example-vlan-nncp.adoc

@@ -5,8 +5,14 @@
 [id="virt-example-vlan-nncp_{context}"]
 = Example: VLAN interface node network configuration policy
 
-Create a VLAN interface on nodes in the cluster by applying a `NodeNetworkConfigurationPolicy` manifest
-to the cluster.
+Create a VLAN interface on nodes in the cluster by applying a `NodeNetworkConfigurationPolicy` manifest to the cluster.
+
+[NOTE]
+====
+Define all related configurations for the VLAN interface of a node in a single `NodeNetworkConfigurationPolicy` manifest. For example, define the VLAN interface for a node and the related routes for the VLAN interface in the same `NodeNetworkConfigurationPolicy` manifest.
+
+When a node restarts, the Kubernetes NMState Operator cannot control the order in which policies are applied. Therefore, if you use separate policies for related network configurations, the Kubernetes NMState Operator might apply these policies in a sequence that results in a degraded network object.
+====
 
 The following YAML file is an example of a manifest for a VLAN interface.
 It includes samples values that you must replace with your own information.

networking/k8s_nmstate/k8s-nmstate-updating-node-network-config.adoc

@@ -38,6 +38,18 @@ include::modules/virt-removing-interface-from-nodes.adoc[leveloffset=+2]
 [id="virt-nmstate-example-policy-configurations"]
 == Example policy configurations for different interfaces
 
+The following examples show different `NodeNetworkConfigurationPolicy` manifest configurations.
+
+For best performance, consider the following factors when applying a policy:
+
+* When you need to apply a policy to more than one node, create a `NodeNetworkConfigurationPolicy` manifest for each target node. Scoping a policy to a single node reduces the overall length of time for the Kubernetes NMState Operator to apply the policies. 
++
+In contrast, if a single policy includes configurations for several nodes, the Kubernetes NMState Operator applies the policy to each node in sequence, which increases the overall length of time for policy application. 
+
+* All related network configurations should be specified in a single policy. 
++
+When a node restarts, the Kubernetes NMState Operator cannot control the order in which policies are applied. Therefore, the Kubernetes NMState Operator might apply interdependent policies in a sequence that results in a degraded network object. 
+
 include::modules/virt-example-bridge-nncp.adoc[leveloffset=+2]
 
 include::modules/virt-example-vlan-nncp.adoc[leveloffset=+2]