mirror of https://github.com/k3s-io/k3s
Tighten the identifiers spec
As I read through it I wanted to wordsmith a bit, which lead to reordering some to read sort of top-down. There were a couple things I thought were wrong (pod name should be a subdomain) and a few things I think we can make more concise. I also added examples and clarified implications.pull/6/head
Tim Hockin
parent
9408bd77ec
commit
6e78426d00
|
|
@ -5,33 +5,20 @@ A summarization of the goals and recommendations for identifiers and names in Ku
|
|||
## Definitions
|
||||
|
||||
identifier
|
||||
: an opaque machine generated value guaranteed to be unique in a certain space
|
||||
: 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
|
||||
: 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.
|
||||
: 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 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
|
||||
: 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 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
|
||||
|
|
@ -51,28 +38,49 @@ pod unique identifier
|
|||
8) Allow DNS names to be automatically generated for individual containers or pods (#146)
|
||||
|
||||
|
||||
## Implications
|
||||
## Design
|
||||
|
||||
1) Each container name within a container manifest must be unique within that manifest
|
||||
1) Each apiserver has a Namespace string (a DNS_SUBDOMAIN) that is unique across all apiservers that share its configured minions.
|
||||
Example: "k8s.example.com"
|
||||
|
||||
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
|
||||
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
|
||||
Example: "guestbook.user"
|
||||
|
||||
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
|
||||
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"
|
||||
|
||||
4) Each apiserver must have a configured namespace string (NAMESPACE) that is unique across all apiservers that share its configured minions
|
||||
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
|
||||
Example: "01234567-89ab-cdef-0123-456789abcdef"
|
||||
|
||||
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
|
||||
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
|
||||
Example: "frontend"
|
||||
|
||||
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)
|
||||
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"
|
||||
|
||||
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
|
||||
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"
|
||||
|
||||
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
|
||||
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 should use the pod unique name and pod unique identifier to produce a Docker container name (--name)
|
||||
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
|
||||
Example: "77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182"
|
||||
|
|
|
|||
Loading…
Reference in New Issue