2.5 KiB
Kubernetes User Documentation
Resources
The Kubernetes API currently manages 3 main resources: pods,
replicationControllers, and services. Pods correspond to colocated groups
of Docker containers with shared volumes, as supported by
Google Cloud Platform container-vm
images. 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: 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. 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.