-
Notifications
You must be signed in to change notification settings - Fork 38.7k
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.
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
Describe identifiers in Kubernetes #334
Merged
brendandburns
merged 1 commit into
kubernetes:master
from
smarterclayton:add_identifier_doc
Jul 2, 2014
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) | ||
|
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is the pod.ID field, correct? And it should equal the ContainerManifest's ID, field, should we choose to keep that as a thing, correct?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, based on tentative agreement in #294. I can clarify that in the doc.