github/kubernetes
1
0
Fork 0
mirror of https://github.com/k3s-io/kubernetes.git synced 2025-09-02 17:57:33 +00:00
Code Issues Projects Releases Wiki Activity

Documentation improvements. Fixes #2004, #2115, #2171.

Browse Source
This commit is contained in:
Brian Grant
2014-11-17 21:32:44 +00:00
parent 37d2bab7ed
commit d5700eac35
5 changed files with 140 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
docs/overview.md
View File

@@ -1,49 +1,27 @@
# Kubernetes User Documentation
The Kubernetes API currently manages 3 main resources:
* [pods](pods.md)
* [replication controllers](replication-controller.md)
* [services](services.md)
## Resources
In Kubernetes, rather than individual containers, _pods_ are the smallest deployable units that can be created, scheduled, and managed. Singleton pods can be created directly, and sets of pods may created, maintained, and scaled using replication controllers. Services create load-balanced targets for sets of pods.
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.
Kubernetes supports a unique [networking model](networking.md). Kubernetes encourages a flat address and does not dynamically allocate ports, instead allowing users to select whichever ports are convenient for them. To achieve this, it allocates an IP address for each pod and each service. Services provide stable addresses and [DNS names](dns.md) for clients to connect to, even as serving pods are replaced by new pods on new hosts.
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 a map 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.
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.
Each resource also has a map of string keys and values that can be used by external tooling to store and retrieve arbitrary metadata about this object, called [annotations.md](annotations.md).
Each resource is created within a specific [namespace](namespaces.md), a default one if unspecified.
## 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.
Other details:
* [API](api-conventions.md)
* [Client libraries](client-libraries.md)
* [Command-line interface](cli.md)
* [UI](ux.md)
* [Images and registries](images.md)
* [Container environment](container-environment.md)
* [Logging](logging.md)
* Monitoring using [CAdvisor](https://github.com/google/cadvisor) and [Heapster](https://github.com/GoogleCloudPlatform/heapster)