From eb562c04be94cbb7777ea744caf4d123c7e5869f Mon Sep 17 00:00:00 2001
From: Cole Mickens <cole.mickens@gmail.com>
Date: Tue, 27 Feb 2018 11:48:46 -0800
Subject: [PATCH] promote PodNodeSelector to stable; document detailed behavior
 (#7134)

* promote PodNodeSelector to stable; document detailed behavior

* respond to feedback
---
 docs/admin/admission-controllers.md | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/docs/admin/admission-controllers.md b/docs/admin/admission-controllers.md
index 488062af63..7d61cf1015 100644
--- a/docs/admin/admission-controllers.md
+++ b/docs/admin/admission-controllers.md
@@ -434,7 +434,7 @@ This admission controller defaults and limits what node selectors may be used wi
 
 #### Configuration File Format
 
-PodNodeSelector uses a configuration file to set options for the behavior of the backend.
+`PodNodeSelector` uses a configuration file to set options for the behavior of the backend.
 Note that the configuration file format will move to a versioned file in a future release.
 This file may be json or yaml and has the following format:
 
@@ -445,7 +445,7 @@ podNodeSelectorPluginConfig:
  namespace2: <node-selectors-labels>
 ```
 
-Reference the PodNodeSelector configuration file from the file provided to the API server's command line flag `--admission-control-config-file`:
+Reference the `PodNodeSelector` configuration file from the file provided to the API server's command line flag `--admission-control-config-file`:
 
 ```yaml
 kind: AdmissionConfiguration
@@ -457,7 +457,7 @@ plugins:
 ```
 
 #### Configuration Annotation Format
-PodNodeSelector uses the annotation key `scheduler.alpha.kubernetes.io/node-selector` to assign node selectors to namespaces.
+`PodNodeSelector` uses the annotation key `scheduler.kubernetes.io/node-selector` to assign node selectors to namespaces.
 
 ```yaml
 apiVersion: v1
@@ -468,6 +468,19 @@ metadata:
   name: namespace3
 ```
 
+#### Internal Behavior
+This admission controller has the following behavior:
+  1. If the `Namespace` has an annotation with a key `scheduler.kubernetes.io/nodeSelector`, use its value as the
+     node selector.
+  1. If the namespace lacks such an annotation, use the `clusterDefaultNodeSelector` defined in the `PodNodeSelector`
+     plugin configuration file as the node selector.
+  1. Evaluate the pod's node selector against the namespace node selector for conflicts. Conflicts result in rejection.
+  1. Evaluate the pod's node selector against the namespace-specific whitelist defined the plugin configuration file.
+     Conflicts result in rejection.
+
+**Note:** `PodTolerationRestriction` is more versatile and powerful than `PodNodeSelector` and can encompass the scenarios supported by `PodNodeSelector`.
+{: .note}
+
 ### PersistentVolumeClaimResize
 
 This admission controller implements additional validations for checking incoming `PersistentVolumeClaim` resize requests.