Write page templates and canonical examples.

Conflicts: _data/tasks.yml _data/tutorials.yml docs/tasks/access-kubernetes-api/http-proxy-access-api.md docs/tasks/index.md docs/tutorials/index.md
2016-09-23 15:40:21 -07:00
parent 51add3e397
commit 822d59b5e4
23 changed files with 1254 additions and 37 deletions
@@ -0,0 +1,14 @@
+---
+---
+
+The Concepts section of the Kubernetes documentation is a work in progress.
+
+#### Object Metadata
+
+[Annotations](/docs/concepts/object-metadata/annotations/)
+
+### What's next
+
+If you would like to write a concept page, see
+[Using Page Templates](/docs/contribute/page-templates/)
+for information about the concept page type and the concept template.
@@ -0,0 +1,60 @@
+---
+---
+
+{% capture overview %}
+You can use Kubernetes annotations to attach arbitrary non-identifying metadata
+to objects. Clients such as tools and libraries can retrieve this metadata.
+{% endcapture %}
+
+{% capture body %}
+### Attaching metadata to objects
+
+You can use either labels or annotations to attach metadata to Kubernetes
+objects. Labels can be used to select objects and to find
+collections of objects that satisfy certain conditions. In contrast, annotations
+are not used to identify and select objects. The metadata
+in an annotation can be small or large, structured or unstructured, and can
+include characters not permitted by labels.
+
+Annotations, like labels, are key/value maps:
+
+    "annotations": {
+      "key1" : "value1",
+      "key2" : "value2"
+    }
+
+Here are some examples of information that could be recorded in annotations:
+
+* Fields managed by a declarative configuration layer. Attaching these fields
+  as annotations distinguishes them from default values set by clients or
+  servers, and from auto-generated fields and fields set by
+  auto-sizing or auto-scaling systems.
+
+* Build, release, or image information like timestamps, release IDs, git branch,
+  PR numbers, image hashes, and registry address.
+
+* Pointers to logging, monitoring, analytics, or audit repositories.
+
+* Client library or tool information that can be used for debugging purposes:
+  for example, name, version, and build information.
+
+* User or tool/system provenance information, such as URLs of related objects
+  from other ecosystem components.
+
+* Lightweight rollout tool metadata: for example, config or checkpoints.
+
+* Phone or pager numbers of persons responsible, or directory entries that
+  specify where that information can be found, such as a team web site.
+
+Instead of using annotations, you could store this type of in information in an
+external database or directory, but that would make it much harder to produce
+shared client libraries and tools for deployment, management, introspection,
+and the like.
+
+{% endcapture %}
+
+{% capture whatsnext %}
+Learn more about [Labels and Selectors](/docs/user-guide/labels/).
+{% endcapture %}
+
+{% include templates/concept.md %}