WIP: tighten identifier spec 

DO NOT MERGE YET

There are still a couple open questions.  As I read through it I wanted to wordsmith a bit, which lead to reordering some to read sort of top-down.  There were a couple things I thought were wrong (pod name should be a subdomain) and a few things I think we can make more concise.  I also added examples and clarifies corollaries.

@smarterclayton in particular


How would someone use the POD_GENERATION identifier?  Would the kubelet use it to report "this thing, which I thought was scheduled for me back when we were at generation 2, is no longer on me"?  Is POD_GENERATION really just the pod version identifier?  If a pod can be updated, you need to be able to know what the version you have persisted efficiently.

I think the use cases for these are identifier use cases, not name use cases - the system is assigning guaranteed unique values to distinguish system level interactions.  Names are more about propagating a human usable value throughout the system, and making it easy as a consumer to label or relabel something that already exists (should names be changeable over time?  argue yes if it's intended to be useful for humans).

So in OpenShift we inject variables like the following above into the container each time.  The problem is when folks start to depend on them for a usecase (say, to choose the default name for a database that is unique).  Then their code/image becomes coupled to a particular system.  I think there's value in resisting the urge to inject the environment until you absolutely need it, and then when you do, you probably want to let the apiserver client define the mapping (so instead of just exposing KUBE_POD_ID into the container, let the client specify in the manifest that FOO_VAR=$KUBERNETES_POD_ID).  That allows a consumer to utilize the value but forces them to make the decision to map the value to something useful.