Merge pull request #33752 from justinsb/labels_annotations_and_taints_ohmy

Automatic merge from submit-queue

Start a doc for well-known labels & taints

docs/api-reference/labels-annotations-taints.md

@@ -0,0 +1,140 @@
+<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
+
+<!-- BEGIN STRIP_FOR_RELEASE -->
+
+<img src="http://kubernetes.io/kubernetes/img/warning.png" alt="WARNING"
+     width="25" height="25">
+<img src="http://kubernetes.io/kubernetes/img/warning.png" alt="WARNING"
+     width="25" height="25">
+<img src="http://kubernetes.io/kubernetes/img/warning.png" alt="WARNING"
+     width="25" height="25">
+<img src="http://kubernetes.io/kubernetes/img/warning.png" alt="WARNING"
+     width="25" height="25">
+<img src="http://kubernetes.io/kubernetes/img/warning.png" alt="WARNING"
+     width="25" height="25">
+
+<h2>PLEASE NOTE: This document applies to the HEAD of the source tree</h2>
+
+If you are using a released version of Kubernetes, you should
+refer to the docs that go with that version.
+
+Documentation for other releases can be found at
+[releases.k8s.io](http://releases.k8s.io).
+</strong>
+--
+
+<!-- END STRIP_FOR_RELEASE -->
+
+<!-- END MUNGE: UNVERSIONED_WARNING -->
+
+# Well-Known Labels, Annotations and Taints
+
+Kubernetes reserves all labels and annotations in the kubernetes.io namespace.  This document describes
+the well-known kubernetes.io labels and annotations.
+
+This document serves both as a reference to the values, and as a coordination point for assigning values.
+
+**Table of contents:**
+<!-- BEGIN MUNGE: GENERATED_TOC -->
+
+- [Well-Known Labels, Annotations and Taints](#well-known-labels-annotations-and-taints)
+  - [beta.kubernetes.io/arch](#betakubernetesioarch)
+  - [beta.kubernetes.io/os](#betakubernetesioos)
+  - [kubernetes.io/hostname](#kubernetesiohostname)
+  - [beta.kubernetes.io/instance-type](#betakubernetesioinstance-type)
+  - [failure-domain.beta.kubernetes.io/region](#failure-domainbetakubernetesioregion)
+  - [failure-domain.beta.kubernetes.io/zone](#failure-domainbetakubernetesiozone)
+
+<!-- END MUNGE: GENERATED_TOC -->
+
+
+## beta.kubernetes.io/arch
+
+Example: `beta.kubernetes.io/arch=amd64`
+
+Used on: Node
+
+Kubelet populates this with `runtime.GOARCH` as defined by Go.  This can be handy if you are mixing arm and x86 nodes,
+for example.
+
+## beta.kubernetes.io/os
+
+Example: `beta.kubernetes.io/os=linux`
+
+Used on: Node
+
+Kubelet populates this with `runtime.GOOS` as defined by Go.  This can be handy if you are mixing operating systems
+in your cluster (although currently Linux is the only OS supported by kubernetes).
+
+## kubernetes.io/hostname
+
+Example: `kubernetes.io/hostname=ip-172-20-114-199.ec2.internal`
+
+Used on: Node
+
+Kubelet populates this with the hostname.  Note that the hostname can be changed from the "actual" hostname
+by passing the `--hostname-override` flag to kubelet.
+
+## beta.kubernetes.io/instance-type
+
+Example: `beta.kubernetes.io/instance-type=m3.medium`
+
+Used on: Node
+
+Kubelet populates this with the instance type as defined by the `cloudprovider`.  It will not be set if
+not using a cloudprovider.  This can be handy if you want to target certain workloads to certain instance
+types, but typically you want to rely on the kubernetes scheduler to perform resource-based scheduling,
+and you should aim to schedule based on properties rather than on instance types (e.g. require a GPU, instead
+of requiring a `g2.2xlarge`)
+
+
+## failure-domain.beta.kubernetes.io/region
+
+See [failure-domain.beta.kubernetes.io/zone](#failure-domainbetakubernetesiozone)
+
+## failure-domain.beta.kubernetes.io/zone
+
+Example:
+
+`failure-domain.beta.kubernetes.io/region=us-east-1`
+
+`failure-domain.beta.kubernetes.io/zone=us-east-1c`
+
+Used on: Node, PersistentVolume
+
+On the Node: Kubelet populates this with the zone information as defined by the `cloudprovider`.  It will not be set if
+not using a `cloudprovider`, but you should consider setting it on the nodes if it makes sense in your topology.
+
+On the PersistentVolume: The `PersistentVolumeLabel` admission controller will automatically add zone labels to PersistentVolumes,
+on GCE and AWS.
+
+Kubernetes will automatically spread the pods in a replication controller or service across nodes in a single-zone
+cluster (to reduce the impact of failures.) With multiple-zone clusters, this spreading behaviour is extended
+across zones (to reduce the impact of zone failures.) This is achieved via SelectorSpreadPriority.
+
+This is a best-effort placement, and so if the zones in your cluster are heterogeneous (e.g. different numbers of nodes,
+different types of nodes, or different pod resource requirements), this might prevent equal spreading of
+your pods across zones. If desired, you can use homogenous zones (same number and types of nodes) to reduce
+the probability of unequal spreading.
+
+The scheduler (via the VolumeZonePredicate predicate) will also ensure that pods that claim a given volume
+are only placed into the same zone as that volume, as volumes cannot be attached across zones.
+
+
+The actual values of zone and region don't matter, and nor is the meaning of the hierarchy rigidly defined.  The expectation
+is that failures of nodes in different zones should be uncorrelated unless the entire region has failed.  For example,
+zones should typically avoid sharing a single network switch.  The exact mapping depends on your particular
+infrastructure - a three-rack installation will choose a very different setup to a multi-datacenter configuration.
+
+If `PersistentVolumeLabel` does not support automatic labeling of your PersistentVolumes, you should consider
+adding the labels manually (or adding support to `PersistentVolumeLabel`), if you want the scheduler to prevent
+pods from mounting volumes in a different zone.  If your infrastructure doesn't have this constraint, you don't
+need to add the zone labels to the volumes at all.
+
+
+
+
+
+<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
+[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/api-reference/labels-annotations-taints.md?pixel)]()
+<!-- END MUNGE: GENERATED_ANALYTICS -->