A summarization of the goals and recommendations for identifiers in Kubernetes. Described in GitHub issue #199.
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 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/rfc1123 label
(DNS_LABEL):
An alphanumeric (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/rfc1123 subdomain
(DNS_SUBDOMAIN):
One or more lowercase rfc1035/rfc1123 labels separated by '.' with a maximum
length of 253 characters.
rfc4122 universally unique identifier
(UUID):
A 128 bit generated value that is extremely unlikely to collide across time and
space and requires no central coordination.
rfc6335 port name
(IANA_SVC_NAME):
An alphanumeric (a-z, and 0-9) string, with a maximum length of 15 characters,
with the '-' character allowed anywhere except the first or the last character
or adjacent to another '-' character, it must contain at least a (a-z)
character.
- Uniquely identify (via a UID) an object across space and time.
- Uniquely name (via a name) an object across space.
- Provide human-friendly names in API operations and/or configuration files.
- Allow idempotent creation of API resources (#148) and enforcement of space-uniqueness of singleton objects.
- Allow DNS names to be automatically generated for some objects.
- When an object is created via an API, a Name string (a DNS_SUBDOMAIN) must
be specified. Name must be non-empty and unique within the apiserver. This
enables idempotent and space-unique creation operations. 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. For situations where generating a name is
impractical, some or all objects may support a param to auto-generate a name.
Generating random names will defeat idempotency.
- Examples: "guestbook.user", "backend-x4eb1"
- When an object is created via an API, a Namespace string (a DNS_LABEL)
may be specified. Depending on the API receiver,
namespaces might be validated (e.g. apiserver might ensure that the namespace
actually exists). If a namespace is not specified, one will be assigned by the
API receiver. This assignment policy might vary across API receivers (e.g.
apiserver might have a default, kubelet might generate something semi-random).
- Example: "api.k8s.example.com"
- Upon acceptance of an object via an API, the object is assigned a UID
(a UUID). UID must be non-empty and unique across space and time.
- Example: "01234567-89ab-cdef-0123-456789abcdef"
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.
- A user submits a pod with Namespace="" and Name="guestbook" to the apiserver.
- The apiserver validates the input.
- A default Namespace is assigned.
- The pod name must be space-unique within the Namespace.
- Each container within the pod has a name which must be space-unique within the pod.
- The pod is accepted.
- A new UID is assigned.
- The pod is bound to a node.
- The kubelet on the node is passed the pod's UID, Namespace, and Name.
- Kubelet validates the input.
- Kubelet runs the pod.
- Each container is started up with enough metadata to distinguish the pod from whence it came.
- Each attempt to run a container is assigned a UID (a string) that is unique across time. * This may correspond to Docker's container ID.
- A config file is stored on the node, containing a pod with UID="", Namespace="", and Name="cadvisor".
- Kubelet validates the input.
- Since UID is not provided, kubelet generates one.
- Since Namespace is not provided, kubelet generates one.
- The generated namespace should be deterministic and cluster-unique for
the source, such as a hash of the hostname and file path.
- E.g. Namespace="file-f4231812554558a718a01ca942782d81"
- The generated namespace should be deterministic and cluster-unique for
the source, such as a hash of the hostname and file path.
- Kubelet runs the pod.
- Each container is started up with enough metadata to distinguish the pod from whence it came.
- Each attempt to run a container is assigned a UID (a string) that is
unique across time.
- This may correspond to Docker's container ID.