From 76440b211079bd930107b964cffdb6964207446f Mon Sep 17 00:00:00 2001
From: Michael Burke <mburke@redhat.com>
Date: Wed, 24 Jan 2018 20:50:31 -0500
Subject: [PATCH] reorg'd scheduler doc and new pod placement topic

---
 _topic_map.yml                                |    2 +
 admin_guide/revhistory_admin_guide.adoc       |   24 +
 admin_guide/scheduling/index.adoc             |    5 +
 admin_guide/scheduling/pod_placement.adoc     |  380 ++++++
 admin_guide/scheduling/scheduler.adoc         | 1181 +++++++++--------
 .../admission_controllers.adoc                |    8 +-
 welcome/revhistory_full.adoc                  |    4 +
 7 files changed, 1049 insertions(+), 555 deletions(-)
 create mode 100644 admin_guide/scheduling/pod_placement.adoc

diff --git a/_topic_map.yml b/_topic_map.yml
index c7910737bfca..b22eaeb51ff8 100644
--- a/_topic_map.yml
+++ b/_topic_map.yml
@@ -573,6 +573,8 @@ Topics:
     File: scheduler
   - Name: Custom Scheduling
     File: custom_scheduler
+  - Name: Controlling Pod Placement
+    File: pod_placement
   - Name: Advanced Scheduling
     File: scheduler-advanced
   - Name: Advanced Scheduling and Node Affinity
diff --git a/admin_guide/revhistory_admin_guide.adoc b/admin_guide/revhistory_admin_guide.adoc
index 37f405dd3f91..499e43ae14cc 100644
--- a/admin_guide/revhistory_admin_guide.adoc
+++ b/admin_guide/revhistory_admin_guide.adoc
@@ -8,6 +8,30 @@
 
 // do-release: revhist-tables
 
+== Fri Feb 23 2018
+
+// tag::admin_guide_fri_feb_23_2018[]
+[cols="1,3",options="header"]
+|===
+
+|Affected Topic |Description of Change
+//Fri Feb 23 2018
+n|xref:../admin_guide/scheduling/scheduler.adoc#admin-guide-scheduler[Default Scheduling]
+|Reorganized topic and updated the list of predicates and policies in the xref:../admin_guide/scheduling/scheduler.adoc#scheduler-policy[Scheduler Policy] section.
+
+|xref:../admin_guide/scheduling/pod_placement.adoc#controlling-pod-placement[Controlling Pod Placement]
+|Created new topic from the Controlling Pod Placement section of the xref:../admin_guide/scheduling/scheduler.adoc#admin-guide-scheduler[Default Scheduling] topic. No change to the content. 
+
+|xref:../admin_guide/manage_scc.adoc#admin-guide-manage-scc[Managing Security Context Constraints]
+|Noted the importance of `-z` flag usage when xref:../admin_guide/manage_scc.adoc#add-scc-to-user-group-project[granting access to service accounts].
+
+|xref:../admin_guide/service_accounts.adoc#admin-guide-service-accounts[Configuring Service Accounts]
+|Noted the importance of `-z` flag usage when xref:../admin_guide/service_accounts.adoc#admin-sa-user-names-and-groups[granting access to service accounts].
+|===
+
+// end::admin_guide_fri_feb_23_2018[]]
+
+
 == Tues Feb 20 2018
 
 // tag::admin_guide_tues_feb_20_2018[]
diff --git a/admin_guide/scheduling/index.adoc b/admin_guide/scheduling/index.adoc
index 3a22455f6e1a..e2e9d32a5b69 100644
--- a/admin_guide/scheduling/index.adoc
+++ b/admin_guide/scheduling/index.adoc
@@ -16,6 +16,10 @@ toc::[]
 Pod scheduling is an internal process that determines placement of new
 pods onto nodes within the cluster.
 
+The scheduler code has a clean separation that watches new pods
+as they get created and identifies the most suitable node to host them. It then
+creates bindings (pod to node bindings) for the pods using the master API.
+
 [[admin-guide-scheduling-index-default]]
 == Default scheduling
 
@@ -36,3 +40,4 @@ For information about advanced scheduling, see xref:../../admin_guide/scheduling
 {product-title} also allows you to use your own or third-party schedulers by editing the pod specification. 
 
 For more information, see xref:../../admin_guide/scheduling/custom_scheduler.adoc#admin-guide-sched-custom[Custom Schedulers].
+
diff --git a/admin_guide/scheduling/pod_placement.adoc b/admin_guide/scheduling/pod_placement.adoc
new file mode 100644
index 000000000000..fc62c28a0f56
--- /dev/null
+++ b/admin_guide/scheduling/pod_placement.adoc
@@ -0,0 +1,380 @@
+[[controlling-pod-placement]]
+= Controlling Pod Placement
+{product-author}
+{product-version}
+:data-uri:
+:icons:
+:experimental:
+:toc: macro
+:toc-title:
+
+toc::[]
+
+== Overview
+
+As a cluster administrator, you can set a policy to prevent application
+developers with certain roles from targeting specific nodes when scheduling
+pods.
+
+The Pod Node Constraints admission controller ensures that pods 
+are deployed onto only specified node hosts using labels]
+and prevents users without a specific role from using the 
+`nodeSelector` field to schedule pods.
+
+[[constraining-pod-placement-labels]]
+== Constraining Pod Placement Using Node Name
+
+Use the Pod Node Constraints admission controller to ensure a pod 
+is deployed onto only a specified node host by assigning it a label
+and specifying this in the `nodeName` setting in a pod configuration.
+
+. Ensure you have the desired labels
+ifdef::openshift-enterprise,openshift-origin[]
+(see xref:../../admin_guide/manage_nodes.adoc#updating-labels-on-nodes[Updating
+Labels on Nodes] for details)
+endif::openshift-enterprise,openshift-origin[]
+ifdef::openshift-dedicated[]
+(request changes by opening a support case on the
+https://access.redhat.com/support/[Red Hat Customer Portal])
+endif::openshift-dedicated[]
+and xref:../../admin_guide/managing_projects.adoc#using-node-selectors[node selector]
+set up in your environment.
++
+For example, make sure that your pod configuration features the `nodeName`
+value indicating the desired label:
++
+----
+apiVersion: v1
+kind: Pod
+spec:
+  nodeName: <value>
+----
+
+. Modify the master configuration file
+(*_/etc/origin/master/master-config.yaml_*) in two places:
++
+.. Add `PodNodeConstraints` to the `admissionConfig` section:
++
+----
+...
+admissionConfig:
+  pluginConfig:
+    PodNodeConstraints:
+      configuration:
+        apiversion: v1
+        kind: PodNodeConstraintsConfig
+...
+----
+
+.. Then, add the same to the `kubernetesMasterConfig` section:
++
+----
+...
+kubernetesMasterConfig:
+  admissionConfig:
+    pluginConfig:
+      PodNodeConstraints:
+        configuration:
+          apiVersion: v1
+          kind: PodNodeConstraintsConfig
+...
+----
+
+. Restart {product-title} for the changes to take effect.
+ifdef::openshift-origin[]
++
+----
+# systemctl restart origin-master
+----
+endif::[]
+ifdef::openshift-enterprise[]
++
+----
+# systemctl restart atomic-openshift-master
+----
+endif::[]
+
+
+[[constraining-pod-placement-nodeselector]]
+== Constraining Pod Placement Using a Node Selector
+
+Using xref:../../admin_guide/managing_projects.adoc#using-node-selectors[node selectors], 
+you can ensure that pods are only placed onto nodes with specific labels. As a cluster administrator, you can
+use the Pod Node Constraints admission controller to set a policy that prevents users without the *pods/binding* permission 
+from using node selectors to schedule pods.
+
+The `nodeSelectorLabelBlacklist` field of a master configuration file gives you
+control over the labels that certain roles can specify in a pod configuration's
+`nodeSelector` field. Users, service accounts, and groups that have the
+*pods/binding* permission xref:../../admin_guide/manage_rbac.adoc#admin-guide-manage-rbac[role]
+ can specify any node selector. Those without the
+*pods/binding* permission are prohibited from setting a `nodeSelector` for any
+label that appears in `nodeSelectorLabelBlacklist`.
+
+For example, an {product-title} cluster might consist of five data
+centers spread across two regions. In the U.S., "us-east", "us-central", and
+"us-west"; and in the Asia-Pacific region (APAC), "apac-east" and "apac-west".
+Each node in each geographical region is labeled accordingly. For example,
+`region: us-east`.
+
+[NOTE]
+====
+ifdef::openshift-enterprise,openshift-origin[]
+See xref:../../admin_guide/manage_nodes.adoc#updating-labels-on-nodes[Updating
+Labels on Nodes] for details on assigning labels.
+endif::openshift-enterprise,openshift-origin[]
+ifdef::openshift-dedicated[]
+(request changes by opening a support case on the
+https://access.redhat.com/support/[Red Hat Customer Portal])
+endif::openshift-dedicated[]
+====
+
+As a cluster administrator, you can create an infrastructure where application
+developers should be deploying pods only onto the nodes closest to their
+geographical location. You can create a node selector, grouping the U.S. data centers into `superregion: us` and the APAC
+data centers into `superregion: apac`.
+
+To maintain an even loading of resources per data center, you can add the
+desired `region` to the `nodeSelectorLabelBlacklist` section of a master
+configuration. Then, whenever a developer located in the U.S. creates a pod, it
+is deployed onto a node in one of the regions with the `superregion: us` label.
+If the developer tries to target a specific region for their pod (for example,
+`region: us-east`), they receive an error. If they try again, without the
+node selector on their pod, it can still be deployed onto the region they tried
+to target, because `superregion: us` is set as the project-level node selector,
+and nodes labeled `region: us-east` are also labeled `superregion: us`.
+
+
+. Ensure you have the desired labels
+ifdef::openshift-enterprise,openshift-origin[]
+(see xref:../../admin_guide/manage_nodes.adoc#updating-labels-on-nodes[Updating
+Labels on Nodes] for details)
+endif::openshift-enterprise,openshift-origin[]
+ifdef::openshift-dedicated[]
+(request changes by opening a support case on the
+https://access.redhat.com/support/[Red Hat Customer Portal])
+endif::openshift-dedicated[]
+and xref:../../admin_guide/managing_projects.adoc#using-node-selectors[node selector]
+set up in your environment.
+//tag::node-selectors[]
++
+For example, make sure that your pod configuration features the `nodeSelector`
+value indicating the desired label:
++
+----
+apiVersion: v1
+kind: Pod
+spec:
+  nodeSelector:
+    <key>: <value>
+...
+----
+
+. Modify the master configuration file
+(*_/etc/origin/master/master-config.yaml_*) in two places:
++
+.. Add `nodeSelectorLabelBlacklist` to the `admissionConfig` section with
+the labels that are assigned to the node hosts you want to deny pod placement:
++
+----
+...
+admissionConfig:
+  pluginConfig:
+    PodNodeConstraints:
+      configuration:
+        apiversion: v1
+        kind: PodNodeConstraintsConfig
+        nodeSelectorLabelBlacklist:
+          - kubernetes.io/hostname
+          - <label>
+...
+----
+====
+
+.. Then, add the same to the `kubernetesMasterConfig` section to restrict direct pod creation:
++
+----
+...
+kubernetesMasterConfig:
+  admissionConfig:
+    pluginConfig:
+      PodNodeConstraints:
+        configuration:
+          apiVersion: v1
+          kind: PodNodeConstraintsConfig
+          nodeSelectorLabelBlacklist:
+            - kubernetes.io/hostname
+            - <label_1>
+...
+----
+
+. Restart {product-title} for the changes to take effect.
+ifdef::openshift-origin[]
++
+----
+# systemctl restart origin-master
+----
+endif::[]
+ifdef::openshift-enterprise[]
++
+----
+# systemctl restart atomic-openshift-master
+----
+endif::[]
+
+//end::node-selectors[]
+
+[[controlling-pod-placement-projects]]
+== Control Pod Placement to Projects
+
+The _Pod Node Selector_ admission controller allows you to force pods onto nodes associated with a specific project and prevent pods from being scheduled in those nodes.
+
+The *Pod Node Selector* admission controller determines where a pod can be placed using xref:../../architecture/core_concepts/pods_and_services.adoc#labels[labels on projects] and node selectors specified in pods. A new pod will be placed on a node associated with a project  only if the node selectors in the pod match the labels in the project.
+
+After the pod is created, the node selectors are merged into the pod so that the pod specification includes the labels originally included in the specification and any new labels from the node selectors. The example below illustrates the merging effect.
+
+The *Pod Node Selector* admission controller also allows you to create a list of labels that are permitted in a specific project. This list acts as a _whitelist_ that lets developers know what labels are acceptable to use in a project and gives administrators greater control over labeling in a cluster.
+
+To activate the *Pod Node Selector* admission controller: 
+
+. Configure the *Pod Node Selector* admission controller and whitelist, using one of the following methods: 
+
+** Add the following to the master configuration file (*_/etc/origin/master/master-config.yaml_*):
++
+----
+admissionConfig:
+  pluginConfig:
+    PodNodeSelector:
+      configuration:
+        podNodeSelectorPluginConfig: <1>
+          clusterDefaultNodeSelector: "k3=v3" <2>
+          ns1: region=west,env=test,infra=fedora,os=fedora <2>
+----
++
+<1> Adds the *Pod Node Selector* admission controller plug-in.
+<2> Creates default labels for all nodes.
+<3> Creates a whitelist of permitted labels in the specified project. Here, the project is `ns1` and the labels are the `key=value` pairs that follow.
+
+* Create a file containing the admission controller information:
++
+----
+podNodeSelectorPluginConfig:
+    clusterDefaultNodeSelector: "k3=v3"
+     ns1: region=west,env=test,infra=fedora,os=fedora
+----
++
+Then, reference the file in the master configuration:
++
+----
+admissionConfig:
+  pluginConfig:
+    PodNodeSelector:
+      location: <path-to-file>
+----
++
+[NOTE]
+====
+If a project does not have a node selectors specified, the pods associated with that project will be merged using the default node selector (`clusterDefaultNodeSelector`).
+====
+
+. Restart {product-title} for the changes to take effect.
+ifdef::openshift-origin[]
++
+----
+# systemctl restart origin-master
+----
+endif::[]
+ifdef::openshift-enterprise[]
++
+----
+# systemctl restart atomic-openshift-master
+----
+endif::[]
+
+. Create a project object that includes the
+`scheduler.alpha.kubernetes.io/node-selector` annotation and labels.
++
+----
+{
+    "kind": "Namespace",
+    "apiVersion": "v1",
+    "metadata": {
+        "name": "ns1",
+        "annotations": {
+            "scheduler.alpha.kubernetes.io/node-selector": "env=test,infra=fedora" <1>
+        }
+    },
+    "spec": {},
+    "status": {}
+}
+
+----
++
+<1> Annotation to create the labels to match the project label selector. Here, the key/value labels are `env=test` and `infra=fedora`.
+
+. Create a pod specification that includes the labels in the node selector, for example:
++
+----
+apiVersion: v1
+kind: Pod
+metadata:
+  labels:
+    name: hello-pod
+  name: hello-pod
+spec:
+  containers:
+    - image: "docker.io/ocpqe/hello-pod:latest"
+      imagePullPolicy: IfNotPresent
+      name: hello-pod
+      ports:
+        - containerPort: 8080
+          protocol: TCP
+      resources: {}
+      securityContext:
+        capabilities: {}
+        privileged: false
+      terminationMessagePath: /dev/termination-log
+  dnsPolicy: ClusterFirst
+  restartPolicy: Always
+  nodeSelector: <1>
+    env: test
+    os: fedora
+  serviceAccount: ""
+status: {}
+----
++
+<1> Node selectors to match project labels.
+
+
+. Create the pod in the project:
++
+----
+oc create -f pod.yaml --namespace=ns1
+----
+
+. Check that the node selector labels were added to the pod configuration:
++
+----
+get pod pod1 --namespace=ns1 -o json
+
+nodeSelector": {
+ "env": "test",
+ "infra": "fedora",
+ "os": "fedora"
+}
+----
++
+The node selectors are merged into the pod and the pod should be scheduled in the appropriate project.
+
+If you create a pod with a label that is not specified in the project specification, the pod is not scheduled on the node.
+
+For example, here the label `env: production` is not in any project specification:
+
+----
+nodeSelector:
+ "env: production"
+ "infra": "fedora",
+ "os": "fedora"
+----
+
+If there is a node that does not have a node selector annotation, the pod will be scheduled there.
diff --git a/admin_guide/scheduling/scheduler.adoc b/admin_guide/scheduling/scheduler.adoc
index 304d564ebf8f..78ac74e46eeb 100644
--- a/admin_guide/scheduling/scheduler.adoc
+++ b/admin_guide/scheduling/scheduler.adoc
@@ -21,28 +21,29 @@ particular node.
 [[generic-scheduler]]
 == Generic Scheduler
 The existing generic scheduler is the default platform-provided scheduler
-"engine" that selects a node to host the pod in a 3-step operation:
+_engine_ that selects a node to host the pod in a three-step operation:
 
-. Filter the nodes
-. Prioritize the filtered list of nodes
-. Select the best fit node
+. The scheduler xref:filter-the-nodes[filters out inappropriate nodes using predicates].
+. The  scheduler xref:prioritize-filtered-list-nodes[prioritizes the filtered list of nodes].
+. The scheduler xref:select-best-fit-node[selects the highest priority node] for the pod.
 
 [[filter-the-nodes]]
-=== Filter the Nodes
+== Filter the Nodes
 The available nodes are filtered based on the constraints or requirements
-specified. This is done by running each of the nodes through the list of filter
-functions called 'predicates'.
+specified. This is done by running each node through the list of filter
+functions called xref:available-predicates[_predicates_].
 
 [[prioritize-filtered-list-nodes]]
 === Prioritize the Filtered List of Nodes
-This is achieved by passing each node through a series of 'priority' functions
+This is achieved by passing each node through a series of
+xref:available-priority-functions[_priority_ functions]
 that assign it a score between 0 - 10, with 0 indicating a bad fit and 10
 indicating a good fit to host the pod. The scheduler configuration can also take
-in a simple "weight" (positive numeric value) for each priority function. The
-node score provided by each priority function is multiplied by the "weight"
-(default weight is 1) and then combined by just adding the scores for each node
-provided by all the priority functions. This weight attribute can be used by
-administrators to give higher importance to some priority functions.
+in a simple _weight_ (positive numeric value) for each priority function. The
+node score provided by each priority function is multiplied by the weight
+(default weight for most priorities is 1) and then combined by adding the scores for each node
+provided by all the priorities. This weight attribute can be used by
+administrators to give higher importance to some priorities.
 
 [[select-best-fit-node]]
 === Select the Best Fit Node
@@ -50,9 +51,215 @@ The nodes are sorted based on their scores and the node with the highest score
 is selected to host the pod. If multiple nodes have the same high score, then
 one of them is selected at random.
 
+[[scheduler-policy]]
+== Scheduler Policy
+The selection of the xref:available-predicates[predicate] and xref:available-priority-functions[priorities]
+defines the policy for the scheduler.
+
+The scheduler configuration file is a JSON file that specifies the predicates and priorities the scheduler
+will consider.
+
+In the absence of the scheduler policy file, the default configuration file,
+*_/etc/origin/master/scheduler.json_*, gets applied.
+
+[IMPORTANT]
+====
+The predicates and priorities defined in
+the scheduler configuration file completely override the default scheduler
+policy. If any of the default predicates and priorities are required,
+you must explicitly specify the functions in the scheduler configuration file.
+====
+
+[[default-scheduler-policy]]
+.Default scheduler configuration file
+[source,json]
+----
+{
+    "apiVersion": "v1",
+    "kind": "Policy",
+    "predicates": [
+        {
+            "name": "NoVolumeZoneConflict"
+        },
+        {
+            "name": "MaxEBSVolumeCount"
+        },
+        {
+            "name": "MaxGCEPDVolumeCount"
+        },
+        {
+            "name": "MaxAzureDiskVolumeCount"
+        },
+        {
+            "name": "MatchInterPodAffinity"
+        },
+        {
+            "name": "NoDiskConflict"
+        },
+        {
+            "name": "GeneralPredicates"
+        },
+        {
+            "name": "PodToleratesNodeTaints"
+        },
+        {
+            "name": "CheckNodeMemoryPressure"
+        },
+        {
+            "name": "CheckNodeDiskPressure"
+        },
+        {
+            "name": "NoVolumeNodeConflict"
+        },
+        {
+            "argument": {
+                "serviceAffinity": {
+                    "labels": [
+                        "region"
+                    ]
+                }
+            },
+            "name": "Region"
+
+         }
+    ],
+    "priorities": [
+        {
+            "name": "SelectorSpreadPriority",
+            "weight": 1
+        },
+        {
+            "name": "InterPodAffinityPriority",
+            "weight": 1
+        },
+        {
+            "name": "LeastRequestedPriority",
+            "weight": 1
+        },
+        {
+            "name": "BalancedResourceAllocation",
+            "weight": 1
+        },
+        {
+            "name": "NodePreferAvoidPodsPriority",
+            "weight": 10000
+        },
+        {
+            "name": "NodeAffinityPriority",
+            "weight": 1
+        },
+        {
+            "name": "TaintTolerationPriority",
+            "weight": 1
+        },
+        {
+            "argument": {
+                "serviceAntiAffinity": {
+                    "label": "zone"
+                }
+            },
+            "name": "Zone",
+            "weight": 2
+        }
+    ]
+}
+----
+
+[[modifying-scheduler-policy]]
+=== Modifying Scheduler Policy
+
+The scheduler policy is defined in a file on the master,
+named *_/etc/origin/master/scheduler.json_* by default,
+unless overridden by the `kubernetesMasterConfig.schedulerConfigFile`
+field in the
+xref:../../install_config/master_node_configuration.adoc#master-configuration-files[master configuration file].
+
+.Sample modified scheduler configuration file
+[source,json]
+----
+kind: "Policy"
+version: "v1"
+"predicates": [
+        {
+            "name": "PodFitsResources"
+        },
+        {
+            "name": "NoDiskConflict"
+        },
+        {
+            "name": "MatchNodeSelector"
+        },
+        {
+            "name": "HostName"
+        },
+        {
+            "name": "NoVolumeNodeConflict"
+        },
+        {
+            "argument": {
+                "serviceAffinity": {
+                    "labels": [
+                        "region"
+                    ]
+                }
+            },
+            "name": "Region"
+        }
+    ],
+    "priorities": [
+        {
+            "name": "LeastRequestedPriority",
+            "weight": 1
+        },
+        {
+            "name": "BalancedResourceAllocation",
+            "weight": 1
+        },
+        {
+            "name": "ServiceSpreadingPriority",
+            "weight": 1
+        },
+        {
+            "argument": {
+                "serviceAntiAffinity": {
+                    "label": "zone"
+                }
+            },
+            "name": "Zone",
+            "weight": 2
+        }
+    ]
+----
+
+To modify the scheduler policy:
+
+. Edit the scheduler configuration file to configure the desired
+xref:default-scheduler-policy[default predicates and priorities].
+You can create a custom configuration, or use and modify one of the
+xref:scheduler-sample-policies[sample policy configurations].
+
+. Add any xref:configurable-predicates[configurable predicates] and xref:configurable-priority-functions[configurable priorities]
+you require.
+
+. Restart the {product-title} for the changes to take effect.
++
+ifdef::openshift-enterprise[]
+----
+# systemctl restart atomic-openshift-master-api atomic-openshift-master-controllers
+----
+endif::[]
+ifdef::openshift-origin[]
+----
+# systemctl restart origin-master-api origin-master-controllers
+----
+endif::[]
+
 [[available-predicates]]
 == Available Predicates
-There are several predicates provided out of the box in Kubernetes. Some of
+
+Predicates are rules that filter out unqualified nodes.
+
+There are several predicates provided by default in {product-title}. Some of
 these predicates can be customized by providing certain parameters. Multiple
 predicates can be combined to provide additional filtering of nodes.
 
@@ -62,33 +269,122 @@ These predicates do not take any configuration parameters or inputs from the
 user. These are specified in the scheduler configuration using their exact
 name.
 
-**_PodFitsPorts_** deems a node to be fit for hosting a pod based on the absence
-of port conflicts.
+**_NoVolumeZoneConflict_** checks that the volumes a pod requests
+are available in the zone. _The default scheduler policy includes this predicate._
 ----
-{"name" : "PodFitsPorts"}
+{"name" : "NoVolumeZoneConflict"}
 ----
 
-**_PodFitsResources_** determines a fit based on resource availability. The
-nodes can declare their resource capacities and then pods can specify what
-resources they require. Fit is based on requested, rather than used
-resources.
+**_MaxEBSVolumeCount_** checks the maximum number of volumes that can be attached to an AWS instance.
+_The default scheduler policy includes this predicate._
 ----
-{"name" : "PodFitsResources"}
+{"name" : "MaxEBSVolumeCount"}
+----
+
+**_MaxGCEPDVolumeCount_** checks the maximum number of Google Compute Engine (GCE) Persistent Disks (PD).
+_The default scheduler policy includes this predicate._
+----
+{"name" : "MaxGCEPDVolumeCount"}
 ----
 
-**_NoDiskConflict_** determines fit based on non-conflicting disk volumes.
-It evaluates if a pod can fit due to the volumes it requests, and those that are
-already mounted. It is GCE PD, Amazon EBS, and Ceph RBD specific.
-Only Persistent Volume Claims for those supported types are checked.
-Persistent Volumes added directly to pods are not evaluated and are not constrained by this policy.
+**_MatchInterPodAffinity_** checks if the pod affinity/antiaffinity rules permit the pod.
+_The default scheduler policy includes this predicate._
+----
+{"name" : "MatchInterPodAffinity"}
+----
+
+**_NoDiskConflict_** checks if the volume requested by a pod is available.
+_The default scheduler policy includes this predicate._
 ----
 {"name" : "NoDiskConflict"}
 ----
 
-**_MatchNodeSelector_** determines fit based on node selector query that is
-defined in the pod.
+**_PodToleratesNodeTaints_** checks if a pod can tolerate the node taints.
+_The default scheduler policy includes this predicate._
 ----
-{"name" : "MatchNodeSelector"}
+{"name" : "PodToleratesNodeTaints"}
+----
+
+**_CheckNodeMemoryPressure_** checks if a pod can be scheduled on a node with a memory pressure condition.
+_The default scheduler policy includes this predicate._
+----
+{"name" : "CheckNodeMemoryPressure"}
+----
+
+**_CheckNodeDiskPressure_** checks if a pod can be scheduled on a node with a disk pressure condition.
+_The default scheduler policy includes this predicate._
+----
+{"name" : "CheckNodeDiskPressure"}
+----
+
+**_NoVolumeNodeConflict_**
+----
+{"name" : "NoVolumeNodeConflict"}
+----
+
+**_CheckVolumeBinding_** evaluates if a pod can fit based on the volumes, it requests, for both bound and unbound PVCs.
+* For PVCs that are bound, the predicate checks that the corresponding PV's node affinity is satisfied by the given node.
+* For PVCs that are unbound, the predicate searched for available PVs that can satisfy the PVC requirements and that
+the PV node affinity is satisfied by the given node.
+
+The predicate returns true if all bound PVCs have compatible PVs with the node, and if all unbound PVCs can be matched with an available and node-compatible PV.
+----
+{"name" : "CheckVolumeBinding"}
+----
+
+The `CheckVolumeBinding` predicate must be enabled in non-default schedulers.
+
+**_CheckNodeCondition_** checks if a pod can be scheduled on a node reporting *out of disk*, *network unavailable*, or *not ready* conditions.
+----
+{"name" : "CheckNodeCondition"}
+----
+
+**_PodToleratesNodeNoExecuteTaints_** checks if a pod tolerations can tolerate a node *NoExecute* taints.
+----
+{"name" : "PodToleratesNodeNoExecuteTaints"}
+----
+
+**_CheckNodeLabelPresence_** checks if all of the specified labels exist on a node, regardless of their value.
+----
+{"name" : "CheckNodeLabelPresence"}
+----
+
+**_checkServiceAffinity_** checks that ServiceAffinity labels are homogeneous for pods that are scheduled on a node.
+----
+{"name" : "checkServiceAffinity"}
+----
+
+**_MaxAzureDiskVolumeCount_**  checks the maximum number of Azure Disk Volumes.
+----
+{"name" : "MaxAzureDiskVolumeCount"}
+----
+
+[[admin-guide-scheduler-general-predicates]]
+=== General Predicates
+
+The following general predicates check whether non-critical predicates and essential predicates pass. Non-critical predicates are the predicates
+that only non-critical pods need to pass and essential predicates are the predicates that all pods need to pass.
+
+_The default scheduler policy includes the general predicates._
+
+[discrete]
+==== Non-critical general predicates
+
+**_PodFitsResources_** determines a fit based on resource availability
+(CPU, memory, GPU, and so forth). The
+nodes can declare their resource capacities and then pods can specify what
+resources they require. Fit is based on requested, rather than used
+resources.
+----
+{"name" : "PodFitsResources"}
+----
+[discrete]
+==== Essential general predicates
+
+**_PodFitsHostPorts_** determines if a node has free ports for the requested pod ports (absence
+of port conflicts).
+----
+{"name" : "PodFitsHostPorts"}
 ----
 
 **_HostName_** determines fit based on the presence of the Host parameter
@@ -97,56 +393,170 @@ and a string match with the name of the host.
 {"name" : "HostName"}
 ----
 
+**_MatchNodeSelector_** determines fit based on
+xref:../../admin_guide/scheduling/node_selector.adoc#admin-guide-sched-selector[node selector (nodeSelector)] queries
+defined in the pod.
+----
+{"name" : "MatchNodeSelector"}
+----
+
 [[configurable-predicates]]
 === Configurable Predicates
-These predicates can be configured by the user to tweak their functioning. They
-can be given any user-defined name. The type of the predicate is identified by
-the argument that they take. Since these are configurable, multiple predicates
+You can configure these predicates in the scheduler configuration,
+by default *_/etc/origin/master/scheduler.json_*, to add labels to affect
+how the predicate functions.
+
+Since these are configurable, multiple predicates
 of the same type (but different configuration parameters) can be combined as
 long as their user-defined names are different.
 
-**_ServiceAffinity_** filters out nodes that do not belong to the specified
-topological level defined by the provided labels. This predicate takes in a list
-of labels and ensures affinity within the nodes (that have the same label
-values) for pods belonging to the same service. If the pod specifies a value for
-the labels in its NodeSelector, then the nodes matching those labels are the
-ones where the pod is scheduled. If the pod does not specify the labels in its
-NodeSelector, then the first pod can be placed on any node based on availability
+For information on using these priorities,
+see xref:modifying-scheduler-policy[Modifying Scheduler Policy].
+
+**_ServiceAffinity_** places pods on nodes based on the service running on that pod.
+Placing pods of the same service on the same or co-located nodes can lead to higher efficiency.
+
+This predicate attempts to place pods with specific labels
+in its xref:../../admin_guide/scheduling/node_selector.adoc#admin-guide-sched-selector[node selector]
+on nodes that have the same label.
+
+If the pod does not specify the labels in its
+node selector, then the first pod is placed on any node based on availability
 and all subsequent pods of the service are scheduled on nodes that have the
-same label values.
-----
-{"name" : "Zone", "argument" : {"serviceAffinity" : {"labels" : ["zone"]}}}
-----
+same label values as that node.
+
+[source,json]
+----
+"predicates":[
+      {
+         "name":"<name>", <1>
+         "weight" : "1" <2>
+         "argument":{
+            "serviceAffinity":{
+               "labels":[
+                  "<label>" <3>
+               ]
+            }
+         }
+      }
+   ],
+----
+<1> Specify a name for the predicate.
+<2> Specify a weight from 1 (bad fit) to 10 (best fit).
+<3> Specify a label for matching.
+For example:
+
+[source,json]
+----
+         "name":"ZoneAffinity",
+         "weight" : "1"
+         "argument":{
+            "serviceAffinity":{
+               "labels":[
+                  "rack"
+----
+
+For example. if the first pod of a service had a node selector `rack` was scheduled to a node with label `region=rack`,
+all the other subsequent pods belonging to the same service will be scheduled on nodes
+with the same `region=rack` label. For more information,
+see xref:../../admin_guide/scheduling/pod_placement.adoc#controlling-pod-placement[Controlling Pod Placement].
+
+Multiple-level labels are also supported. Users can also specify all pods for a service to
+be scheduled on nodes within the same region and within the same zone (under the region).
 
 **_LabelsPresence_** checks whether a particular node has a certain label
 defined or not, regardless of its value. Matching by label can be useful, for
 example, where nodes have their physical location or status defined by labels.
+
+[source,json]
+----
+"predicates":[
+      {
+         "name":"<name>", <1>
+         "weight" : "1" <2>
+         "argument":{
+            "labelsPresence":{
+               "labels":[
+                  "<label>" <3>
+                presence: true/false
+               ]
+            }
+         }
+      }
+   ],
+----
+<1> Specify a name for the predicate.
+<2> Specify a weight from 1 (bad fit) to 10 (best fit).
+<3> Specify a label for matching.
+<4> Specify whether the labels are required.
++
+* For `presence:false`, if any of the requested labels are present in the node labels,
+the pod cannot be scheduled. If the labels are not present, the pod can be scheduled.
++
+* For `presence:true`, if all of the requested labels are present in the node labels,
+the pod can be scheduled. If all of the lables are not present, the pod is not scheduled.
+
+For example:
+
+[source,json]
 ----
-{"name" : "RequireRegion", "argument" : {"labelsPresence" : {"labels" : ["region"], "presence" : true}}}
+         "name":"RackPreferred",
+         "weight" : "1"
+         "argument":{
+            "labelsPresence":{
+               "labels":[
+                  "rack"
+            "labelsPresence:"{
+                "labels:"[
+                - "region"
+                presence: true
 ----
-* If "presence" is false, and any of the requested labels match any of the
-node labels, it returns false. Otherwise, it returns true.
-* If "presence" is true, and any of the requested labels do not match any of
-the node's labels, it returns false. Otherwise, it returns true.
 
 [[available-priority-functions]]
-== Available Priority Functions
-A custom set of priority functions can be specified to configure the scheduler.
-There are several priority functions provided out-of-the-box in Kubernetes.
-Some of these priority functions can be customized by providing certain
-parameters. Multiple priority functions can be combined and different weights
-can be given to each in order to impact the prioritization. A weight is required
-to be specified and cannot be 0 or negative.
+== Available Priorities
+
+Priorities are rules that rank remaining nodes according to preferences.
+
+A custom set of priorities can be specified to configure the scheduler.
+There are several priorities provided by default in {product-title}.
+Other priorities can be customized by providing certain
+parameters. Multiple priorities can be combined and different weights
+can be given to each in order to impact the prioritization.
 
 [[static-priority-functions]]
-=== Static Priority Functions
-These priority functions do not take any configuration parameters or inputs from
-the user. These are specified in the scheduler configuration using their exact
-name as well as the weight.
+=== Static Priorities
+
+Static priorities do not take any configuration parameters from
+the user, except weight. A weight is required to be specified and cannot be 0 or negative.
+
+These are specified in the scheduler configuration,
+by default *_/etc/origin/master/scheduler.json_*.
+
+The default scheduler policy includes the priorities noted in the list. Each of
+the priority function has a weight of `1` except `*NodePreferAvoidPodsPriority*`,
+which has a weight of `10000`:
+
+**_SelectorSpreadPriority_** looks for services, replication controllers (RC),
+replication sets (RS), and stateful sets that match the pod,
+then finds existing pods that match those selectors.
+The scheduler favors nodes that have fewer existing matching pods. Then, it schedules the pod on a node with the smallest number of
+pods that match those selectors as the pod being scheduled.
+_The default scheduler policy includes this priority._
+----
+{"name" : "SelectorSpreadPriority", "weight" : 1}
+----
+
+**_InterPodAffinityPriority_** computes a sum by iterating through the elements of `weightedPodAffinityTerm` and adding
+_weight_ to the sum if the corresponding PodAffinityTerm is satisfied for that node. The node(s) with the highest sum are the most preferred.
+_The default scheduler policy includes this priority._
+----
+{"name" : "InterPodAffinityPriority", "weight" : 1}
+----
 
 **_LeastRequestedPriority_** favors nodes with fewer requested resources. It
 calculates the percentage of memory and CPU requested by pods scheduled on the
 node, and prioritizes nodes that have the highest available/remaining capacity.
+_The default scheduler policy includes this priority._
 ----
 {"name" : "LeastRequestedPriority", "weight" : 1}
 ----
@@ -154,129 +564,179 @@ node, and prioritizes nodes that have the highest available/remaining capacity.
 **_BalancedResourceAllocation_** favors nodes with balanced resource usage rate.
 It calculates the difference between the consumed CPU and memory as a fraction
 of capacity, and prioritizes the nodes based on how close the two metrics are to
-each other. This should always be used together with _LeastRequestedPriority_.
+each other. This should always be used together with `LeastRequestedPriority`.
+_The default scheduler policy includes this priority._
 ----
 {"name" : "BalancedResourceAllocation", "weight" : 1}
 ----
 
-**_ServiceSpreadingPriority_** spreads pods by minimizing the number of pods
-belonging to the same service onto the same machine.
+**_NodePreferAvoidPodsPriority_** ignores pods that are owned by a controller other than a replication controller.
+_The default scheduler policy includes this priority._
 ----
-{"name" : "ServiceSpreadingPriority", "weight" : 1}
+{"name" : "NodePreferAvoidPodsPriority", "weight" : 10000}
+----
+
+**_NodeAffinityPriority_** prioritizes nodes according to node affinity scheduling preferences
+_The default scheduler policy includes this priority._
+----
+{"name" : "NodeAffinityPriority", "weight" : 1}
+----
+
+**_TaintTolerationPriority_** prioritizes nodes that have a fewer number of _intolerable_ taints on them for a pod. An intolerable taint is one which has key `PreferNoSchedule`.
+_The default scheduler policy includes this priority._
+----
+{"name" : "TaintTolerationPriority", "weight" : 1}
 ----
 
-**_EqualPriority_** gives an equal weight of one to all nodes, if no priority
-configs are provided. It is not required/recommended outside of testing.
+**_EqualPriority_** gives an equal weight of `1` to all nodes, if no priority
+configurations are provided. We recommend using this priority only for testing environments.
 ----
 {"name" : "EqualPriority", "weight" : 1}
 ----
 
+//https://github.com/kubernetes/kubernetes/issues/41712
+**_MostRequestedPriority_** prioritizes nodes with most requested resources. It calculates the percentage of memory and CPU
+requested by pods scheduled on the node, and prioritizes based on the maximum of the average of the fraction of requested to capacity.
+
+----
+{"name" : "MostRequestedPriority", "weight" : 1}
+----
+
+**_ImageLocalityPriority_** prioritizes nodes that already have requested pod container's images.
+----
+{"name" : "ImageLocalityPriority", "weight" : 1}
+----
+
+**_ServiceSpreadingPriority_** spreads pods by minimizing the number of pods
+belonging to the same service onto the same machine.
+----
+{"name" : "ServiceSpreadingPriority", "weight" : 1}
+----
+
 [[configurable-priority-functions]]
-=== Configurable Priority Functions
-These priority functions can be configured by the user by providing certain
-parameters.  They can be given any user-defined name. The type of the priority
+=== Configurable Priorities
+
+You can configure these priorities in the scheduler configuration,
+by default *_/etc/origin/master/scheduler.json_*, to add labels to affect
+how the priorities.
+
+The type of the priority
 function is identified by the argument that they take. Since these are
-configurable, multiple priority functions of the same type (but different
+configurable, multiple priorities of the same type (but different
 configuration parameters) can be combined as long as their user-defined names
 are different.
 
+For information on using these priorities,
+see xref:modifying-scheduler-policy[Modifying Scheduler Policy].
+
 **_ServiceAntiAffinity_** takes a label and ensures a good spread of the pods
 belonging to the same service across the group of nodes based on the label
 values. It gives the same score to all nodes that have the same value for the
 specified label. It gives a higher score to nodes within a group with the least
 concentration of pods.
-----
-{"name" : "RackSpread", "weight" : 1, "argument" : {"serviceAntiAffinity" : {"label" : "rack"}}}
-----
 
-**_LabelPreference_** prefers nodes that have a particular label defined or not,
-regardless of its value.
+[source,json]
 ----
-{"name" : "RackPreferred", "weight" : 1, "argument" : {"labelPreference" : {"label" : "rack"}}}
+"priorities":[
+      {
+         "name":"<name>", <1>
+         "weight" : "1" <2>
+         "argument":{
+            "serviceAntiAffinity":{
+               "labels":[
+                  "<label>" <3>
+               ]
+            }
+         }
+      }
+   ]
 ----
+<1> Specify a name for the priority.
+<2> Specify a weight from 1 (bad fit) to 10 (best fit).
+<3> Specify a label for matching.
 
-[[scheduler-policy]]
-== Scheduler Policy
-The selection of the predicate and priority functions defines the policy for the
-scheduler. Administrators can provide a JSON file that specifies the predicates
-and priority functions to configure the scheduler. The path to the scheduler
-policy file can be specified in the master configuration file. In the absence of
-the scheduler policy file, the default configuration gets applied.
-
-It is important to note that the predicates and priority functions defined in
-the scheduler configuration file completely override the default scheduler
-policy. If any of the default predicates and priority functions are required,
-they have to be explicitly specified in the scheduler configuration file.
-
-[[default-scheduler-policy]]
-=== Default Scheduler Policy
-The default scheduler policy includes the following predicates:
-
-. NoVolumeZoneConflict
-. MaxEBSVolumeCount
-. MaxGCEPDVolumeCount
-. MatchInterPodAffinity
-. NoDiskConflict
-. GeneralPredicates
-. PodToleratesNodeTaints
-. CheckNodeMemoryPressure
-. CheckNodeDiskPressure
-
-The default scheduler policy includes the following priority functions. Each of
-the priority function has a weight of `1` except `*NodePreferAvoidPodsPriority*`,
-which has a weight of `10000`:
+For example:
 
-. SelectorSpreadPriority
-. InterPodAffinityPriority
-. LeastRequestedPriority
-. BalancedResourceAllocation
-. NodePreferAvoidPodsPriority
-. NodeAffinityPriority
-. TaintTolerationPriority
+[source,json]
+----
+         "name":"RackSpread",
+         "weight" : "1"
+         "argument":{
+            "serviceAffinity":{
+               "labels":[
+                  "rack"
+----
 
-[[modifying-scheduler-policy]]
-=== Modifying Scheduler Policy
+**_LabelPreference_** prefers nodes that have a particular label defined,
+regardless of its value.
 
-The scheduler policy is defined in a file on the master,
-named *_/etc/origin/master/scheduler.json_* by default,
-unless overridden by the `kubernetesMasterConfig.schedulerConfigFile`
-field in the
-xref:../../install_config/master_node_configuration.adoc#master-configuration-files[master configuration file].
+[source,json]
+----
+"predicates":[
+      {
+         "name":"<name>", <1>
+         "weight" : "1" <2>
+         "argument":{
+            "labelsPresence":{
+               "labels":[
+                  "<label>" <3>
+                presence: true/false
+               ]
+            }
+         }
+      }
+   ],
+----
+<1> Specify a name for the priority.
+<2> Specify a weight from 1 (bad fit) to 10 (best fit).
+<3> Specify a label for matching.
+<4> Specify whether the labels are required.
++
+* For `presence:false`, if any of the requested labels are present in the node labels,
+the pod cannot be scheduled. If the labels are not present, the pod can be scheduled.
++
+* For `presence:true`, if all of the requested labels are present in the node labels,
+the pod can be scheduled. If all of the lables are not present, the pod is not scheduled.
 
-To modify the scheduler policy:
+For example:
 
-. Edit the scheduler configuration file to set the desired
-xref:default-scheduler-policy[predicates and priority functions].
-You can create a custom configuration, or modify one of the
-xref:scheduler-sample-policies[sample policy configurations].
+[source,json]
+----
+         "name":"RackPreferred",
+         "weight" : "1"
+         "argument":{
+            "labelsPresence":{
+               "labels":[
+                  "rack"
+----
 
-. Restart the {product-title}
-xref:../../install_config/master_node_configuration.adoc#launching-servers-using-configuration-files[master services]
-for the changes to take effect.
 
 [[use-cases]]
 == Use Cases
+
 One of the important use cases for scheduling within {product-title} is to support
 flexible affinity and anti-affinity policies.
-
 ifdef::openshift-enterprise,openshift-origin[]
 
 [[infrastructure-topological-levels]]
 === Infrastructure Topological Levels
+
 Administrators can define multiple topological levels for their infrastructure
-(nodes).
-This is done by specifying
+(nodes) by specifying
 xref:../../admin_guide/manage_nodes.adoc#updating-labels-on-nodes[labels on nodes]
 (e.g., `region=r1`, `zone=z1`, `rack=s1`).
+
 These label names have no particular meaning and
 administrators are free to name their infrastructure levels anything
 (eg, city/building/room). Also, administrators can define any number of levels
 for their infrastructure topology, with three levels usually being adequate
-(eg. regions -> zones -> racks).  Lastly, administrators can specify affinity
+(such as: `regions` -> `zones` -> `racks`).  Administrators can specify affinity
 and anti-affinity rules at each of these levels in any combination.
 endif::openshift-enterprise,openshift-origin[]
+
 [[affinity]]
 === Affinity
+
 Administrators should be able to configure the scheduler to specify affinity at
 any topological level, or even at multiple levels. Affinity at a particular
 level indicates that all pods that belong to the same service are scheduled
@@ -294,6 +754,7 @@ to specify which node a pod can be scheduled on and to force or reject schedulin
 
 [[anti-affinity]]
 === Anti Affinity
+
 Administrators should be able to configure the scheduler to specify
 anti-affinity at any topological level, or even at multiple levels.
 Anti-affinity (or 'spread') at a particular level indicates that all pods that
@@ -310,35 +771,45 @@ to specify which node a pod can be scheduled on and to force or reject schedulin
 
 [[scheduler-sample-policies]]
 == Sample Policy Configurations
+
 The configuration below specifies the default scheduler configuration, if it
 were to be specified via the scheduler policy file.
+
 ----
 kind: "Policy"
 version: "v1"
 predicates:
-  - name: "PodFitsPorts"
-  - name: "PodFitsResources"
-  - name: "NoDiskConflict"
-  - name: "MatchNodeSelector"
-  - name: "HostName"
+...
+  - name: "RegionZoneAffinity" <1>
+    argument:
+      serviceAffinity: <2>
+        labels: <3>
+          - "region"
+          - "zone"
 priorities:
-  - name: "LeastRequestedPriority"
-    weight: 1
-  - name: "BalancedResourceAllocation"
-    weight: 1
-  - name: "ServiceSpreadingPriority"
+...
+  - name: "RackSpread" <4>
     weight: 1
+    argument:
+      serviceAntiAffinity: <5>
+        label: "rack" <6>
 ----
 
-[IMPORTANT]
-====
+<1> The name for the predicate.
+<2> The xref:available-predicates[type of predicate].
+<3> The labels for the predicate.
+<4> The name for the priority.
+<5> The xref:available-priority-functions[type of priority].
+<6> The labels for the priority.
+
 In all of the sample configurations below, the list of predicates and priority
 functions is truncated to include only the ones that pertain to the use case
 specified.  In practice, a complete/meaningful scheduler policy should include
-most, if not all, of the default predicates and priority functions listed above.
-====
+most, if not all, of the default predicates and priorities listed above.
 
-Three topological levels defined as region (affinity) --> zone (affinity) --> rack (anti-affinity)
+The following example defines three topological levels, region (affinity) -> zone (affinity) -> rack (anti-affinity):
+
+[source,yaml]
 ----
 kind: "Policy"
 version: "v1"
@@ -359,8 +830,10 @@ priorities:
         label: "rack"
 ----
 
-Three topological levels defined as city (affinity) -> building
+The following example defines three topological levels, city (affinity) -> building
 (anti-affinity) -> room (anti-affinity):
+
+[source,yaml]
 ----
 kind: "Policy"
 version: "v1"
@@ -385,8 +858,10 @@ priorities:
         label: "room"
 ----
 
-Only use nodes with the 'region' label defined and prefer nodes with the 'zone'
+The following example defines a policy to only use nodes with the 'region' label defined and prefer nodes with the 'zone'
 label defined:
+
+[source,yaml]
 ----
 kind: "Policy"
 version: "v1"
@@ -408,8 +883,10 @@ priorities:
         presence: true
 ----
 
-Configuration example combining static and configurable predicates and
-priority functions:
+The following example combines both static and configurable predicates and
+also priorities:
+
+[source,yaml]
 ----
 kind: "Policy"
 version: "v1"
@@ -452,405 +929,3 @@ priorities:
 
 ----
 
-[[scheduler-extensibility]]
-== Scheduler Extensibility
-As is the case with almost everything else in Kubernetes/{product-title}, the
-scheduler is built using a plug-in model and the current implementation itself
-is a plug-in. There are two ways to extend the scheduler functionality:
-
-* Enhancements
-* Replacement
-
-[[enhancements]]
-=== Enhancements
-The scheduler functionality can be enhanced by adding new predicates and
-priority functions. They can either be contributed upstream or maintained
-separately. These predicates and priority functions would need to be registered
-with the scheduler factory and then specified in the scheduler policy file.
-
-[[replacement]]
-=== Replacement
-Since the scheduler is a plug-in, it can be replaced in favor of an alternate
-implementation. The scheduler code has a clean separation that watches new pods
-as they get created and identifies the most suitable node to host them. It then
-creates bindings (pod to node bindings) for the pods using the master API.
-
-[[controlling-pod-placement]]
-== Controlling Pod Placement
-
-As a cluster administrator, you can set a policy to prevent application
-developers with certain roles from targeting specific nodes when scheduling
-pods.
-
-[IMPORTANT]
-====
-This process involves the *pods/binding* permission
-xref:../../admin_guide/manage_authorization_policy.adoc#admin-guide-manage-authorization-policy[role], which is needed to
-target particular nodes. The constraint on the use of the `nodeSelector` field
-of a pod configuration is based on the *pods/binding* permission and the
-`nodeSelectorLabelBlacklist` configuration option.
-====
-
-The `nodeSelectorLabelBlacklist` field of a master configuration file gives you
-control over the labels that certain roles can specify in a pod configuration's
-`nodeSelector` field. Users, service accounts, and groups that have the
-*pods/binding* permission can specify any node selector. Those without the
-*pods/binding* permission are prohibited from setting a `nodeSelector` for any
-label that appears in `nodeSelectorLabelBlacklist`.
-
-As a hypothetical example, an {product-title} cluster might consist of five data
-centers spread across two regions. In the U.S., "us-east", "us-central", and
-"us-west"; and in the Asia-Pacific region (APAC), "apac-east" and "apac-west".
-Each node in each geographical region is labeled accordingly. For example,
-`region: us-east`.
-ifdef::openshift-enterprise,openshift-origin[]
-[NOTE]
-====
-See xref:../../admin_guide/manage_nodes.adoc#updating-labels-on-nodes[Updating
-Labels on Nodes] for details on assigning labels.
-====
-endif::openshift-enterprise,openshift-origin[]
-
-As a cluster administrator, you can create an infrastructure where application
-developers should be deploying pods only onto the nodes closest to their
-geographical location. You can
-xref:../../admin_guide/managing_projects.adoc#using-node-selectors[create a node
-selector], grouping the U.S. data centers into `superregion: us` and the APAC
-data centers into `superregion: apac`.
-
-To maintain an even loading of resources per data center, you can add the
-desired `region` to the `nodeSelectorLabelBlacklist` section of a master
-configuration. Then, whenever a developer located in the U.S. creates a pod, it
-is deployed onto a node in one of the regions with the `superregion: us` label.
-If the developer tries to target a specific region for their pod (for example,
-`region: us-east`), they receive an error. If they try again, without the
-node selector on their pod, it can still be deployed onto the region they tried
-to target, because `superregion: us` is set as the project-level node selector,
-and nodes labeled `region: us-east` are also labeled `superregion: us`.
-
-[[constraining-pod-placement-labels]]
-=== Constraining Pod Placement Using Node Name
-
-Ensure a pod is deployed onto only a specified node host by assigning it a label
-and specifying this in the `nodeName` setting in a pod configuration.
-
-. Ensure you have the desired labels and
-xref:../../admin_guide/managing_projects.adoc#using-node-selectors[node selector]
-set up in your environment.
-+
-For example, make sure that your pod configuration features the `nodeName`
-value indicating the desired label:
-+
-----
-apiVersion: v1
-kind: Pod
-spec:
-  nodeName: <value>
-----
-
-. Modify the master configuration file
-(*_/etc/origin/master/master-config.yaml_*) in two places:
-+
-.. Add `nodeSelectorLabelBlacklist` to the `admissionConfig` section:
-+
-====
-----
-...
-admissionConfig:
-  pluginConfig:
-    PodNodeConstraints:
-      configuration:
-        apiversion: v1
-        kind: PodNodeConstraintsConfig
-...
-----
-====
-
-.. Then, add the same to the `kubernetesMasterConfig` section to restrict direct pod creation:
-+
-====
-----
-...
-kubernetesMasterConfig:
-  admissionConfig:
-    pluginConfig:
-      PodNodeConstraints:
-        configuration:
-          apiVersion: v1
-          kind: PodNodeConstraintsConfig
-...
-----
-====
-
-. Restart {product-title} for the changes to take effect.
-+
-ifdef::openshift-origin[]
-----
-# systemctl restart origin-master-api origin-master-controllers
-----
-endif::[]
-ifdef::openshift-enterprise[]
-----
-# systemctl restart atomic-openshift-master-api atomic-openshift-master-controllers
-
-----
-endif::[]
-
-
-[[constraining-pod-placement-nodeselector]]
-=== Constraining Pod Placement Using a Node Selector
-
-
-Using `nodeSelector` in a pod configuration, you can ensure that pods are only
-placed onto nodes with specific labels.
-
-
-. Ensure you have the desired labels
-ifdef::openshift-enterprise,openshift-origin[]
-(see xref:../../admin_guide/manage_nodes.adoc#updating-labels-on-nodes[Updating
-Labels on Nodes] for details)
-endif::openshift-enterprise,openshift-origin[]
-ifdef::openshift-dedicated[]
-(request changes by opening a support case on the
-https://access.redhat.com/support/[Red Hat Customer Portal])
-endif::openshift-dedicated[]
-and xref:../../admin_guide/managing_projects.adoc#using-node-selectors[node selector]
-set up in your environment.
-//tag::node-selectors[]
-+
-For example, make sure that your pod configuration features the `nodeSelector`
-value indicating the desired label:
-+
-----
-apiVersion: v1
-kind: Pod
-spec:
-  nodeSelector:
-    <key>: <value>
-...
-----
-
-. Modify the master configuration file
-(*_/etc/origin/master/master-config.yaml_*) in two places:
-+
-.. Add `nodeSelectorLabelBlacklist` to the `admissionConfig` section with
-the labels that are assigned to the node hosts you want to deny pod placement:
-+
-====
-----
-...
-admissionConfig:
-  pluginConfig:
-    PodNodeConstraints:
-      configuration:
-        apiversion: v1
-        kind: PodNodeConstraintsConfig
-        nodeSelectorLabelBlacklist:
-          - kubernetes.io/hostname
-          - <label>
-...
-----
-====
-
-.. Then, add the same to the `kubernetesMasterConfig` section to restrict direct pod creation:
-+
-====
-----
-...
-kubernetesMasterConfig:
-  admissionConfig:
-    pluginConfig:
-      PodNodeConstraints:
-        configuration:
-          apiVersion: v1
-          kind: PodNodeConstraintsConfig
-          nodeSelectorLabelBlacklist:
-            - kubernetes.io/hostname
-            - <label_1>
-...
-----
-====
-
-. Restart {product-title} for the changes to take effect.
-+
-ifdef::openshift-origin[]
-----
-# systemctl restart origin-master-api origin-master-controllers
-----
-endif::[]
-ifdef::openshift-enterprise[]
-----
-# systemctl restart atomic-openshift-master-api atomic-openshift-master-controllers
-----
-endif::[]
-
-//end::node-selectors[]
-== Control Pod Placement to Projects
-
-The _Pod Node Selector_ admission controller allows you to force pods onto nodes associated with a specific project and prevent pods from being scheduled in those nodes. 
-
-The *Pod Node Selector* admission controller determines where a pod can be placed using xref:../../architecture/core_concepts/pods_and_services.adoc#labels[labels on projects] and node selectors specified in pods. A new pod will be placed on a node associated with a project  only if the node selectors in the pod match the labels in the project. 
-
-After the pod is created, the node selectors are merged into the pod so that the pod specification includes the labels originally included in the specification and any new labels from the node selectors. The example below illustrates the merging effect.  
-
-The *Pod Node Selector* admission controller also allows you to create a list of labels that are permitted in a specific project. This list acts as a _whitelist_ that lets developers know what labels are acceptable to use in a project and gives administrators greater control over labeling in a cluster.
-
-To activate the *Pod Node Selector* admission controller, add the following to the master configuration file (*_/etc/origin/master/master-config.yaml_*) or create a file and reference the file in the master configuration:
-
-.Master configuration file with the *Pod Node Selector* admission controller and whitelist
-----
-admissionConfig:
-  pluginConfig:
-    PodNodeSelector:
-      configuration:
-        podNodeSelectorPluginConfig: <1>
-          clusterDefaultNodeSelector: "k3=v3" <2>
-          ns1: region=west,env=test,infra=fedora,os=fedora <2>
-----
-
-<1> Adds the *Pod Node Selector* admission controller plug-in.
-<2> Creates default labels for all nodes. 
-<3> Creates a whitelist of permitted labels in the specified project. Here, the project is `ns1` and the labels are the `key=value` pairs that follow.
-
-Alternatively, create a file containing the admission controller information:
-
-----
-podNodeSelectorPluginConfig:
-    clusterDefaultNodeSelector: "k3=v3"
-     ns1: region=west,env=test,infra=fedora,os=fedora
-----
-
-Then, reference the file in the master configuration:
-
-----
-admissionConfig:
-  pluginConfig:
-    PodNodeSelector:
-      location: <path-to-file>
-----
-
-
-[NOTE]
-====
-If a project does not have a node selectors specified, the pods associated with that project will be merged with the using the default node selector (`clusterDefaultNodeSelector`).
-====
-
-To schedule pods onto specific project nodes:
-
-. Activate the *Pod Node Selector* admission controller:
-+
-.. Modify the master configuration file (*_/etc/origin/master/master-config.yaml_*) to add the admission controller plug-in and labels:
-+
-----
-admissionConfig:
-  pluginConfig:
-    PodNodeSelector:
-      configuration:
-        podNodeSelectorPluginConfig:
-          clusterDefaultNodeSelector: "k3=v3" 
-          ns1: region=west,env=test,infra=fedora,os=fedora 
-----
-
-. Restart {product-title} for the changes to take effect.
-ifdef::openshift-origin[]
-+
-----
-# systemctl restart origin-master-api origin-master-controllers
-----
-endif::[]
-ifdef::openshift-enterprise[]
-+
-----
-# systemctl restart atomic-openshift-master-api atomic-openshift-master-controllers
-----
-endif::[]
-
-
-. Create a project object that includes the 
-`scheduler.alpha.kubernetes.io/node-selector` annotation and labels. 
-+
-----
-{
-    "kind": "Namespace",
-    "apiVersion": "v1",
-    "metadata": {
-        "name": "ns1",
-        "annotations": {
-            "scheduler.alpha.kubernetes.io/node-selector": "env=test,infra=fedora" <1>
-        }
-    },
-    "spec": {},
-    "status": {}
-}
-
-----
-+
-<1> Annotation to create the labels to match the project label selector. Here, the key/value labels are `env=test` and `infra=fedora`.
-
-. Create a pod specification that includes the labels in the node selector, for example:
-+
-----
-apiVersion: v1
-kind: Pod
-metadata:
-  labels:
-    name: hello-pod
-  name: hello-pod
-spec:
-  containers:
-    - image: "docker.io/ocpqe/hello-pod:latest"
-      imagePullPolicy: IfNotPresent
-      name: hello-pod
-      ports:
-        - containerPort: 8080
-          protocol: TCP
-      resources: {}
-      securityContext:
-        capabilities: {}
-        privileged: false
-      terminationMessagePath: /dev/termination-log
-  dnsPolicy: ClusterFirst
-  restartPolicy: Always
-  nodeSelector: <1>
-    env: test
-    os: fedora
-  serviceAccount: ""
-status: {}
-----
-+
-<1> Node selectors to match project labels.
-
-
-. Create the pod in the project:
-+
-----
-oc create -f pod.yaml --namespace=ns1
-----
-
-. Check that the node selector labels were added to the pod configuration:
-+
-----
-get pod pod1 --namespace=ns1 -o json
-
-nodeSelector": {
- "env": "test",
- "infra": "fedora",
- "os": "fedora"
-}
-----
-+
-The node selectors are merged into the pod and the pod should be scheduled in the appropriate project.
-
-If you create a pod with a label that is not specified in the project specification, the pod is not scheduled on the node. 
-
-For example, here the label `env: production` is not in any project specification:
-
-----
-nodeSelector:
- "env: production"
- "infra": "fedora",
- "os": "fedora"
-----
-
-If there is a node that does not have a node selector annotation, the pod will be scheduled there. 
-
diff --git a/architecture/additional_concepts/admission_controllers.adoc b/architecture/additional_concepts/admission_controllers.adoc
index 8dd24c26cf8a..508ba824c620 100644
--- a/architecture/additional_concepts/admission_controllers.adoc
+++ b/architecture/additional_concepts/admission_controllers.adoc
@@ -116,7 +116,10 @@ certain behavior, such as:
 - xref:../../admin_guide/managing_projects.adoc#limit-projects-per-user[Limiting Number of Self-Provisioned Projects Per User]
 ifdef::openshift-enterprise,openshift-origin[]
 - xref:../../install_config/build_defaults_overrides.adoc#install-config-build-defaults-overrides[Configuring Global Build Defaults and Overrides]
-- xref:../../admin_guide/scheduling/scheduler.adoc#controlling-pod-placement[Controlling Pod Placement]
+endif::[]
+ifdef::openshift-enterprise,openshift-origin[]
+- xref:../../admin_guide/scheduling/pod_placement#controlling-pod-placement[Controlling Pod Placement]
+endif::[]
 - xref:../../admin_solutions/user_role_mgmt.adoc#role-binding-restriction[Restricting Role Bindings]
 
 [[admission-controllers-using-containers]]
@@ -125,4 +128,5 @@ ifdef::openshift-enterprise,openshift-origin[]
 Admission controllers using containers also support
 xref:../../architecture/core_concepts/containers_and_images.adoc#init-containers[init
 containers].
-endif::[]
\ No newline at end of file
+endif::[]
+
diff --git a/welcome/revhistory_full.adoc b/welcome/revhistory_full.adoc
index 6a8f09b0ac5e..36d492ab4427 100644
--- a/welcome/revhistory_full.adoc
+++ b/welcome/revhistory_full.adoc
@@ -11,6 +11,10 @@ date.
 
 // do-release: revhist-tables
 
+== Fri Feb 23 2018
+.Cluster Administration
+include::admin_guide/revhistory_admin_guide.adoc[tag=admin_guide_fri_feb_23_2018]
+
 == Wed Feb 21 2018
 .Installation and Configuration
 include::install_config/revhistory_install_config.adoc[tag=install_config_wed_feb_21_2018]