Kubernetes API documentation version v1beta1
The Kubernetes API currently manages 3 main resources:
services. Pods correspond to colocated groups of Docker containers with shared volumes, as supported by Google Cloud Platform's 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 string
id and list of key-value
id 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 may have at most one label with a particular key. Individual labels are used to specify identifying metadata that can be used to define sets of resources by specifying required labels. Examples of typical pod label keys include
track, but you are free to develop your own conventions.
Creation is currently not idempotent. We plan to add a modification token to each resource. A unique value for the token should be provided by the user during creation. If the user specifies a duplicate token at creation time, the system should return an error with a pointer to the existing resource with that token. In this way a user can deterministically recover from a dropped connection during a resource creation request.
Custom verbs are minimized and are used only for 'edge triggered' actions such as a reboot. Resource descriptions are generally set up with
desiredState for the user provided parameters and
currentState for the actual system state. While consistent terminology is used across these two stanzas they do not match member for member.
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 isn't required to 'touch base' at 5 before making 3 the
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.
While currently unspecified, it is intended that concurrent modification should be accomplished with optimistic locking of resources. We plan to add a modification token to each resource. If this is included with the PUT operation the system will verify that there haven't 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.
Note that updates currently only work for replicationControllers and services, but not for pods. Label updates have not yet been implemented, either.