github/kubernetes
1
0
Fork 0
mirror of https://github.com/k3s-io/kubernetes.git synced 2025-09-09 13:12:20 +00:00
Code Issues Projects Releases Wiki Activity

Revisit identifiers spec

Browse Source
This commit is contained in:
Tim Hockin
2014-09-08 12:58:44 -07:00
parent b5c6edcd79
commit 1a21ffdd0a
1 changed files with 38 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

85
docs/identifiers.md
View File

@@ -1,14 +1,15 @@
# Identifiers and Names in Kubernetes
A summarization of the goals and recommendations for identifiers and names in Kubernetes. Described in [GitHub issue #199](https://github.com/GoogleCloudPlatform/kubernetes/issues/199).
A summarization of the goals and recommendations for identifiers in Kubernetes. Described in [GitHub issue #199](https://github.com/GoogleCloudPlatform/kubernetes/issues/199).
## Definitions
identifier
: An opaque machine generated value guaranteed to be unique in a certain space
uid
: An opaque system-generated value guaranteed to be unique in time and space; intended to distinguish between historical occurrences of similar entities.
name
: A human readable string intended to help an end user distinguish between similar but distinct entities
: 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.
[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
@@ -19,68 +20,58 @@ name
[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 identifiers
1) Uniquely identify an instance of a pod on the apiserver and on the kubelet
## Objectives for names and uids
2) Uniquely identify an instance of a container within a pod on the apiserver and on the kubelet
1) Uniquely identify (via a uid) an object across space and time
3) Uniquely identify a single execution of a container in time for logging or reporting
2) Uniquely name (via a Name) an object across space
4) The structure of a pod specification should stay largely the same throughout the entire system
3) Provide human-friendly names in API operations and/or configuration files
5) Provide human-friendly, memorable, semantically meaningful, short-ish references in container and pod operations
4) Allow idempotent creation of API resources (#148) and enforcement of space-uniqueness of singleton objects
6) Provide predictable container and pod references in operations and/or configuration files
7) Allow idempotent creation of API resources (#148)
8) Allow DNS names to be automatically generated for individual containers or pods (#146)
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
1) Each apiserver has a Namespace string (a DNS_SUBDOMAIN) that is unique across all apiservers that share its configured minions.
1) Each apiserver must be assigned a Namespace string (a DNS_SUBDOMAIN).
1) must be non-empty and unique across all apiservers that share minions
Example: "k8s.example.com"
2) Each pod instance on an apiserver has a PodName string (a DNS_SUBDOMAIN) which is and unique within the Namespace.
1) If not specified by the client, the apiserver will assign this identifier
2) 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's Namespace
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
Example: "guestbook.user"
Example: "backend-x4eb1"
3) Each pod instance on an apiserver has a PodFullName (a DNS_SUBDOMAIN) string which is derived from a combination of the Namespace and Name strings.
1) If the joined Namespace and PodName is too long for a DNS_SUBDOMAIN, the apiserver must transform it to fit, while still being unique
Example: "guestbook.user.k8s.example.com"
FIXME: final debate on having master default a name. Alternative: set "autosetName"=true
FIXME: how long can <name>+<namespace> be? We previously had FullName, making it the apiserver's problem to truncate long names to DNS_DOMAIN len.
4) Each pod instance on an apiserver has a PodID (a UUID) that is unique across space and time
1) If not specified by the client, the apiserver will assign this identifier
2) This identifier will persist for the lifetime of the pod, even if the pod is stopped and started or moved across hosts
3) Upon acceptance at the apiserver, a pod is assigned a uid (a UUID).
1) must be non-empty and unique across space and time
Example: "01234567-89ab-cdef-0123-456789abcdef"
5) Each container within a pod has a ContainerName string (a DNS_LABEL) that is unique within that pod
1) This name must be specified by the client or the apiserver will reject the pod
4) 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"
6) Each pod instance on a kubelet has a PodNamespace string (a DNS_SUBDOMAIN)
1) This corresponds to the apiserver's Namespace string
2) If not specified, the kubelet will assign this name to a deterministic value which is likely to be unique across all sources on the host
Example: "k8s.example.com"
Example: "file-f4231812554558a718a01ca942782d81"
5) 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
7) Each pod instance on a kubelet has a PodName string (a DNS_SUBDOMAIN) which is unique within the source Namespace
1) This corresponds to the apiserver's PodName string
2) If not specified, the kubelet will assign this name to a deterministic value
Example: "frontend"
6) When a pod is bound to a node, the node is told the pod's Namespace, and Name.
1) if Namespace is not provided, the kubelet will generate one
2) generated 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"
8) When starting an instance of a pod on a kubelet, a PodInstanceID (a UUID) will be assigned to that pod instance
1) If not specified, the kubelet will assign this identifier
2) If the pod is restarted, it must retain the PodInstanceID it previously had
3) If the pod is stopped and a new instance with the same PodNamespace and PodName is started, it must be assigned a new PodInstanceID
4) If the pod is moved across hosts, it must be assigned a new PodInstanceID
Example: "01234567-89ab-cdef-0123-456789abcdef"
9) The kubelet may use the PodNamespace, PodName, PodID, and PodInstanceID to produce a docker container name (--name)
Example: "01234567-89ab-cdef-0123-456789abcdef_frontend_k8s.example.com"
10) Each run of a container within a pod will be assigned a ContainerAttemptID (string) that is unique across time.
1) This corresponds to Docker container IDs
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"