Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Revisit identifiers spec #1216

Merged
merged 5 commits into from
Sep 16, 2014
Merged

Revisit identifiers spec #1216

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1a21ffd
Revisit identifiers spec
thockin Sep 8, 2014
b6eb7cc
Simplify pod namespaces
thockin Sep 8, 2014
1d9cff4
Make pods a case study in identifiers.md
thockin Sep 9, 2014
1eeed78
Document auto-set names
thockin Sep 10, 2014
d4b6f7a
Re-add namespaces
thockin Sep 11, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
104 changes: 54 additions & 50 deletions docs/identifiers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
: 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 human readable string intended to help an end user distinguish between similar but distinct 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be clarified to be:

"A non-empty string guaranteed to be unique to a resource type within a given scope at a particular time."

It should be a-ok to have different resource types that have the same name in a particular scope.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree with your point, but I think "within a given scope" captures that. It's already a mouthy sentence.


[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
Expand All @@ -19,68 +20,71 @@ 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

1. Uniquely identify (via a UID) an object across space and time

2. Uniquely name (via a name) an object across space

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

5. Allow DNS names to be automatically generated for some objects

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
## General design

4) The structure of a pod specification should stay largely the same throughout the entire system
1. 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"

5) Provide human-friendly, memorable, semantically meaningful, short-ish references in container and pod operations
2. When an object is created via an api, a Namespace string (a DNS_SUBDOMAIN? format TBD via #1114) 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"

6) Provide predictable container and pod references in operations and/or configuration files
3. 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"

7) Allow idempotent creation of API resources (#148)

8) Allow DNS names to be automatically generated for individual containers or pods (#146)
## Case study: Scheduling a pod

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.

## Design
### A pod scheduled by a user through the apiserver

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"
1. A user submits a pod with Namespace="" and Name="guestbook" to the apiserver.

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"
2. The apiserver validates the input.
1. A default Namespace is assigned.
2. The pod name must be space-unique within the Namespace.
3. Each container within the pod has a name which must be space-unique within the pod.

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"
3. The pod is accepted.
1. A new UID is assigned.

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"
4. The pod is bound to a node.
1. The kubelet on the node is passed the pod's UID, Namespace, and Name.

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"
5. Kubelet validates the input.

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"
6. 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.
* This may correspond to Docker's container ID.

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"
### A pod placed by a config file on the node

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"
1. A config file is stored on the node, containing a pod with UID="", Namespace="", and Name="cadvisor".

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"
2. Kubelet validates the input.
1. Since UID is not provided, kubelet generates one.
2. Since Namespace is not provided, kubelet generates one.
1. 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"

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"
3. 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.