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>
This commit is contained in:
Misty Stanley-Jones
parent
7e6db44e2b
commit
5c4c062ffc
3 changed files with 145 additions and 202 deletions
|
|
@ -134,6 +134,43 @@ image. We recommend the [Debian image](https://hub.docker.com/_/debian/)
|
|||
since it’s very tightly controlled and kept minimal (currently under 150 mb),
|
||||
while still being a full distribution.
|
||||
|
||||
### LABEL
|
||||
|
||||
[Understanding object labels](../labels-custom-metadata.md)
|
||||
|
||||
You can add labels to your image to help organize images by project, record
|
||||
licensing information, to aid in automation, or for other reasons. For each
|
||||
label, add a line beginning with `LABEL` and with one or more key-value pairs.
|
||||
The following examples show the different acceptable formats. Explanatory comments
|
||||
are included inline.
|
||||
|
||||
>**Note**: If your string contains spaces, it must be quoted **or** the spaces
|
||||
must be escaped. If your string contains inner quote characters (`"`), escape
|
||||
them as well.
|
||||
|
||||
```dockerfile
|
||||
# Set one or more individual labels
|
||||
LABEL com.example.version="0.0.1-beta"
|
||||
LABEL vendor="ACME Incorporated"
|
||||
LABEL com.example.release-date="2015-02-12"
|
||||
LABEL com.example.version.is-production=""
|
||||
|
||||
# Set multiple labels on one line
|
||||
LABEL com.example.version="0.0.1-beta" com.example.release-date="2015-02-12"
|
||||
|
||||
# Set multiple labels at once, using line-continuation characters to break long lines
|
||||
LABEL vendor=ACME\ Incorporated \
|
||||
com.example.is-beta= \
|
||||
com.example.is-production="" \
|
||||
com.example.version="0.0.1-beta" \
|
||||
com.example.release-date="2015-02-12"
|
||||
```
|
||||
|
||||
See [Understanding object labels](../labels-custom-metadata.md) for
|
||||
guidelines about acceptable label keys and values. For information about
|
||||
querying labels, refer to the items related to filtering in
|
||||
[Managing labels on objects](../labels-custom-metadata.md#managing-labels-on-objects).
|
||||
|
||||
### RUN
|
||||
|
||||
[Dockerfile reference for the RUN instruction](../../reference/builder.md#run)
|
||||
|
|
@ -142,7 +179,7 @@ As always, to make your `Dockerfile` more readable, understandable, and
|
|||
maintainable, split long or complex `RUN` statements on multiple lines separated
|
||||
with backslashes.
|
||||
|
||||
### apt-get
|
||||
#### apt-get
|
||||
|
||||
Probably the most common use-case for `RUN` is an application of `apt-get`. The
|
||||
`RUN apt-get` command, because it installs packages, has several gotchas to look
|
||||
|
|
|
|||
|
|
@ -3,6 +3,7 @@
|
|||
title = "Introduction"
|
||||
description = "Introduction to user guide"
|
||||
keywords = ["docker, introduction, documentation, about, technology, docker.io, user, guide, user's, manual, platform, framework, home, intro"]
|
||||
identifier = "engine_guide_intro"
|
||||
[menu.main]
|
||||
parent="engine_guide"
|
||||
+++
|
||||
|
|
@ -64,6 +65,25 @@ learning how to manage data, volumes and mounts inside our containers.
|
|||
|
||||
Go to [Managing Data in Containers](../tutorials/dockervolumes.md).
|
||||
|
||||
## Managing metadata (labels) for Docker objects
|
||||
|
||||
Labels are a mechanism for applying metadata to Docker objects, including:
|
||||
|
||||
- Images
|
||||
- Containers
|
||||
- Local daemons
|
||||
- Volumes
|
||||
- Networks
|
||||
- Swarm nodes
|
||||
- Swarm services
|
||||
|
||||
|
||||
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.
|
||||
|
||||
Go to [Managing Docker object labels](labels-custom-metadata.md).
|
||||
|
||||
## Docker products that complement Engine
|
||||
|
||||
Often, one powerful technology spawns many other inventions that make that easier to get to, easier to use, and more powerful. These spawned things share one common characteristic: they augment the central technology. The following Docker products expand on the core Docker Engine functions.
|
||||
|
|
|
|||
|
|
@ -1,230 +1,116 @@
|
|||
<!--[metadata]>
|
||||
+++
|
||||
title = "Apply custom metadata"
|
||||
description = "Learn how to work with custom metadata in Docker, using labels."
|
||||
keywords = ["Usage, user guide, labels, metadata, docker, documentation, examples, annotating"]
|
||||
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"]
|
||||
[menu.main]
|
||||
parent = "engine_guide"
|
||||
parent = "engine_guide_intro"
|
||||
weight=90
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
# Apply custom metadata
|
||||
# About labels
|
||||
|
||||
You can apply metadata to your images, containers, volumes, networks, nodes, services or daemons via
|
||||
labels. Labels serve a wide range of uses, such as adding notes or licensing
|
||||
information to an image, or to identify a host.
|
||||
Labels are a mechanism for applying metadata to Docker objects, including:
|
||||
|
||||
A label is a `<key>` / `<value>` pair. Docker stores the label values as
|
||||
*strings*. You can specify multiple labels but each `<key>` must be
|
||||
unique or the value will be overwritten. If you specify the same `key` several
|
||||
times but with different values, newer labels overwrite previous labels. Docker
|
||||
uses the last `key=value` you supply.
|
||||
- Images
|
||||
- Containers
|
||||
- Local daemons
|
||||
- Volumes
|
||||
- Networks
|
||||
- Swarm nodes
|
||||
- Swarm services
|
||||
|
||||
>**Note:** Support for daemon-labels was added in Docker 1.4.1. Labels on
|
||||
>containers and images were added in Docker 1.6.0
|
||||
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.
|
||||
|
||||
## Label keys (namespaces)
|
||||
# Label keys and values
|
||||
|
||||
Docker puts no hard restrictions on the `key` used for a label. However, using
|
||||
simple keys can easily lead to conflicts. For example, you have chosen to
|
||||
categorize your images by CPU architecture using "architecture" labels in
|
||||
your Dockerfiles:
|
||||
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.
|
||||
|
||||
LABEL architecture="amd64"
|
||||
## Key format recommendations
|
||||
|
||||
LABEL architecture="ARMv7"
|
||||
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.
|
||||
|
||||
Another user may apply the same label based on a building's "architecture":
|
||||
- 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`.
|
||||
|
||||
LABEL architecture="Art Nouveau"
|
||||
|
||||
To prevent naming conflicts, Docker recommends using namespaces to label keys
|
||||
using reverse domain notation. Use the following guidelines to name your keys:
|
||||
|
||||
- All (third-party) tools should prefix their keys with the
|
||||
reverse DNS notation of a domain controlled by the author. For
|
||||
example, `com.example.some-label`.
|
||||
- Do not use a domain in your label key without the domain owner's permission.
|
||||
|
||||
- The `com.docker.*`, `io.docker.*` and `org.dockerproject.*` namespaces are
|
||||
reserved for Docker's internal use.
|
||||
reserved by Docker for internal use.
|
||||
|
||||
- Keys should only consist of lower-cased alphanumeric characters,
|
||||
dots and dashes (for example, `[a-z0-9-.]`).
|
||||
- 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.
|
||||
|
||||
- Keys should start *and* end with an alpha numeric character.
|
||||
- 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.
|
||||
|
||||
- Keys may not contain consecutive dots or dashes.
|
||||
These guidelines are not currently enforced and additional guidelines may apply
|
||||
to specific use cases.
|
||||
|
||||
- Keys *without* namespace (dots) are reserved for CLI use. This allows end-
|
||||
users to add metadata to their containers and images without having to type
|
||||
cumbersome namespaces on the command-line.
|
||||
## 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.
|
||||
|
||||
|
||||
These are simply guidelines and Docker does not *enforce* them. However, for
|
||||
the benefit of the community, you *should* use namespaces for your label keys.
|
||||
- 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)
|
||||
|
||||
## Store structured data in labels
|
||||
- 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)
|
||||
|
||||
Label values can contain any data type as long as it can be represented as a
|
||||
string. For example, consider this JSON document:
|
||||
- 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)
|
||||
|
||||
{
|
||||
"Description": "A containerized foobar",
|
||||
"Usage": "docker run --rm example/foobar [args]",
|
||||
"License": "GPL",
|
||||
"Version": "0.0.1-beta",
|
||||
"aBoolean": true,
|
||||
"aNumber" : 0.01234,
|
||||
"aNestedArray": ["a", "b", "c"]
|
||||
}
|
||||
|
||||
You can store this struct in a label by serializing it to a string first:
|
||||
|
||||
LABEL com.example.image-specs="{\"Description\":\"A containerized foobar\",\"Usage\":\"docker run --rm example\\/foobar [args]\",\"License\":\"GPL\",\"Version\":\"0.0.1-beta\",\"aBoolean\":true,\"aNumber\":0.01234,\"aNestedArray\":[\"a\",\"b\",\"c\"]}"
|
||||
|
||||
While it is *possible* to store structured data in label values, Docker treats
|
||||
this data as a 'regular' string. This means that Docker doesn't offer ways to
|
||||
query (filter) based on nested properties. If your tool needs to filter on
|
||||
nested properties, the tool itself needs to implement this functionality.
|
||||
|
||||
|
||||
## Add labels to images
|
||||
|
||||
To add labels to an image, use the `LABEL` instruction in your Dockerfile:
|
||||
|
||||
|
||||
LABEL [<namespace>.]<key>=<value> ...
|
||||
|
||||
The `LABEL` instruction adds a label to your image. A `LABEL` consists of a `<key>`
|
||||
and a `<value>`.
|
||||
Use an empty string for labels that don't have a `<value>`,
|
||||
Use surrounding quotes or backslashes for labels that contain
|
||||
white space characters in the `<value>`:
|
||||
|
||||
LABEL vendor=ACME\ Incorporated
|
||||
LABEL com.example.version.is-beta=
|
||||
LABEL com.example.version.is-production=""
|
||||
LABEL com.example.version="0.0.1-beta"
|
||||
LABEL com.example.release-date="2015-02-12"
|
||||
|
||||
The `LABEL` instruction also supports setting multiple `<key>` / `<value>` pairs
|
||||
in a single instruction:
|
||||
|
||||
LABEL com.example.version="0.0.1-beta" com.example.release-date="2015-02-12"
|
||||
|
||||
Long lines can be split up by using a backslash (`\`) as continuation marker:
|
||||
|
||||
LABEL vendor=ACME\ Incorporated \
|
||||
com.example.is-beta= \
|
||||
com.example.is-production="" \
|
||||
com.example.version="0.0.1-beta" \
|
||||
com.example.release-date="2015-02-12"
|
||||
|
||||
Docker recommends you add multiple labels in a single `LABEL` instruction. Using
|
||||
individual instructions for each label can result in an inefficient image. This
|
||||
is because each `LABEL` instruction in a Dockerfile produces a new IMAGE layer.
|
||||
|
||||
You can view the labels via the `docker inspect` command:
|
||||
|
||||
$ docker inspect 4fa6e0f0c678
|
||||
|
||||
...
|
||||
"Labels": {
|
||||
"vendor": "ACME Incorporated",
|
||||
"com.example.is-beta": "",
|
||||
"com.example.is-production": "",
|
||||
"com.example.version": "0.0.1-beta",
|
||||
"com.example.release-date": "2015-02-12"
|
||||
}
|
||||
...
|
||||
|
||||
# Inspect labels on container
|
||||
$ docker inspect -f "{{json .Config.Labels }}" 4fa6e0f0c678
|
||||
|
||||
{"Vendor":"ACME Incorporated","com.example.is-beta":"", "com.example.is-production":"", "com.example.version":"0.0.1-beta","com.example.release-date":"2015-02-12"}
|
||||
|
||||
# Inspect labels on images
|
||||
$ docker inspect -f "{{json .ContainerConfig.Labels }}" myimage
|
||||
|
||||
|
||||
## Query labels
|
||||
|
||||
Besides storing metadata, you can filter images and containers by label. To list all
|
||||
running containers that have the `com.example.is-beta` label:
|
||||
|
||||
# List all running containers that have a `com.example.is-beta` label
|
||||
$ docker ps --filter "label=com.example.is-beta"
|
||||
|
||||
List all running containers with the label `color` that have a value `blue`:
|
||||
|
||||
$ docker ps --filter "label=color=blue"
|
||||
|
||||
List all images with the label `vendor` that have the value `ACME`:
|
||||
|
||||
$ docker images --filter "label=vendor=ACME"
|
||||
|
||||
|
||||
## Container labels
|
||||
|
||||
docker run \
|
||||
-d \
|
||||
--label com.example.group="webservers" \
|
||||
--label com.example.environment="production" \
|
||||
busybox \
|
||||
top
|
||||
|
||||
Please refer to the [Query labels](#query-labels) section above for information
|
||||
on how to query labels set on a container.
|
||||
|
||||
|
||||
## Daemon labels
|
||||
|
||||
dockerd \
|
||||
--dns 8.8.8.8 \
|
||||
--dns 8.8.4.4 \
|
||||
-H unix:///var/run/docker.sock \
|
||||
--label com.example.environment="production" \
|
||||
--label com.example.storage="ssd"
|
||||
|
||||
These labels appear as part of the `docker info` output for the daemon:
|
||||
|
||||
$ docker -D info
|
||||
|
||||
Containers: 12
|
||||
Running: 5
|
||||
Paused: 2
|
||||
Stopped: 5
|
||||
Images: 672
|
||||
Server Version: 1.9.0
|
||||
Storage Driver: aufs
|
||||
Root Dir: /var/lib/docker/aufs
|
||||
Backing Filesystem: extfs
|
||||
Dirs: 697
|
||||
Dirperm1 Supported: true
|
||||
Execution Driver: native-0.2
|
||||
Logging Driver: json-file
|
||||
Kernel Version: 3.19.0-22-generic
|
||||
Operating System: Ubuntu 15.04
|
||||
CPUs: 24
|
||||
Total Memory: 62.86 GiB
|
||||
Name: docker
|
||||
ID: I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S
|
||||
Debug mode (server): true
|
||||
File Descriptors: 59
|
||||
Goroutines: 159
|
||||
System Time: 2015-09-23T14:04:20.699842089+08:00
|
||||
EventsListeners: 0
|
||||
Init SHA1:
|
||||
Init Path: /usr/bin/docker
|
||||
Docker Root Dir: /var/lib/docker
|
||||
Http Proxy: http://test:test@localhost:8080
|
||||
Https Proxy: https://test:test@localhost:8080
|
||||
WARNING: No swap limit support
|
||||
Username: svendowideit
|
||||
Registry: [https://index.docker.io/v1/]
|
||||
Labels:
|
||||
com.example.environment=production
|
||||
com.example.storage=ssd
|
||||
- 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)
|
||||
|
|
|
|||
Loading…
Reference in a new issue