Separated user, dev, and design docs.

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.
duda · Oct 31, 2014 · c47693c · c47693c
1 parent a18cdac
commit c47693c
Show file tree

Hide file tree

Showing 16 changed files with 656 additions and 452 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,29 @@
+# Kubernetes Documentation
+
+Kubernetes documentation is organized into several categories.
+
+  - **Getting Started Guides**
+    - for people who want to create a kubernetes cluster
+    - in [docs/getting-started-guides](./getting-started-guides)
+  - **User Documentation**
+    - in [docs](./overview.md)
+    - for people who want to run programs on kubernetes
+    - describes current features of the system (with brief mentions of planned features)
+  - **Developer Documentation**
+    - in [docs/devel](./devel)
+    - for people who want to contribute code to kubernetes
+    - covers development conventions
+    - explains current architecture and project plans
+  - **Design Documentation**
+    - in [docs/design](./design)
+    - for people who want to understand the design choices made
+    - describes tradeoffs, alternative designs
+    - descriptions of planned features that are too long for a github issue.
+  - **Walkthroughs and Examples**
+    - in [examples](../examples)
+    - Hands on introduction and example config files
+  - **API documentation**
+    - in [api](../api)
+    - automatically generated REST API documentation
+  - **Wiki**
+    - in [wiki](https://github.com/GoogleCloudPlatform/kubernetes/wiki)
diff --git a/docs/access.md → docs/design/access.md b/docs/access.md → docs/design/access.md
diff --git a/docs/design/identifiers.md b/docs/design/identifiers.md
@@ -0,0 +1,90 @@
+# Identifiers and Names in Kubernetes
+
+A summarization of the goals and recommendations for identifiers in Kubernetes.  Described in [GitHub issue #199](https://github.com/GoogleCloudPlatform/kubernetes/issues/199).
+
+
+## Definitions
+
+UID
+: A non-empty, opaque, system-generated value guaranteed to be unique in time and space; intended to distinguish between historical occurrences of similar entities.
+
+Name
+: A non-empty string guaranteed to be unique within a given scope at a particular time; used in resource URLs; provided by clients at creation time and encouraged to be human friendly; intended to facilitate creation idempotence and space-uniqueness of singleton objects, distinguish distinct entities, and reference particular entities across operations.
+
+[rfc1035](http://www.ietf.org/rfc/rfc1035.txt)/[rfc1123](http://www.ietf.org/rfc/rfc1123.txt) label (DNS_LABEL)
+: An alphanumeric (a-z, A-Z, and 0-9) string, with a maximum length of 63 characters, with the '-' character allowed anywhere except the first or last character, suitable for use as a hostname or segment in a domain name
+
+[rfc1035](http://www.ietf.org/rfc/rfc1035.txt)/[rfc1123](http://www.ietf.org/rfc/rfc1123.txt) subdomain (DNS_SUBDOMAIN)
+: One or more rfc1035/rfc1123 labels separated by '.' with a maximum length of 253 characters
+
+[rfc4122](http://www.ietf.org/rfc/rfc4122.txt) universally unique identifier (UUID)
+: A 128 bit generated value that is extremely unlikely to collide across time and space and requires no central coordination
+
+
+## Objectives for names and UIDs
+
+1. Uniquely identify (via a UID) an object across space and time
+
+2. Uniquely name (via a name) an object across space
+
+3. Provide human-friendly names in API operations and/or configuration files
+
+4. Allow idempotent creation of API resources (#148) and enforcement of space-uniqueness of singleton objects
+
+5. Allow DNS names to be automatically generated for some objects
+
+
+## General design
+
+1. When an object is created via an API, a Name string (a DNS_SUBDOMAIN) must be specified.  Name must be non-empty and unique within the apiserver.  This enables idempotent and space-unique creation operations.  Parts of the system (e.g. replication controller) may join strings (e.g. a base name and a random suffix) to create a unique Name.  For situations where generating a name is impractical, some or all objects may support a param to auto-generate a name.  Generating random names will defeat idempotency.
+   * Examples: "guestbook.user", "backend-x4eb1"
+
+2. When an object is created via an api, a Namespace string (a DNS_SUBDOMAIN? format TBD via #1114) may be specified.  Depending on the API receiver, namespaces might be validated (e.g. apiserver might ensure that the namespace actually exists).  If a namespace is not specified, one will be assigned by the API receiver.  This assignment policy might vary across API receivers (e.g. apiserver might have a default, kubelet might generate something semi-random).
+   * Example: "api.k8s.example.com"
+
+3. Upon acceptance of an object via an API, the object is assigned a UID (a UUID).  UID must be non-empty and unique across space and time.
+   * Example: "01234567-89ab-cdef-0123-456789abcdef"
+
+
+## Case study: Scheduling a pod
+
+Pods can be placed onto a particular node in a number of ways.  This case
+study demonstrates how the above design can be applied to satisfy the
+objectives.
+
+### A pod scheduled by a user through the apiserver
+
+1. A user submits a pod with Namespace="" and Name="guestbook" to the apiserver.
+
+2. The apiserver validates the input.
+   1. A default Namespace is assigned.
+   2. The pod name must be space-unique within the Namespace.
+   3. Each container within the pod has a name which must be space-unique within the pod.
+
+3. The pod is accepted.
+   1. A new UID is assigned.
+
+4. The pod is bound to a node.
+   1. The kubelet on the node is passed the pod's UID, Namespace, and Name.
+
+5. Kubelet validates the input.
+
+6. Kubelet runs the pod.
+   1. Each container is started up with enough metadata to distinguish the pod from whence it came.
+   2. Each attempt to run a container is assigned a UID (a string) that is unique across time.
+      * This may correspond to Docker's container ID.
+
+### A pod placed by a config file on the node
+
+1. A config file is stored on the node, containing a pod with UID="", Namespace="", and Name="cadvisor".
+
+2. Kubelet validates the input.
+   1. Since UID is not provided, kubelet generates one.
+   2. Since Namespace is not provided, kubelet generates one.
+      1. The generated namespace should be deterministic and cluster-unique for the source, such as a hash of the hostname and file path.
+         * E.g. Namespace="file-f4231812554558a718a01ca942782d81"
+
+3. Kubelet runs the pod.
+   1. Each container is started up with enough metadata to distinguish the pod from whence it came.
+   2. Each attempt to run a container is assigned a UID (a string) that is unique across time.
+      1. This may correspond to Docker's container ID.
diff --git a/docs/design/labels.md b/docs/design/labels.md
@@ -0,0 +1,68 @@
+# Labels
+
+_Labels_ are key/value pairs identifying client/user-defined attributes (and non-primitive system-generated attributes) of API objects, which are stored and returned as part of the [metadata of those objects](api-conventions.md). Labels can be used to organize and to select subsets of objects according to these attributes.
+
+Each object can have a set of key/value labels set on it, with at most one label with a particular key. 
+```
+"labels": {
+  "key1" : "value1",
+  "key2" : "value2"
+}
+```
+
+Unlike [names and UIDs](identifiers.md), labels do not provide uniqueness. In general, we expect many objects to carry the same label(s). 
+
+Via a _label selector_, the client/user can identify a set of objects. The label selector is the core grouping primitive in Kubernetes. 
+
+Label selectors may also be used to associate policies with sets of objects.
+
+We also [plan](https://github.com/GoogleCloudPlatform/kubernetes/issues/560) to make labels available inside pods and [lifecycle hooks](container-environment.md).
+
+[Namespacing of label keys](https://github.com/GoogleCloudPlatform/kubernetes/issues/1491) is under discussion.
+
+Valid labels follow a slightly modified RFC952 format:  24 characters or less, all lowercase, begins with alpha, dashes (-) are allowed, and ends with alphanumeric.
+
+## Motivation
+
+Service deployments and batch processing pipelines are often multi-dimensional entities (e.g., multiple partitions or deployments, multiple release tracks, multiple tiers, multiple micro-services per tier). Management often requires cross-cutting operations, which breaks encapsulation of strictly hierarchical representations, especially rigid hierarchies determined by the infrastructure rather than by users. Labels enable users to map their own organizational structures onto system objects in a loosely coupled fashion, without requiring clients to store these mappings.
+
+## Label selectors
+
+Label selectors permit very simple filtering by label keys and values. The simplicity of label selectors is deliberate. It is intended to facilitate transparency for humans, easy set overlap detection, efficient indexing, and reverse-indexing (i.e., finding all label selectors matching an object's labels - https://github.com/GoogleCloudPlatform/kubernetes/issues/1348). 
+
+Currently the system supports selection by exact match of a map of keys and values. Matching objects must have all of the specified labels (both keys and values), though they may have additional labels as well.
+
+We are in the process of extending the label selection specification (see [selector.go](../blob/master/pkg/labels/selector.go) and https://github.com/GoogleCloudPlatform/kubernetes/issues/341) to support conjunctions of requirements of the following forms:
+```
+key1 in (value11, value12, ...)
+key1 not in (value11, value12, ...)
+key1 exists
+```
+
+LIST and WATCH operations may specify label selectors to filter the sets of objects returned using a query parameter: `?labels=key1%3Dvalue1,key2%3Dvalue2,...`. We may extend such filtering to DELETE operations in the future.
+
+Kubernetes also currently supports two objects that use label selectors to keep track of their members, `service`s and `replicationController`s:
+- `service`: A [service](services.md) is a configuration unit for the proxies that run on every worker node.  It is named and points to one or more pods.
+- `replicationController`: A [replication controller](replication-controller.md) ensures that a specified number of pod "replicas" are running at any one time.  If there are too many, it'll kill some.  If there are too few, it'll start more.
+
+The set of pods that a `service` targets is defined with a label selector. Similarly, the population of pods that a `replicationController` is monitoring is also defined with a label selector. 
+
+For management convenience and consistency, `services` and `replicationControllers` may themselves have labels and would generally carry the labels their corresponding pods have in common.
+
+In the future, label selectors will be used to identify other types of distributed service workers, such as worker pool members or peers in a distributed application.
+
+Individual labels are used to specify identifying metadata, and to convey the semantic purposes/roles of pods of containers. Examples of typical pod label keys include `service`, `environment` (e.g., with values `dev`, `qa`, or `production`), `tier` (e.g., with values `frontend` or `backend`), and `track` (e.g., with values `daily` or `weekly`), but you are free to develop your own conventions.
+
+Sets identified by labels and label selectors could be overlapping (think Venn diagrams). For instance, a service might target all pods with `tier in (frontend), environment in (prod)`.  Now say you have 10 replicated pods that make up this tier.  But you want to be able to 'canary' a new version of this component.  You could set up a `replicationController` (with `replicas` set to 9) for the bulk of the replicas with labels `tier=frontend, environment=prod, track=stable` and another `replicationController` (with `replicas` set to 1) for the canary with labels `tier=frontend, environment=prod, track=canary`.  Now the service is covering both the canary and non-canary pods.  But you can mess with the `replicationControllers` separately to test things out, monitor the results, etc. 
+
+Note that the superset described in the previous example is also heterogeneous. In long-lived, highly available, horizontally scaled, distributed, continuously evolving service applications, heterogeneity is inevitable, due to canaries, incremental rollouts, live reconfiguration, simultaneous updates and auto-scaling, hardware upgrades, and so on.
+
+Pods (and other objects) may belong to multiple sets simultaneously, which enables representation of service substructure and/or superstructure. In particular, labels are intended to facilitate the creation of non-hierarchical, multi-dimensional deployment structures. They are useful for a variety of management purposes (e.g., configuration, deployment) and for application introspection and analysis (e.g., logging, monitoring, alerting, analytics). Without the ability to form sets by intersecting labels, many implicitly related, overlapping flat sets would need to be created, for each subset and/or superset desired, which would lose semantic information and be difficult to keep consistent. Purely hierarchically nested sets wouldn't readily support slicing sets across different dimensions.
+
+Pods may be removed from these sets by changing their labels. This flexibility may be used to remove pods from service for debugging, data recovery, etc.
+
+Since labels can be set at pod creation time, no separate set add/remove operations are necessary, which makes them easier to use than manual set management. Additionally, since labels are directly attached to pods and label selectors are fairly simple, it's easy for users and for clients and tools to determine what sets they belong to (i.e., they are reversible). OTOH, with sets formed by just explicitly enumerating members, one would (conceptually) need to search all sets to determine which ones a pod belonged to.
+
+## Labels vs. annotations
+
+We'll eventually index and reverse-index labels for efficient queries and watches, use them to sort and group in UIs and CLIs, etc. We don't want to pollute labels with non-identifying, especially large and/or structured, data. Non-identifying information should be recorded using [annotations](annotations.md).