From 1d9cff4a87a8e952448b841e4f8bc8018cfdafe0 Mon Sep 17 00:00:00 2001 From: Tim Hockin Date: Tue, 9 Sep 2014 09:57:02 -0700 Subject: [PATCH] Make pods a case study in identifiers.md --- docs/identifiers.md | 96 ++++++++++++++++++++++++++++----------------- 1 file changed, 61 insertions(+), 35 deletions(-) diff --git a/docs/identifiers.md b/docs/identifiers.md index 6efd613d647..07bc9391554 100644 --- a/docs/identifiers.md +++ b/docs/identifiers.md @@ -5,11 +5,11 @@ A summarization of the goals and recommendations for identifiers in Kubernetes. ## Definitions -uid -: An opaque system-generated value guaranteed to be unique in time and space; intended to distinguish between historical occurrences of similar entities. +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 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. +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 @@ -21,52 +21,78 @@ name : 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 +## Objectives for names and UIDs -1) Uniquely identify (via a uid) an object across space and time +1. Uniquely identify (via a UID) an object across space and time -2) Uniquely name (via a Name) an object across space +2. Uniquely name (via a name) an object across space -3) Provide human-friendly names in API operations and/or configuration files +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 +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 +5. Allow DNS names to be automatically generated for some objects -FIXME: Should this be more agnostic to resource type, and talk about pod as a particular case? -## Design +## General design -1) When an object is created on an apiserver, a Name string (a DNS_SUBDOMAIN) must be provided. - 1) must be non-empty and unique within the apiserver - 2) enables idempotent and space-unique creation - 1) generating random names will defeat idempotentcy - 3) other parts of the system (e.g. replication controller) may join strings (e.g. a base name and a random suffic) to create a unique Name +1. When an object is created via an api, a Name string (a DNS_SUBDOMAIN) must be provided. + 1. must be non-empty and unique within the apiserver + 2. enables idempotent and space-unique creation + 1. generating random names will defeat idempotentcy + 3. 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 Example: "guestbook.user" Example: "backend-x4eb1" FIXME: final debate on having master default a name. Alternative: set "autosetName"=true -2) Upon acceptance at the apiserver, a pod is assigned a uid (a UUID). - 1) must be non-empty and unique across space and time +2. Upon acceptance of an object via an api, the object is assigned a UID (a UUID). + 1. must be non-empty and unique across space and time Example: "01234567-89ab-cdef-0123-456789abcdef" -3) Each container within a pod must have a Name string (a DNS_LABEL). - 1) must be non-empty and unique within the pod - Example: "frontend" -4) When a pod is bound to a node, the node is told the pod's uid. - 1) if not provided, the kubelet will generate one - 2) provides for pods from node-local config files +## Case study: Scheduling a pod -6) When a pod is bound to a node, the node is told the pod's Name. - 1) kubelet will namespace pods from distinct sources (e.g. files vs apiserver) - 2) namespaces must be deterministic - 3) provides a cluster-wide space-unique name - Example: Namespace="k8s.example.com" Name="guestbook.user" - Example: Namespace="k8s.example.com" Name="backend-x4eb1" - Example: Namespace="file-f4231812554558a718a01ca942782d81" Name="cadvisor" +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. -7) Each run of a container within a pod will be assigned an AttemptID (string) that is unique across time. - 1) corresponds to Docker's container ID - Example: "77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182" +### A pod scheduled by a user through the apiserver + +1. A user submits a pod named "guestbook" to the apiserver. + +2. The apiserver validates the input. + 1. The pod name must be space-unique within the apiserver. + 2. Each container within the pod has a name which must be space-unique within the pod. + +3. The pod is accepted and a UID is assigned. + +4. The pod is bound to a node. + 1. The kubelet on the node is passed the pod's UID and name. + +5. Kubelet validates the input. + +6. Kubelet further namespaces the pod name with information about the source of the pod. + 1. E.g. Namespace="api.k8s.example.com" + +7. 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. + +### A pod placed by a config file on the node + +1. A config file is stored on the node, containing a pod named "cadvisor" with no UID. + +2. Kubelet validates the input. + 1. Since UID is not provided, kubelet generates one. + +3. Kubelet further namespaces the pod name with information about the source of the pod. + 1. The generated namespace should be deterministic and cluster-unique for the source. + 1. E.g. a hash of the hostname and file path. + 2. E.g. Namespace="file-f4231812554558a718a01ca942782d81" + +4. 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.