# Kubernetes User Documentation


## Resources

The Kubernetes API currently manages 3 main resources: `pods`,
`replicationControllers`, and `services`. Pods correspond to colocated groups
of [Docker containers](http://docker.io) with shared volumes, as supported by
[Google Cloud Platform container-vm
images](https://developers.google.com/compute/docs/containers).  Singleton pods
can be created directly via the `/pods` endpoint. Sets of pods may created,
maintained, and scaled using replicationControllers.  Services create
load-balanced targets for sets of pods.

Each resource has a two [identifiers](identifiers.md): a string `Name` and a
string `UID`.  The name is provided by the user.  The UID is generated by the
system and is guaranteed to be unique in space and time across all resources.
`labels` is a map of string (key) to string (value).

Each resource has list of key-value [labels](labels.md).
Individual labels are used to specify identifying metadata that can be used to define sets of resources by
specifying required labels.


## Creation and Updates

Object creation is idempotent when the client remembers the name of the object it wants to create.
Resources have a `desiredState` for the user provided parameters and a
`currentState` for the actual system state.  When a new version of a resource
is PUT the `desiredState` is updated and available immediately. Over time the
system will work to bring the `currentState` into line with the `desiredState`.
The system will drive toward the most recent `desiredState` regardless of
previous versions of that stanza. In other words, if a value is changed from 2
to 5 in one PUT and then back down to 3 in another PUT the system is not
required to 'touch base' at 5 before making 3 the `currentState`.

When doing an update, we assume that the entire `desiredState` stanza is
specified. If a field is omitted it is assumed that the user is looking to
delete that field. It is viable for a user to GET the resource, modify what
they like in the `desiredState` or labels stanzas and then PUT it back. If the
`currentState` is included in the PUT it will be silently ignored.

Concurrent modification should be accomplished with optimistic locking of
resources. All resources have a `ResourceVersion` as part of their metadata.
If this is included with the PUT operation the system will verify that there
have not been other successful mutations to the resource during a
read/modify/write cycle. The correct client action at this point is to GET the
resource again, apply the changes afresh and try submitting again.