diff --git a/docs/identifiers.md b/docs/identifiers.md new file mode 100644 index 00000000000..6954ac2738a --- /dev/null +++ b/docs/identifiers.md @@ -0,0 +1,78 @@ +# 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). + +## Definitions + +identifier +: an opaque machine generated value guaranteed to be unique in a certain space + +name +: a human readable string intended to help an end user distinguish between similar but distinct entities + +[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 less than 64 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 255 characters + +namespace string (NAMESPACE) +: An rfc1035/rfc1123 subdomain no longer than 191 characters (255-63-1) + +source namespace string +: The namespace string of a source of pod definitions on a host + +[rfc4122](http://www.ietf.org/rfc/rfc4122.txt) universally unique identifier (UUID) +: A 128 bit generated value that is extremely unilkely to collide across time and space and requires no central coordination + +pod unique name +: the combination of a pod's source namespace string and name string on a host + +pod unique identifier +: the identifier associated with a single execution of a pod on a host, which changes on each restart. Must be a UUID + + +## Objectives for names and identifiers + +1) Uniquely identify an instance of a pod on the apiserver and on the kubelet + +2) Uniquely identify an instance of a container within a pod on the apiserver and on the kubelet + +3) Uniquely identify a single execution of a container in time for logging or reporting + +4) The structure of a pod specification should stay largely the same throughout the entire system + +5) Provide human-friendly, memorable, semantically meaningful, short-ish references in container and pod operations + +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) + + +## Implications + +1) Each container name within a container manifest must be unique within that manifest + +2) Each pod instance on the apiserver must have a unique identifier across space and time (UUID) + 1) The apiserver may set this identifier if not specified by a client + 2) This identifier will persist even if moved across hosts + +3) Each pod instance on the apiserver must have a name string which is human-friendly, dns-friendly (DNS_LABEL), and unique in the apiserver space + 1) The apiserver may set this name string if not specified by a client + +4) Each apiserver must have a configured namespace string (NAMESPACE) that is unique across all apiservers that share its configured minions + +5) Each source of pod configuration to a kubelet must have a source namespace string (NAMESPACE) that is unique across all sources available to that kubelet + +6) All pod instances on a host must have a name string which is human-friendly, dns-friendly, and unique per namespace string (DNS_LABEL) + +7) The combination of the name string and source namespace string on a kubelet must be unique and is referred to as the pod unique name + +8) When starting an instance of a pod on a kubelet the first time, a new pod unique identifier (UUID) should be assigned to that pod instance + 1) If that pod is restarted, it must retain the pod unique identifier it previously had + 2) If the pod is stopped and a new instance with the same pod unique name is started, it must be assigned a new pod unique identifier + +9) The kubelet should use the pod unique name and pod unique identifier to produce a Docker container name (--name) +