improve node selector docs

modules/nodes-scheduler-node-selectors-pod.adoc

@@ -7,44 +7,53 @@
 
 You can use node selector labels on pods to control where the pod is scheduled.
 
-You then add labels to a specific nodes where you want the pods scheduled or to the MachineSet that controls the nodes. 
+With node selectors, {product-title} schedules the pods on nodes that contain matching labels. 
 
 You can add labels to a node or MachineConfig, but the labels will not persist if the node or machine goes down. 
 Adding the label to the MachineSet ensures that new nodes or machines will have the label.
 
-.Procedure
+To add node selectors to an existing pod, add a node selector to the controlling object for that node, such as 
+a ReplicaSet, Daemonset, or StatefulSet. Any existing pods under that controlling object are recreated on a node
+with a matching label. If you are creating a new pod, you can add the node selector directly
+to the pod spec. 
+
+[NOTE]
+====
+You cannot add a node selector to an existing scheduled pod.
+====
+
+.Prerequisites
+
+If you want to add a node selector to existing pods, determine the controlling object for that pod.
+For exeample, the `router-default-66d5cf9464-m2g75` pod is controlled by the `router-default-66d5cf9464`
+ReplicaSet:
 
-. Add the desired node selector on your pod. 
-+
-For example, make sure that your pod configuration features the `nodeSelector`
-value indicating the desired label:
-+
-[source,yaml]
 ----
-apiVersion: v1
-kind: Pod
-spec:
-  nodeSelector:
-    <key>: <value>
-...
-----
-+
-For example:
-+
-[source,yaml]
-----
-apiVersion: v1
-kind: Pod
+$ oc describe pod router-default-66d5cf9464-7pwkc
+
+Name:               router-default-66d5cf9464-7pwkc
+Namespace:          openshift-ingress
 
 ....
 
-spec:
-  nodeSelector:
-    region: east
-    type: user-node
+Controlled By:      ReplicaSet/router-default-66d5cf9464
 ----
 
-. Add the label to your nodes:
+The web console lists the controlling object under `ownerReferences` in the pod YAML:
++
+----
+  ownerReferences:
+    - apiVersion: apps/v1
+      kind: ReplicaSet
+      name: router-default-66d5cf9464
+      uid: d81dd094-da26-11e9-a48a-128e7edf0312
+      controller: true
+      blockOwnerDeletion: true
+----
+
+.Procedure
+
+. Add the desired label to your nodes:
 +
 ----
 $ oc label <resource> <name> <key>=<value>
@@ -89,6 +98,67 @@ metadata:
 ----
 <1> Label added to the node.
 
+. Add the desired node selector a pod:
++
+* To add a node selector to existing and furture pods, add a node selector to the controlling object for the pods:
++
+For example:
++
+----
+kind: ReplicaSet
+
+....
+
+spec:
+
+....
+
+  template:
+    metadata:
+      creationTimestamp: null
+      labels:
+        ingresscontroller.operator.openshift.io/deployment-ingresscontroller: default
+        pod-template-hash: 66d5cf9464
+    spec:
+      nodeSelector:
+        beta.kubernetes.io/os: linux
+        node-role.kubernetes.io/worker: ''
+        type: user-node <1>
+----
+<1> Add the desired node selector.
++
+* For a new pod, you can add the selector to the pod specification directly:
++
+[source,yaml]
+----
+apiVersion: v1
+kind: Pod
+
+...
+
+spec:
+  nodeSelector:
+    <key>: <value>
+
+...
+
+----
++
+For example:
++
+[source,yaml]
+----
+apiVersion: v1
+kind: Pod
+
+....
+
+spec:
+  nodeSelector:
+    region: east
+    type: user-node
+----
+
 [NOTE] 
 ====
 If you are using node selectors and node affinity in the same pod configuration, note the following: