Proposal: v1beta3 API overhaul

Speculative change for some items from #1200:

* Metadata that applies to resources is split from APIMetadata on non-resource API objects
* Metadata is a sub field of objects
* Labels are on Metadata
* Pod current and desired state is split
* Name is used for pods instead of ID (UID is part of metadata, Name is part of resource) for idempotent creation #148 and #1216 
* PodTemplate is a Metadata carrying object as per #170
 * If replicationController gave way to a generic "replicator", then pod template could be both a nested struct and a real resource.
* A ScheduledPod and ScheduledPodList is what the kubelet sees as per #860
* Non-schema'd k/v values on Metadata as `Config` (better names welcome) as per #1201

Not changed yet:

* ReplicationControllers
* Services

EDIT: Moving to higher bandwidth document here: https://docs.google.com/document/d/1E_HNsbyocweD9zJHXbz5Xb9XPwBqvDnLHhGeBq15FlI/edit?usp=sharing
No objections from me on that.  Feels better than the others.

> On Sep 26, 2014, at 7:33 PM, bgrant0607 <notifications@github.com> wrote:
> 
> In pkg/api/v1beta3/types.go:
> 
> >  type Pod struct {
> > -	JSONBase     `json:",inline" yaml:",inline"`
> > -	Labels       map[string]string `json:"labels,omitempty" yaml:"labels,omitempty"`
> > -	DesiredState PodState          `json:"desiredState,omitempty" yaml:"desiredState,omitempty"`
> > -	CurrentState PodState          `json:"currentState,omitempty" yaml:"currentState,omitempty"`
> > +	TypeMeta `json:",inline" yaml:",inline"`
> > +	Metadata ObjectMeta `json:"metadata,omitempty" yaml:"metadata,omitempty"`
> > +
> > +	// Spec defines the behavior of a pod.
> > +	Spec PodSpec `json:"spec,omitempty" yaml:"spec,omitempty"`
> > +
> > +	// Status represents the current information about a pod. This data may not be up
> > +	// to date.
> > +	Status PodStatus `json:"status,omitempty" yaml:"status,omitempty"`
> Observations:
> 
> The Status type, which is used for object-less API responses, also contains a string called Status. It also contains StatusReason and StatusDetails. Because it's a set of closely related fields, aesthetically this looks pretty nice. The pod status fields are less likely to be as closely related. Also, requests are more ephemeral than objects, so "status" makes more sense for this case than any other term I can think of. I don't think we should change them, but I also don't think that this necessarily dictates what we do for pod status.
> 
> The Event type being added in #1354 also contains a Status string. It's not in use yet, so it's mutable.
> 
> We're not using state primarily because of the "pod status is not a state machine" argument, but also because the term is extremely overloaded, and we're moving away from using it everywhere else.
> 
> "Current" is not a noun, at least our meaning of it isn't.
> 
> If we used Status both for the collection of fields and for the string field, would it be confusing? Imagine someone asking "what was the pod's status?", or requesting "post the pod's status". I'd interpret the former as asking about the string, but might request qualification of the latter (field or subobject). Using different terms would certainly avoid this type of ambiguity.
> 
> Decisions:
> 
> Status is the most reasonable term for the collection of current state fields.
> 
> We should use "Condition" for the string, both in PodStatus and in Event.
> 
> —
> Reply to this email directly or view it on GitHub.