github/kubernetes
1
0
Fork 0
mirror of https://github.com/k3s-io/kubernetes.git synced 2025-07-30 06:54:01 +00:00
Code Issues Projects Releases Wiki Activity

Make pods a case study in identifiers.md

Browse Source
This commit is contained in:
Tim Hockin 2014-09-09 09:57:02 -07:00
parent b6eb7cc979
commit 1d9cff4a87
1 changed files with 61 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
docs/identifiers.md
View File

@ -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.