mirror of
https://github.com/k3s-io/kubernetes.git
synced 2025-10-30 21:30:16 +00:00
c47693c0d5
Renamed: logging.md -> devel/logging.m Renamed: access.md -> design/access.md Renamed: identifiers.md -> design/identifiers.md Renamed: labels.md -> design/labels.md Renamed: namespaces.md -> design/namespaces.md Renamed: security.md -> design/security.md Renamed: networking.md -> design/networking.md Added abbreviated user user-focused document in place of most moved docs. Added docs/README.md explains how docs are organized. Added short, user-oriented documentation on labels Added a glossary. Fixed up some links.
50 lines
2.5 KiB
Markdown
50 lines
2.5 KiB
Markdown
# 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.
|
|
|