Update user-guide/node-selection/index.md to include pod affinity/anti-affinity

docs/user-guide/node-selection/index.md

@@ -1,16 +1,33 @@
 ---
 assignees:
-- dchen1107
-- eparis
-- mikedanese
+- davidopp
+- kevin-wangzefeng
 
 ---
 
-This example shows how to assign a [pod](/docs/user-guide/pods/) to a specific [node](/docs/admin/node/) or to one of a set of nodes using node labels and the nodeSelector field in a pod specification. Generally this is unnecessary, as the scheduler will take care of things for you, but you may want to do so in certain circumstances like to ensure that your pod ends up on a machine with an SSD attached to it.
+# Constraining pods to run on particular nodes
 
-You can find all the files for this example [in our docs
+You can constrain a [pod](/docs/user-guide/pods/) to only be able to run on particular [nodes](/docs/admin/node/) or to prefer to
+run on particular nodes. There are several ways to do this, and they all use
+[label selectors](/docs/user-guide/labels/) to make the selection.
+Generally such constraints are unnecessary, as the scheduler will automatically do a reasonable placement
+(e.g. spread your pods across nodes, not place the pod on a node with insufficient free resources, etc.)
+but there are some circumstances where you may want more control where a pod lands, e.g. to ensure
+that a pod ends up on a machine with an SSD attached to it, or to co-locate pods from two different
+services that communicate a lot into the same availability zone.
+
+You can find all the files for these examples [in our docs
 repo here](https://github.com/kubernetes/kubernetes.github.io/tree/{{page.docsbranch}}/docs/user-guide/node-selection).
 
+## nodeSelector
+
+`nodeSelector` is the simplest form of constraint.
+`nodeSelector` is a field of PodSpec. It specifies a map of key-value pairs. For the pod to be eligible
+to run on a node, the node must have each of the indicated key-value pairs as labels (it can have
+additional labels as well). The most common usage is one key-value pair.
+
+Let's walk through an example of how to use `nodeSelector`.
+
 ### Step Zero: Prerequisites
 
 This example assumes that you have a basic understanding of Kubernetes pods and that you have [turned up a Kubernetes cluster](https://github.com/kubernetes/kubernetes#documentation).
@@ -50,26 +67,58 @@ Then add a nodeSelector like so:
 
 When you then run `kubectl create -f pod.yaml`, the pod will get scheduled on the node that you attached the label to! You can verify that it worked by running `kubectl get pods -o wide` and looking at the "NODE" that the pod was assigned to.
 
-#### Alpha feature in Kubernetes v1.2: Node Affinity
+## Interlude: built-in node labels
+
+In addition to labels you [attach yourself](#step-one-attach-label-to-the-node), nodes come pre-populated
+with a standard set of labels. As of Kubernetes v1.4 these labels are
+
+* `kubernetes.io/hostname`
+* `failure-domain.beta.kubernetes.io/zone`
+* `failure-domain.beta.kubernetes.io/region`
+* `beta.kubernetes.io/instance-type`
+* `beta.kubernetes.io/os`
+* `beta.kubernetes.io/arch`
+
+## Alpha features: affinity and anti-affinity
+
+`nodeSelector` provides a very simple way to constrain pods to nodes with particular labels. The affinity/anti-affinity
+feature, currently in alpha, greatly expands the types of constraints you can express. The key enhancements are
+
+1. the language is more expressive (not just "AND of exact match")
+1. you can indicate that the rule is "soft"/"preference" rather than a hard requirement, so if the scheduler
+can't satisfy it, the pod will still be scheduled
+1. you can constrain against labels on other pods running on the node (or other topological domain),
+rather than against labels on the node itself, which allows rules about which pods can and cannot be co-located 
+
+The affinity feature consists of two types of affinity, "node affinity" and "inter-pod affinity/anti-affinity."
+Node affinity is like the existing `nodeSelector` (but with the first two benefits listed above),
+while inter-pod affinity/anti-affinity constrains against pod labels rather than node labels, as
+described in the three item listed above, in addition to having the first and second properties listed above.
+
+`nodeSelector` continues to work as usual, but will eventually be deprecated, as node affinity can express
+everything that `nodeSelector` can express.
+
+### Node affinity (alpha feature)
 
-During the first half of 2016 we are rolling out a new mechanism, called *affinity* for controlling which nodes your pods wil be scheduled onto.
-Like `nodeSelector`, affinity is based on labels. But it allows you to write much more expressive rules.
-`nodeSelector` wil continue to work during the transition, but will eventually be deprecated.
+Node affinity was introduced in Kubernetes 1.2.
+Node affinity is conceptually similar to `nodeSelector` -- it allows you to constrain which nodes your
+pod is eligible to schedule on, based on labels on the node.
 
-Kubernetes v1.2 offers an alpha version of the first piece of the affinity mechanism, called [node affinity](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/nodeaffinity.md).
 There are currently two types of node affinity, called `requiredDuringSchedulingIgnoredDuringExecution` and
 `preferredDuringSchedulingIgnoredDuringExecution`. You can think of them as "hard" and "soft" respectively,
 in the sense that the former specifies rules that *must* be met for a pod to schedule onto a node (just like
 `nodeSelector` but using a more expressive syntax), while the latter specifies *preferences* that the scheduler
 will try to enforce but will not guarantee. The "IgnoredDuringExecution" part of the names means that, similar
-to how `nodeSelector` works, if labels on a node change at runtime such that the rules on a pod are no longer
+to how `nodeSelector` works, if labels on a node change at runtime such that the affinity rules on a pod are no longer
 met, the pod will still continue to run on the node. In the future we plan to offer
 `requiredDuringSchedulingRequiredDuringExecution` which will be just like `requiredDuringSchedulingIgnoredDuringExecution`
 except that it will evict pods from nodes that cease to satisfy the pods' node affinity requirements.
 
-Node affinity is currently expressed using an annotation on Pod. After the release of 1.4, node affinity will use a field, and it will introduce an additional option for affinity called "pod affinity",
-which allows you to control whether a pod schedules onto a particular node based on which other pods are
-running on the node, rather than the labels on the node.
+Thus an example of `requiredDuringSchedulingIgnoredDuringExecution` would be "only run the pod on nodes with Intel CPUs"
+and an example `preferredDuringSchedulingIgnoredDuringExecution` would be "try to run this set of pods in availability
+zone XYZ, but if it's not possible, then allow some to run elsewhere".
+
+Node affinity is currently expressed using an annotation on Pod. Once the feature goes to GA it will use a field of Pod.
 
 Here's an example of a pod that uses node affinity:
 
@@ -81,20 +130,72 @@ among nodes that meet that criteria, nodes with a label whose key is `another-an
 value is `another-annotation-value` should be preferred.
 
 You can see the operator `In` being used in the example. The new node affinity syntax supports the following operators: `In`, `NotIn`, `Exists`, `DoesNotExist`, `Gt`, `Lt`.
+There is no explicit "node anti-affinity" concept, but `NotIn` and `DoesNotExist` give that behavior.
 
 If you specify both `nodeSelector` and `nodeAffinity`, *both* must be satisfied for the pod
 to be scheduled onto a candidate node.
 
-### Built-in node labels
-
-In addition to labels you [attach yourself](#step-one-attach-label-to-the-node), nodes come pre-populated
-with a standard set of labels. As of Kubernetes v1.2 these labels are
+For more information on node affinity, see the design doc
+[here](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/nodeaffinity.md).
+
+### Inter-pod affinity and anti-affinity (alpha feature)
+
+Inter-pod affinity and anti-affinity were introduced in Kubernetes 1.4.
+Inter-pod affinity and anti-affinity allow you to constrain which nodes your pod is eligible to schedule on *based on
+labels on pods that are already running on the node* rather than based on labels on nodes. The rules are of the form "this pod should (or, in the case of
+anti-affinity, should not) run in an X if that X is already running one or more pods that meet rule Y." Y is expressed
+as a LabelSelector with an associated list of namespaces (or "all" namespaces); unlike nodes, because pods are namespaced
+(and therefore the labels on pods are implicitly namespaced),
+a label selector over pod labels must specify which namespaces the selector should apply to. Conceptually X is a topology domain
+like node, rack, cloud provider zone, cloud provider region, etc. You express it using a `topologyKey` which is the
+key for the node label that the system uses to denote such a topology domain, e.g. see the label keys listed above
+in the section "Interlude: built-in node labels."
+
+As with node affinity, there are currently two types of pod affinity and anti-affinity, called `requiredDuringSchedulingIgnoredDuringExecution` and
+`preferredDuringSchedulingIgnoredDuringExecution` which denote "hard" vs. "soft" requirements.
+See the description in the node affinity section earlier.
+An example of `requiredDuringSchedulingIgnoredDuringExecution` affinity would be "co-locate the pods of service A and service B
+in the same zone, since they communicate a lot with each other"
+and an example `preferredDuringSchedulingIgnoredDuringExecution` anti-affinity would be "spread the pods from this service across zones"
+(a hard requirement wouldn't make sense, since you probably have more pods than zones).
+
+Inter-pod affinity and anti-affinity are currently expressed using an annotation on Pod. Once the feature goes to GA it will use a field.
+
+Here's an example of a pod that uses pod affinity:
+
+{% include code.html language="yaml" file="pod-with-pod-affinity.yaml" ghlink="/docs/user-guide/node-selection/pod-with-pod-affinity.yaml" %}
+
+The affinity annotation on this pod defines one pod affinity rule and one pod anti-affinity rule. Both
+must be satisfied for the pod to schedule onto a node. The
+pod affinity rule says that the pod can schedule onto a node only if that node is in the same zone
+as at least one already-running pod that has a label with key "security" and value "S1". (More precisely, the pod is eligible to run
+on node N if node N has a label with key `failure-domain.beta.kubernetes.io/zone` and some value V
+such that there is at least one node in the cluster with key `failure-domain.beta.kubernetes.io/zone` and
+value V that is running a pod that has a label with key "security" and value "S1".) The pod anti-affinity
+rule says that the pod cannot schedule onto a node if that node is already running a pod with label
+having key "security" and value "S2". (If the `topologyKey` were `failure-domain.beta.kuberntes.io/zone` then
+it would mean that the pod cannot schedule onto a node if that node is in the same zone as a pod with
+label having key "security" and value "S2".) See the [design doc](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/podaffinity.md).
+for many more examples of pod affinity and anti-affinity, both the `requiredDuringSchedulingIgnoredDuringExecution`
+flavor and the `preferredDuringSchedulingIgnoredDuringExecution` flavor.
+
+As with node affinity, the legal operators for pod affinity and anti-affinity are `In`, `NotIn`, `Exists`, `DoesNotExist`, `Gt`, `Lt`.
+
+In principle, the `topologyKey` can be any legal label value. However,
+for performance reasons, only a limit set of topology keys are allowed;
+they are specified in the `--failure-domain` command-line argument to the scheduler. By default the allowed topology keys are
 
 * `kubernetes.io/hostname`
 * `failure-domain.beta.kubernetes.io/zone`
 * `failure-domain.beta.kubernetes.io/region`
-* `beta.kubernetes.io/instance-type`
 
-### Conclusion
+In addition to `labelSelector` and `topologyKey`, you can optionally specify a list `namespaces`
+of namespaces which the `labelSelector` should match against (this goes at the same level of the definition as `labelSelector` and `topologyKey`).
+If omitted, it defaults to the namespace of the pod where the affinity/anti-affinity definition appears.
+If defined but empty, it means "all namespaces."
+
+All `matchExpressions` associated with `requiredDuringSchedulingIgnoredDuringExecution` affinity and anti-affinity
+must be satisfied for the pod to schedule onto a node. 
 
-While this example only covered one node, you can attach labels to as many nodes as you want. Then when you schedule a pod with a nodeSelector, it can be scheduled on any of the nodes that satisfy that nodeSelector. Be careful that it will match at least one node, however, because if it doesn't the pod won't be scheduled at all.
+For more information on inter-pod affinity/anti-affinity, see the design doc
+[here](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/podaffinity.md).

docs/user-guide/node-selection/pod-with-node-affinity.yaml

@@ -1,7 +1,7 @@
 apiVersion: v1
 kind: Pod
 metadata:
-  name: with-labels
+  name: with-node-affinity
   annotations:
     scheduler.alpha.kubernetes.io/affinity: >
       {
@@ -24,5 +24,5 @@ metadata:
     another-annotation-key: another-annotation-value
 spec:
   containers:
-  - name: with-labels
+  - name: with-node-affinity
     image: gcr.io/google_containers/pause:2.0

docs/user-guide/node-selection/pod-with-pod-affinity.yaml

@@ -0,0 +1,44 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: with-pod-affinity
+  annotations:
+    scheduler.alpha.kubernetes.io/affinity: >
+        {
+          "podAffinity": {
+            "requiredDuringSchedulingIgnoredDuringExecution": [
+              {
+                "labelSelector": {
+                  "matchExpressions": [
+                    {
+                      "key": "security",
+                      "operator": "In",
+                      "values": ["S1"]
+                    }
+                  ]
+                },
+                "topologyKey": "failure-domain.beta.kubernetes.io/zone"
+             }
+            ]
+           },
+          "podAntiAffinity": {
+            "requiredDuringSchedulingIgnoredDuringExecution": [
+              {
+                "labelSelector": {
+                  "matchExpressions": [
+                    {
+                      "key": "security",
+                      "operator": "In",
+                      "values": ["S2"]
+                    }
+                  ]
+                },
+                "topologyKey": "kubernetes.io/hostname"
+             }
+            ]
+           }
+         }
+spec:
+  containers:
+  - name: with-pod-affinity
+    image: gcr.io/google_containers/pause:2.0

test/examples_test.go

@@ -272,6 +272,7 @@ func TestExampleObjectSchemas(t *testing.T) {
 		"../docs/user-guide/node-selection": {
 			"pod": &api.Pod{},
 			"pod-with-node-affinity": &api.Pod{},
+			"pod-with-pod-affinity": &api.Pod{},
 		},
 		"../docs/admin/resourcequota": {
 			"best-effort":       &api.ResourceQuota{},