272 lines
11 KiB
HTML
272 lines
11 KiB
HTML
<!Doctype html>
|
||
<html id="docs">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
<link href='https://fonts.googleapis.com/css?family=Roboto:400,100,100italic,300,300italic,400italic,500,500italic,700,700italic,900,900italic' rel='stylesheet' type='text/css'>
|
||
<link rel="stylesheet" href="/css/styles.css"/>
|
||
<script src="/js/script.js"></script>
|
||
<script src="/js/jquery-2.2.0.min.js"></script>
|
||
<script src="/js/non-mini.js"></script>
|
||
<title>Kubernetes - Identifiers and Names in Kubernetes</title>
|
||
</head>
|
||
<body>
|
||
<div id="cellophane" onclick="kub.toggleMenu()"></div>
|
||
<header>
|
||
<a href="/" class="logo"></a>
|
||
<div class="nav-buttons" data-auto-burger="primary">
|
||
<a href="/docs" class="button" id="viewDocs">View Documentation</a>
|
||
<a href="/get-started" class="button" id="tryKubernetes">Try Kubernetes</a>
|
||
<button id="hamburger" onclick="kub.toggleMenu()" data-auto-burger-exclude><div></div></button>
|
||
</div>
|
||
|
||
<nav id="mainNav">
|
||
<main data-auto-burger="primary">
|
||
<div class="nav-box">
|
||
<h3><a href="">Get Started</a></h3>
|
||
<p>Built for a multi-cloud world, public, private or hybrid. Seamlessly roll out new features.</p>
|
||
</div>
|
||
<div class="nav-box">
|
||
<h3><a href="">Documentation</a></h3>
|
||
<p>Pellentesque in ipsum id orci porta dapibus. Nulla porttitor accumsan tincidunt. </p>
|
||
</div>
|
||
<div class="nav-box">
|
||
<h3><a href="">Community</a></h3>
|
||
<p>Vestibulum ac diam sit amet quam vehicula elementum sed sit amet dui. </p>
|
||
</div>
|
||
<div class="nav-box">
|
||
<h3><a href="">Blog</a></h3>
|
||
<p>Curabitur arcu erat, accumsan id imperdiet et, porttitor at sem. Quisque velit nisi, pretium ut lacinia in. </p>
|
||
</div>
|
||
</main>
|
||
<main data-auto-burger="primary">
|
||
<div class="left">
|
||
<h5 class="github-invite">Interested in hacking on the core Kubernetes code base?</h5>
|
||
<a href="" class="button">View On Github</a>
|
||
</div>
|
||
|
||
<div class="right">
|
||
<h5 class="github-invite">Explore the community</h5>
|
||
<div class="social">
|
||
<a href="https://twitter.com/kubernetesio" class="Twitter"><span>twitter</span></a>
|
||
<a href="https://github.com/kubernetes/kubernetes" class="github"><span>Github</span></a>
|
||
<a href="http://slack.k8s.io/" class="slack"><span>Slack</span></a>
|
||
<a href="http://stackoverflow.com/questions/tagged/kubernetes" class="stack-overflow"><span>stackoverflow</span></a>
|
||
<a href="https://groups.google.com/forum/#!forum/google-containers" class="mailing-list"><span>Mailing List</span></a>
|
||
</div>
|
||
</div>
|
||
<div class="clear" style="clear: both"></div>
|
||
</main>
|
||
</nav>
|
||
</header>
|
||
|
||
<!-- HERO -->
|
||
<section id="hero" class="light-text">
|
||
<h1></h1>
|
||
<h5></h5>
|
||
<div id="vendorStrip" class="light-text">
|
||
<ul>
|
||
<li><a href="/v1.1/">GUIDES</a></li>
|
||
<li><a href="/v1.1/reference">REFERENCE</a></li>
|
||
<li><a href="/v1.1/samples">SAMPLES</a></li>
|
||
<li><a href="/v1.1/support">SUPPORT</a></li>
|
||
</ul>
|
||
<div class="dropdown">
|
||
<div class="readout"></div>
|
||
<a href="/v1.1">Version 1.1</a>
|
||
<a href="/v1.0">Version 1.0</a>
|
||
</div>
|
||
<input type="text" id="search" placeholder="Search the docs">
|
||
</div>
|
||
</section>
|
||
|
||
<section id="encyclopedia">
|
||
<div id="docsToc">
|
||
<div class="pi-accordion">
|
||
|
||
|
||
|
||
</div> <!-- /pi-accordion -->
|
||
</div> <!-- /docsToc -->
|
||
<div id="docsContent">
|
||
<h1>Identifiers and Names in Kubernetes</h1>
|
||
<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
|
||
|
||
<!-- END MUNGE: UNVERSIONED_WARNING -->
|
||
|
||
<h1 id="identifiers-and-names-in-kubernetes">Identifiers and Names in Kubernetes</h1>
|
||
|
||
<p>A summarization of the goals and recommendations for identifiers in Kubernetes. Described in <a href="http://issue.k8s.io/199">GitHub issue #199</a>.</p>
|
||
|
||
<h2 id="definitions">Definitions</h2>
|
||
|
||
<dl>
|
||
<dt>UID</dt>
|
||
<dd>A non-empty, opaque, system-generated value guaranteed to be unique in time and space; intended to distinguish between historical occurrences of similar entities.</dd>
|
||
<dt>Name</dt>
|
||
<dd>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.</dd>
|
||
<dt><a href="http://www.ietf.org/rfc/rfc1035.txt">rfc1035</a>/<a href="http://www.ietf.org/rfc/rfc1123.txt">rfc1123</a> label (DNS_LABEL)</dt>
|
||
<dd>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</dd>
|
||
<dt><a href="http://www.ietf.org/rfc/rfc1035.txt">rfc1035</a>/<a href="http://www.ietf.org/rfc/rfc1123.txt">rfc1123</a> subdomain (DNS_SUBDOMAIN)</dt>
|
||
<dd>One or more lowercase rfc1035/rfc1123 labels separated by ‘.’ with a maximum length of 253 characters</dd>
|
||
<dt><a href="http://www.ietf.org/rfc/rfc4122.txt">rfc4122</a> universally unique identifier (UUID)</dt>
|
||
<dd>A 128 bit generated value that is extremely unlikely to collide across time and space and requires no central coordination</dd>
|
||
<dt><a href="https://tools.ietf.org/rfc/rfc6335.txt">rfc6335</a> port name (IANA_SVC_NAME)</dt>
|
||
<dd>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</dd>
|
||
</dl>
|
||
|
||
<h2 id="objectives-for-names-and-uids">Objectives for names and UIDs</h2>
|
||
|
||
<ol>
|
||
<li>
|
||
<p>Uniquely identify (via a UID) an object across space and time</p>
|
||
</li>
|
||
<li>
|
||
<p>Uniquely name (via a name) an object across space</p>
|
||
</li>
|
||
<li>
|
||
<p>Provide human-friendly names in API operations and/or configuration files</p>
|
||
</li>
|
||
<li>
|
||
<p>Allow idempotent creation of API resources (#148) and enforcement of space-uniqueness of singleton objects</p>
|
||
</li>
|
||
<li>
|
||
<p>Allow DNS names to be automatically generated for some objects</p>
|
||
</li>
|
||
</ol>
|
||
|
||
<h2 id="general-design">General design</h2>
|
||
|
||
<ol>
|
||
<li>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.
|
||
<ul>
|
||
<li>Examples: “guestbook.user”, “backend-x4eb1”</li>
|
||
</ul>
|
||
</li>
|
||
<li>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).
|
||
<ul>
|
||
<li>Example: “api.k8s.example.com”</li>
|
||
</ul>
|
||
</li>
|
||
<li>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.
|
||
<ul>
|
||
<li>Example: “01234567-89ab-cdef-0123-456789abcdef”</li>
|
||
</ul>
|
||
</li>
|
||
</ol>
|
||
|
||
<h2 id="case-study-scheduling-a-pod">Case study: Scheduling a pod</h2>
|
||
|
||
<p>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.</p>
|
||
|
||
<h3 id="a-pod-scheduled-by-a-user-through-the-apiserver">A pod scheduled by a user through the apiserver</h3>
|
||
|
||
<ol>
|
||
<li>
|
||
<p>A user submits a pod with Namespace=”” and Name=”guestbook” to the apiserver.</p>
|
||
</li>
|
||
<li>The apiserver validates the input.
|
||
<ol>
|
||
<li>A default Namespace is assigned.</li>
|
||
<li>The pod name must be space-unique within the Namespace.</li>
|
||
<li>Each container within the pod has a name which must be space-unique within the pod.</li>
|
||
</ol>
|
||
</li>
|
||
<li>The pod is accepted.
|
||
<ol>
|
||
<li>A new UID is assigned.</li>
|
||
</ol>
|
||
</li>
|
||
<li>The pod is bound to a node.
|
||
<ol>
|
||
<li>The kubelet on the node is passed the pod’s UID, Namespace, and Name.</li>
|
||
</ol>
|
||
</li>
|
||
<li>
|
||
<p>Kubelet validates the input.</p>
|
||
</li>
|
||
<li>Kubelet runs the pod.
|
||
<ol>
|
||
<li>Each container is started up with enough metadata to distinguish the pod from whence it came.</li>
|
||
<li>Each attempt to run a container is assigned a UID (a string) that is unique across time.
|
||
<ul>
|
||
<li>This may correspond to Docker’s container ID.</li>
|
||
</ul>
|
||
</li>
|
||
</ol>
|
||
</li>
|
||
</ol>
|
||
|
||
<h3 id="a-pod-placed-by-a-config-file-on-the-node">A pod placed by a config file on the node</h3>
|
||
|
||
<ol>
|
||
<li>
|
||
<p>A config file is stored on the node, containing a pod with UID=””, Namespace=””, and Name=”cadvisor”.</p>
|
||
</li>
|
||
<li>Kubelet validates the input.
|
||
<ol>
|
||
<li>Since UID is not provided, kubelet generates one.</li>
|
||
<li>Since Namespace is not provided, kubelet generates one.
|
||
<ol>
|
||
<li>The generated namespace should be deterministic and cluster-unique for the source, such as a hash of the hostname and file path.
|
||
<ul>
|
||
<li>E.g. Namespace=”file-f4231812554558a718a01ca942782d81”</li>
|
||
</ul>
|
||
</li>
|
||
</ol>
|
||
</li>
|
||
</ol>
|
||
</li>
|
||
<li>Kubelet runs the pod.
|
||
<ol>
|
||
<li>Each container is started up with enough metadata to distinguish the pod from whence it came.</li>
|
||
<li>Each attempt to run a container is assigned a UID (a string) that is unique across time.
|
||
<ol>
|
||
<li>This may correspond to Docker’s container ID.</li>
|
||
</ol>
|
||
</li>
|
||
</ol>
|
||
</li>
|
||
</ol>
|
||
|
||
<!-- BEGIN MUNGE: IS_VERSIONED -->
|
||
<!-- TAG IS_VERSIONED -->
|
||
<!-- END MUNGE: IS_VERSIONED -->
|
||
|
||
<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
|
||
<p><a href=""><img src="https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/design/identifiers.md?pixel" alt="Analytics" /></a>
|
||
<!-- END MUNGE: GENERATED_ANALYTICS --></p>
|
||
|
||
|
||
</div>
|
||
</section>
|
||
|
||
|
||
<footer>
|
||
<main class="light-text">
|
||
<nav>
|
||
<a href="/getting-started.html">Getting Started</a>
|
||
<a href="/docs.html">Documentation</a>
|
||
<a href="http://blog.kubernetes.io/">Blog</a>
|
||
<a href="/foobang.html">Community</a>
|
||
</nav>
|
||
<div class="social">
|
||
<a href="https://twitter.com/kubernetesio" class="twitter"><span>twitter</span></a>
|
||
<a href="https://github.com/kubernetes/kubernetes" class="github"><span>Github</span></a>
|
||
<a href="http://slack.k8s.io/" class="slack"><span>Slack</span></a>
|
||
<a href="http://stackoverflow.com/questions/tagged/kubernetes" class="stack-overflow"><span>stackoverflow</span></a>
|
||
<a href="https://groups.google.com/forum/#!forum/google-containers" class="mailing-list"><span>Mailing List</span></a>
|
||
<label for="wishField">I wish this page <input type="text" id="wishField" name="wishField" placeholder="made better textfield suggestions"></label>
|
||
</div>
|
||
<div class="center">© 2016 Kubernetes</div>
|
||
</main>
|
||
</footer>
|
||
|
||
</body>
|
||
</html>
|
||
|
||
|
||
|