kotovalexarian-likes-github/moby--moby
1
0
Fork 0
mirror of https://github.com/moby/moby.git synced 2022-11-09 12:21:53 -05:00
Code Releases Activity
moby--moby/docs/userguide/labels-custom-metadata.md

117 lines
5.1 KiB
Markdown
Raw Normal View History

retooling for hugo Tweaking for Hugo Updating the Dockerfile with new sed; fix broken link on Kitematic Fixing image pull for Dockerfile Removing docs targets Signed-off-by: Mary Anthony <mary@docker.com>
2015-06-07 23:07:20 -04:00
<!--[metadata]>
+++
Restructure content about Docker object labels A few points of work: - Took the topic out of the left-hand nav and made it reachable from the User guide intro - Condensed the topic's contents, presenting only conceptual info and pointing instead to the command-line references for each type of object - Added brief information about the `LABELS` keyword to the Dockerfile reference A big part of the point is to establish a pattern of thinking and use around how Docker uses labels and what they mean in different contexts. Signed-off-by: Misty Stanley-Jones <misty@docker.com>
2016-09-15 20:26:12 -04:00
title = "Managing Docker object labels"
description = "Description of labels, which are used to manage metadata on Docker objects."
keywords = ["Usage, user guide, labels, metadata, docker, documentation, examples, annotating"]
retooling for hugo Tweaking for Hugo Updating the Dockerfile with new sed; fix broken link on Kitematic Fixing image pull for Dockerfile Removing docs targets Signed-off-by: Mary Anthony <mary@docker.com>
2015-06-07 23:07:20 -04:00
[menu.main]
Fix menu position of the labels-custom-metadata.md topic Signed-off-by: Misty Stanley-Jones <misty@docker.com>
2016-09-29 13:51:08 -04:00
parent = "engine_guide"
weight=100
retooling for hugo Tweaking for Hugo Updating the Dockerfile with new sed; fix broken link on Kitematic Fixing image pull for Dockerfile Removing docs targets Signed-off-by: Mary Anthony <mary@docker.com>
2015-06-07 23:07:20 -04:00
+++
<![end-metadata]-->
Add labels documentation Adds more documentation for labels and adds the label instruction to the man-pages. Also included is a document called "Labels - custom meta-data in Docker" in the user-guide, this is still a work-in-progress I started to describe the "namespaces" conventions, an example on storing structured data. I ran a bit "out of steam" (writers block?) on that document, but kept it in (for now), in case it still ends up useful. The Remote API documentation changes will need to be moved to the docker_remote_api_v1.18.md document when rebasing the whole PR. Signed-off-by: Sebastiaan van Stijn <github@gone.nl> Signed-off-by: Darren Shepherd <darren@rancher.com>
2015-02-16 19:36:03 -05:00
Restructure content about Docker object labels A few points of work: - Took the topic out of the left-hand nav and made it reachable from the User guide intro - Condensed the topic's contents, presenting only conceptual info and pointing instead to the command-line references for each type of object - Added brief information about the `LABELS` keyword to the Dockerfile reference A big part of the point is to establish a pattern of thinking and use around how Docker uses labels and what they mean in different contexts. Signed-off-by: Misty Stanley-Jones <misty@docker.com>
2016-09-15 20:26:12 -04:00
# About labels
Add labels documentation Adds more documentation for labels and adds the label instruction to the man-pages. Also included is a document called "Labels - custom meta-data in Docker" in the user-guide, this is still a work-in-progress I started to describe the "namespaces" conventions, an example on storing structured data. I ran a bit "out of steam" (writers block?) on that document, but kept it in (for now), in case it still ends up useful. The Remote API documentation changes will need to be moved to the docker_remote_api_v1.18.md document when rebasing the whole PR. Signed-off-by: Sebastiaan van Stijn <github@gone.nl> Signed-off-by: Darren Shepherd <darren@rancher.com>
2015-02-16 19:36:03 -05:00
Restructure content about Docker object labels A few points of work: - Took the topic out of the left-hand nav and made it reachable from the User guide intro - Condensed the topic's contents, presenting only conceptual info and pointing instead to the command-line references for each type of object - Added brief information about the `LABELS` keyword to the Dockerfile reference A big part of the point is to establish a pattern of thinking and use around how Docker uses labels and what they mean in different contexts. Signed-off-by: Misty Stanley-Jones <misty@docker.com>
2016-09-15 20:26:12 -04:00
Labels are a mechanism for applying metadata to Docker objects, including:
Add labels documentation Adds more documentation for labels and adds the label instruction to the man-pages. Also included is a document called "Labels - custom meta-data in Docker" in the user-guide, this is still a work-in-progress I started to describe the "namespaces" conventions, an example on storing structured data. I ran a bit "out of steam" (writers block?) on that document, but kept it in (for now), in case it still ends up useful. The Remote API documentation changes will need to be moved to the docker_remote_api_v1.18.md document when rebasing the whole PR. Signed-off-by: Sebastiaan van Stijn <github@gone.nl> Signed-off-by: Darren Shepherd <darren@rancher.com>
2015-02-16 19:36:03 -05:00
Restructure content about Docker object labels A few points of work: - Took the topic out of the left-hand nav and made it reachable from the User guide intro - Condensed the topic's contents, presenting only conceptual info and pointing instead to the command-line references for each type of object - Added brief information about the `LABELS` keyword to the Dockerfile reference A big part of the point is to establish a pattern of thinking and use around how Docker uses labels and what they mean in different contexts. Signed-off-by: Misty Stanley-Jones <misty@docker.com>
2016-09-15 20:26:12 -04:00
- Images
- Containers
- Local daemons
- Volumes
- Networks
- Swarm nodes
- Swarm services
Add labels documentation Adds more documentation for labels and adds the label instruction to the man-pages. Also included is a document called "Labels - custom meta-data in Docker" in the user-guide, this is still a work-in-progress I started to describe the "namespaces" conventions, an example on storing structured data. I ran a bit "out of steam" (writers block?) on that document, but kept it in (for now), in case it still ends up useful. The Remote API documentation changes will need to be moved to the docker_remote_api_v1.18.md document when rebasing the whole PR. Signed-off-by: Sebastiaan van Stijn <github@gone.nl> Signed-off-by: Darren Shepherd <darren@rancher.com>
2015-02-16 19:36:03 -05:00
Restructure content about Docker object labels A few points of work: - Took the topic out of the left-hand nav and made it reachable from the User guide intro - Condensed the topic's contents, presenting only conceptual info and pointing instead to the command-line references for each type of object - Added brief information about the `LABELS` keyword to the Dockerfile reference A big part of the point is to establish a pattern of thinking and use around how Docker uses labels and what they mean in different contexts. Signed-off-by: Misty Stanley-Jones <misty@docker.com>
2016-09-15 20:26:12 -04:00
You can use labels to organize your images, record licensing information, annotate
relationships between containers, volumes, and networks, or in any way that makes
sense for your business or application.
Add labels documentation Adds more documentation for labels and adds the label instruction to the man-pages. Also included is a document called "Labels - custom meta-data in Docker" in the user-guide, this is still a work-in-progress I started to describe the "namespaces" conventions, an example on storing structured data. I ran a bit "out of steam" (writers block?) on that document, but kept it in (for now), in case it still ends up useful. The Remote API documentation changes will need to be moved to the docker_remote_api_v1.18.md document when rebasing the whole PR. Signed-off-by: Sebastiaan van Stijn <github@gone.nl> Signed-off-by: Darren Shepherd <darren@rancher.com>
2015-02-16 19:36:03 -05:00
Restructure content about Docker object labels A few points of work: - Took the topic out of the left-hand nav and made it reachable from the User guide intro - Condensed the topic's contents, presenting only conceptual info and pointing instead to the command-line references for each type of object - Added brief information about the `LABELS` keyword to the Dockerfile reference A big part of the point is to establish a pattern of thinking and use around how Docker uses labels and what they mean in different contexts. Signed-off-by: Misty Stanley-Jones <misty@docker.com>
2016-09-15 20:26:12 -04:00
# Label keys and values
Add labels documentation Adds more documentation for labels and adds the label instruction to the man-pages. Also included is a document called "Labels - custom meta-data in Docker" in the user-guide, this is still a work-in-progress I started to describe the "namespaces" conventions, an example on storing structured data. I ran a bit "out of steam" (writers block?) on that document, but kept it in (for now), in case it still ends up useful. The Remote API documentation changes will need to be moved to the docker_remote_api_v1.18.md document when rebasing the whole PR. Signed-off-by: Sebastiaan van Stijn <github@gone.nl> Signed-off-by: Darren Shepherd <darren@rancher.com>
2015-02-16 19:36:03 -05:00
Restructure content about Docker object labels A few points of work: - Took the topic out of the left-hand nav and made it reachable from the User guide intro - Condensed the topic's contents, presenting only conceptual info and pointing instead to the command-line references for each type of object - Added brief information about the `LABELS` keyword to the Dockerfile reference A big part of the point is to establish a pattern of thinking and use around how Docker uses labels and what they mean in different contexts. Signed-off-by: Misty Stanley-Jones <misty@docker.com>
2016-09-15 20:26:12 -04:00
A label is a key-value pair, stored as a string. You can specify multiple labels
for an object, but each key-value pair must be unique within an object. If the
same key is given multiple values, the most-recently-written value overwrites
all previous values.
Add labels documentation Adds more documentation for labels and adds the label instruction to the man-pages. Also included is a document called "Labels - custom meta-data in Docker" in the user-guide, this is still a work-in-progress I started to describe the "namespaces" conventions, an example on storing structured data. I ran a bit "out of steam" (writers block?) on that document, but kept it in (for now), in case it still ends up useful. The Remote API documentation changes will need to be moved to the docker_remote_api_v1.18.md document when rebasing the whole PR. Signed-off-by: Sebastiaan van Stijn <github@gone.nl> Signed-off-by: Darren Shepherd <darren@rancher.com>
2015-02-16 19:36:03 -05:00
Restructure content about Docker object labels A few points of work: - Took the topic out of the left-hand nav and made it reachable from the User guide intro - Condensed the topic's contents, presenting only conceptual info and pointing instead to the command-line references for each type of object - Added brief information about the `LABELS` keyword to the Dockerfile reference A big part of the point is to establish a pattern of thinking and use around how Docker uses labels and what they mean in different contexts. Signed-off-by: Misty Stanley-Jones <misty@docker.com>
2016-09-15 20:26:12 -04:00
## Key format recommendations
Add labels documentation Adds more documentation for labels and adds the label instruction to the man-pages. Also included is a document called "Labels - custom meta-data in Docker" in the user-guide, this is still a work-in-progress I started to describe the "namespaces" conventions, an example on storing structured data. I ran a bit "out of steam" (writers block?) on that document, but kept it in (for now), in case it still ends up useful. The Remote API documentation changes will need to be moved to the docker_remote_api_v1.18.md document when rebasing the whole PR. Signed-off-by: Sebastiaan van Stijn <github@gone.nl> Signed-off-by: Darren Shepherd <darren@rancher.com>
2015-02-16 19:36:03 -05:00
Restructure content about Docker object labels A few points of work: - Took the topic out of the left-hand nav and made it reachable from the User guide intro - Condensed the topic's contents, presenting only conceptual info and pointing instead to the command-line references for each type of object - Added brief information about the `LABELS` keyword to the Dockerfile reference A big part of the point is to establish a pattern of thinking and use around how Docker uses labels and what they mean in different contexts. Signed-off-by: Misty Stanley-Jones <misty@docker.com>
2016-09-15 20:26:12 -04:00
A label _key_ is the left-hand side of the key-value pair. Keys are alphanumeric
strings which may contain periods (`.`) and hyphens (`-`). Most Docker users use
images created by other organizations, and the following guidelines help to
prevent inadvertent duplication of labels across objects, especially if you plan
to use labels as a mechanism for automation.
Add labels documentation Adds more documentation for labels and adds the label instruction to the man-pages. Also included is a document called "Labels - custom meta-data in Docker" in the user-guide, this is still a work-in-progress I started to describe the "namespaces" conventions, an example on storing structured data. I ran a bit "out of steam" (writers block?) on that document, but kept it in (for now), in case it still ends up useful. The Remote API documentation changes will need to be moved to the docker_remote_api_v1.18.md document when rebasing the whole PR. Signed-off-by: Sebastiaan van Stijn <github@gone.nl> Signed-off-by: Darren Shepherd <darren@rancher.com>
2015-02-16 19:36:03 -05:00
Restructure content about Docker object labels A few points of work: - Took the topic out of the left-hand nav and made it reachable from the User guide intro - Condensed the topic's contents, presenting only conceptual info and pointing instead to the command-line references for each type of object - Added brief information about the `LABELS` keyword to the Dockerfile reference A big part of the point is to establish a pattern of thinking and use around how Docker uses labels and what they mean in different contexts. Signed-off-by: Misty Stanley-Jones <misty@docker.com>
2016-09-15 20:26:12 -04:00
- Authors of third-party tools should prefix each label key with the
reverse DNS notation of a domain they own, such as `com.example.some-label`.
Add labels documentation Adds more documentation for labels and adds the label instruction to the man-pages. Also included is a document called "Labels - custom meta-data in Docker" in the user-guide, this is still a work-in-progress I started to describe the "namespaces" conventions, an example on storing structured data. I ran a bit "out of steam" (writers block?) on that document, but kept it in (for now), in case it still ends up useful. The Remote API documentation changes will need to be moved to the docker_remote_api_v1.18.md document when rebasing the whole PR. Signed-off-by: Sebastiaan van Stijn <github@gone.nl> Signed-off-by: Darren Shepherd <darren@rancher.com>
2015-02-16 19:36:03 -05:00
Restructure content about Docker object labels A few points of work: - Took the topic out of the left-hand nav and made it reachable from the User guide intro - Condensed the topic's contents, presenting only conceptual info and pointing instead to the command-line references for each type of object - Added brief information about the `LABELS` keyword to the Dockerfile reference A big part of the point is to establish a pattern of thinking and use around how Docker uses labels and what they mean in different contexts. Signed-off-by: Misty Stanley-Jones <misty@docker.com>
2016-09-15 20:26:12 -04:00
- Do not use a domain in your label key without the domain owner's permission.
Add labels documentation Adds more documentation for labels and adds the label instruction to the man-pages. Also included is a document called "Labels - custom meta-data in Docker" in the user-guide, this is still a work-in-progress I started to describe the "namespaces" conventions, an example on storing structured data. I ran a bit "out of steam" (writers block?) on that document, but kept it in (for now), in case it still ends up useful. The Remote API documentation changes will need to be moved to the docker_remote_api_v1.18.md document when rebasing the whole PR. Signed-off-by: Sebastiaan van Stijn <github@gone.nl> Signed-off-by: Darren Shepherd <darren@rancher.com>
2015-02-16 19:36:03 -05:00
Update urls from .com to .org. I added 301 redirects from dockerproject.com to dockerproject.org but may as well make sure everything is updated anyways. Signed-off-by: Jessica Frazelle <princess@docker.com>
2015-06-03 15:08:40 -04:00
- The `com.docker.*`, `io.docker.*` and `org.dockerproject.*` namespaces are
Restructure content about Docker object labels A few points of work: - Took the topic out of the left-hand nav and made it reachable from the User guide intro - Condensed the topic's contents, presenting only conceptual info and pointing instead to the command-line references for each type of object - Added brief information about the `LABELS` keyword to the Dockerfile reference A big part of the point is to establish a pattern of thinking and use around how Docker uses labels and what they mean in different contexts. Signed-off-by: Misty Stanley-Jones <misty@docker.com>
2016-09-15 20:26:12 -04:00
reserved by Docker for internal use.
- Label keys should begin and end with a lower-case letter and should only
contain lower-case alphanumeric characters, the period character (`.`), and
the hyphen character (`-`). Consecutive periods or hyphens are not allowed.
- The period character (`.`) separates namespace "fields". Label keys without
namespaces are reserved for CLI use, allowing users of the CLI to interactively
label Docker objects using shorter typing-friendly strings.
These guidelines are not currently enforced and additional guidelines may apply
to specific use cases.
## Value guidelines
Label values can contain any data type that can be represented as a string,
including (but not limited to) JSON, XML, CSV, or YAML. The only requirement is
that the value be serialized to a string first, using a mechanism specific to
the type of structure. For instance, to serialize JSON into a string, you might
use the `JSON.stringify()` JavaScript method.
Since Docker does not deserialize the value, you cannot treat a JSON or XML
document as a nested structure when querying or filtering by label value unless
you build this functionality into third-party tooling.
# Managing labels on objects
Each type of object with support for labels has mechanisms for adding and
managing them and using them as they relate to that type of object. These links
provide a good place to start learning about how you can use labels in your
Docker deployments.
Labels on images, containers, local daemons, volumes, and networks are static for
the lifetime of the object. To change these labels you must recreate the object.
Labels on swarm nodes and services can be updated dynamically.
- Images and containers
- [Adding labels to images](../reference/builder.md#label)
- [Overriding a container's labels at runtime](../reference/commandline/run.md#set-metadata-on-container-l-label-label-file)
- [Inspecting labels on images or containers](../reference/commandline/inspect.md)
- [Filtering images by label](../reference/commandline/inspect.md#filtering)
- [Filtering containers by label](../reference/commandline/ps.md#filtering)
- Local Docker daemons
- [Adding labels to a Docker daemon at runtime](../reference/commandline/dockerd.md)
- [Inspecting a Docker daemon's labels](../reference/commandline/info.md)
- Volumes
- [Adding labels to volumes](../reference/commandline/volume_create.md)
- [Inspecting a volume's labels](../reference/commandline/volume_inspect.md)
- [Filtering volumes by label](../reference/commandline/volume_ls.md#filtering)
- Networks
- [Adding labels to a network](../reference/commandline/network_create.md)
- [Inspecting a network's labels](../reference/commandline/network_inspect.md)
- [Filtering networks by label](../reference/commandline/network_ls.md#filtering)
- Swarm nodes
- [Adding or updating a swarm node's labels](../reference/commandline/node_update.md#add-label-metadata-to-a-node)
- [Inspecting a swarm node's labels](../reference/commandline/node_inspect.md)
- [Filtering swarm nodes by label](../reference/commandline/node_ls.md#filtering)
- Swarm services
- [Adding labels when creating a swarm service](../reference/commandline/service_create.md#set-metadata-on-a-service-l-label)
- [Updating a swarm service's labels](../reference/commandline/service_update.md)
- [Inspecting a swarm service's labels](../reference/commandline/service_inspect.md)
- [Filtering swarm services by label](../reference/commandline/service_ls.md#filtering)
Copy permalink