1
0
Fork 0
mirror of https://github.com/moby/moby.git synced 2022-11-09 12:21:53 -05:00

Documentation changes for labels

Signed-off-by: Darren Shepherd <darren@rancher.com>
This commit is contained in:
Darren Shepherd 2015-03-16 13:28:55 -07:00
parent 03cea0ef23
commit fae92d5f0a
10 changed files with 111 additions and 111 deletions

View file

@ -144,16 +144,19 @@ A Dockerfile is similar to a Makefile.
the image.
**LABEL**
--**LABEL <key>[=<value>] [<key>[=<value>] ...]**
-- `LABEL <key>[=<value>] [<key>[=<value>] ...]`
The **LABEL** instruction adds metadata to an image. A **LABEL** is a
key-value pair. To include spaces within a **LABEL** value, use quotes and
blackslashes as you would in command-line parsing.
The **LABEL** instruction allows you to add meta-data to the image your
Dockerfile is building. LABEL is specified as name value pairs. This data can
be retrieved using the `docker inspect` command.
```
LABEL "com.example.vendor"="ACME Incorporated"
```
The LABEL instruction allows for multiple labels to be set at one time. Like
command line parsing, quotes and backslashes can be used to include spaces
within values.
An image can have more than one label. To specify multiple labels, separate each
key-value pair by a space.
To display an image's labels, use the `docker inspect` command.
**EXPOSE**
-- `EXPOSE <port> [<port>...]`

View file

@ -105,10 +105,10 @@ IMAGE [COMMAND] [ARG...]
'host': use the host shared memory,semaphores and message queues inside the container. Note: the host mode gives the container full access to local shared memory and is therefore considered insecure.
**-l**, **--label**=[]
Set meta data on the container (e.g., --label=com.example.key=value)
Set metadata on the container (e.g., --label=com.example.key=value)
**--label-file**=[]
Read in a line delimited file of labels
Read in a file of labels (EOL delimited)
**--link**=[]
Add link to another container in the form of <name or id>:alias

View file

@ -34,9 +34,7 @@ versions.
Show all images (by default filter out the intermediate image layers). The default is *false*.
**-f**, **--filter**=[]
Provide filter values. Valid filters:
dangling=true - unlabeled images with no children
label=<key> or label=<key>=<value>
Filters the output. The dangling=true filter finds unused images. While label=com.foo=amd64 filters for images with a com.foo value of amd64. The label=com.foo filter finds images with the label com.foo of any value.
**--help**
Print usage statement

View file

@ -200,7 +200,7 @@ ENTRYPOINT.
'host': use the host shared memory,semaphores and message queues inside the container. Note: the host mode gives the container full access to local shared memory and is therefore considered insecure.
**-l**, **--label**=[]
Set meta data on the container (e.g., --label=com.example.key=value)
Set metadata on the container (e.g., --label com.example.key=value)
**--label-file**=[]
Read in a line delimited file of labels

View file

@ -59,7 +59,7 @@ pages:
- ['userguide/dockerimages.md', 'User Guide', 'Working with Docker Images' ]
- ['userguide/dockerlinks.md', 'User Guide', 'Linking containers together' ]
- ['userguide/dockervolumes.md', 'User Guide', 'Managing data in containers' ]
- ['userguide/labels-custom-metadata.md', 'User Guide', 'Labels - custom meta-data in Docker' ]
- ['userguide/labels-custom-metadata.md', 'User Guide', 'Labels - custom metadata in Docker' ]
- ['userguide/dockerrepos.md', 'User Guide', 'Working with Docker Hub' ]
- ['userguide/level1.md', '**HIDDEN**' ]
- ['userguide/level2.md', '**HIDDEN**' ]

View file

@ -71,9 +71,8 @@ This endpoint now returns `SystemTime`, `HttpProxy`,`HttpsProxy` and `NoProxy`.
### What's new
**New!**
Build now has support for `LABEL` command which can be used to add user data
to an image. For example you could add data describing the content of an image.
The build supports `LABEL` command. Use this to add metadata
to an image. For example you could add data describing the content of an image.
`LABEL "com.example.vendor"="ACME Incorporated"`
@ -91,7 +90,7 @@ You can set labels on container create describing the container.
`GET /containers/json`
**New!**
This endpoint now returns the labels associated with each container (`Labels`).
The endpoint returns the labels associated with the containers (`Labels`).
`GET /containers/(id)/json`

View file

@ -195,8 +195,7 @@ Json Parameters:
- **OpenStdin** - Boolean value, opens stdin,
- **StdinOnce** - Boolean value, close stdin after the 1 attached client disconnects.
- **Env** - A list of environment variables in the form of `VAR=value`
- **Labels** - A map of labels and their values that will be added to the
container. It should be specified in the form `{"name":"value"[,"name2":"value2"]}`
- **Labels** - Adds a map of labels that to a container. To specify a map: `{"key":"value"[,"key2":"value2"]}`
- **Cmd** - Command to run specified as a string or an array of strings.
- **Entrypoint** - Set the entrypoint for the container a a string or an array
of strings

View file

@ -329,26 +329,26 @@ default specified in `CMD`.
> the intended command for the image.
## LABEL
LABEL <key>=<value> <key>=<value> <key>=<value> ...
The `LABEL` instruction allows you to add meta-data to the image your
`Dockerfile` is building. `LABEL` is specified as name value pairs. This data can
be retrieved using the `docker inspect` command
LABEL <key>=<value> <key>=<value> <key>=<value> ...
The `LABEL` instruction adds metadata to an image. A `LABEL` is a
key-value pair. To include spaces within a `LABEL` value, use quotes and
blackslashes as you would in command-line parsing.
LABEL "com.example.vendor"="ACME Incorporated"
An image can have more than one label. To specify multiple labels, separate each
key-value pair by an EOL.
LABEL com.example.label-without-value
LABEL com.example.label-with-value="foo"
LABEL version="1.0"
LABEL description="This my ACME image" vendor="ACME Products"
As illustrated above, the `LABEL` instruction allows for multiple labels to be
set at one time. Like command line parsing, quotes and backslashes can be used
to include spaces within values.
For example:
LABEL description="This text illustrates \
that label-values can span multiple lines."
To view an image's labels, use the `docker inspect` command.
## EXPOSE
EXPOSE <port> [<port>...]

View file

@ -791,7 +791,7 @@ Creates a new container.
-h, --hostname="" Container host name
-i, --interactive=false Keep STDIN open even if not attached
--ipc="" IPC namespace to use
-l, --label=[] Set meta data on the container (e.g., --label=com.example.key=value)
-l, --label=[] Set metadata on the container (e.g., --label=com.example.key=value)
--label-file=[] Read in a line delimited file of labels
--link=[] Add link to another container
--lxc-conf=[] Add custom lxc options
@ -1665,8 +1665,8 @@ removed before the image is removed.
--link=[] Add link to another container
--lxc-conf=[] Add custom lxc options
-m, --memory="" Memory limit
-l, --label=[] Set meta data on the container (e.g., --label=com.example.key=value)
--label-file=[] Read in a line delimited file of labels
-l, --label=[] Set metadata on the container (e.g., --label=com.example.key=value)
--label-file=[] Read in a file of labels (EOL delimited)
--mac-address="" Container MAC address (e.g. 92:d0:c6:0a:29:33)
--memory-swap="" Total memory (memory + swap), '-1' to disable swap
--name="" Assign a name to the container
@ -1837,38 +1837,39 @@ An example of a file passed with `--env-file`
$ sudo docker run --name console -t -i ubuntu bash
This will create and run a new container with the container name being
`console`.
A label is a a `key=value` pair that applies metadata to a container. To label a container with two labels:
$ sudo docker run -l my-label --label com.example.foo=bar ubuntu bash
This sets two labels on the container. Label "my-label" doesn't have a value
specified and will default to "" (empty string) for its value. Both `-l` and
`--label` can be repeated to add more labels. Label names are unique; if the same
label is specified multiple times, latter values overwrite the previous value.
The `my-label` key doesn't specify so the label defaults to an empty
string(`""`). To add multiple labels, repeat the label flag (`-l` or
`--label`).
Labels can also be loaded from a line delimited file of labels using the
`--label-file` flag. The example below will load labels from a file named `labels`
in the current directory;
The `key=value` must be unique. If you specify the same key multiple times
with different values, each subsequent value overwrites the previous. Docker
applies the last `key=value` you supply.
Use the `--label-file` flag to load multiple labels from a file. Delimit each
label in the file with an EOL mark. The example below loads labels from a
labels file in the current directory;
$ sudo docker run --label-file ./labels ubuntu bash
The format of the labels-file is similar to that used for loading environment
variables (see `--label-file` above). An example of a file passed with `--label-file`;
The label-file format is similar to the format for loading environment variables
(see `--env-file` above). The following example illustrates a label-file format;
$ cat ./labels
com.example.label1="a label"
# this is a comment
com.example.label2=another\ label
com.example.label3
Multiple label-files can be loaded by providing the `--label-file` multiple
You can load multiple label-files by supplying the `--label-file` flag multiple
times.
For additional information on working with labels, see
[*Labels - custom meta-data in Docker*](/userguide/labels-custom-metadata/) in
the user guide.
For additional information on working with labels, see
[*Labels - custom metadata in Docker*](/userguide/labels-custom-metadata/) in
the Docker User Guide.
$ sudo docker run --link /redis:redis --name console ubuntu bash

View file

@ -1,61 +1,67 @@
page_title: Labels - custom meta-data in Docker
page_description: Learn how to work with custom meta-data in Docker, using labels.
page_keywords: Usage, user guide, labels, meta-data, docker, documentation, examples, annotating
page_title: Labels - custom metadata in Docker
page_description: Learn how to work with custom metadata in Docker, using labels.
page_keywords: Usage, user guide, labels, metadata, docker, documentation, examples, annotating
## Labels - custom meta-data in Docker
## Labels - custom metadata in Docker
Docker enables you to add meta-data to your images, containers, and daemons via
labels. Meta-data can serve a wide range of uses ranging from adding notes or
licensing information to an image to identifying a host.
You can add metadata to your images, containers, and daemons via
labels. Metadata can serve a wide range of uses. Use them to add notes or
licensing information to an image or to identify a host.
Labels in Docker are implemented as `<key>` / `<value>` pairs and values are
stored as *strings*.
A label is a `<key>` / `<value>` pair. Docker stores the values as *strings*.
You can specify multiple labels but each `<key>` / `<value>` must be unique. If
you specify the same `key` multiple times with different values, each subsequent
value overwrites the previous. Docker applies the last `key=value` you supply.
>**note:** Support for daemon-labels was added in docker 1.4.1, labels on
>containers and images in docker 1.6.0
>**note:** Support for daemon-labels was added in Docker 1.4.1. Labels on
>containers and images are new in Docker 1.6.0
### Naming your labels - namespaces
Docker puts no hard restrictions on the names you pick for your labels, however,
it's easy for labels to "conflict".
For example, you're building a tool that categorizes your images in
architectures, doing so by using an "architecture" label;
Docker puts no hard restrictions on the label `key` you. However, labels can
conflict. For example, you can categorize your images by using a chip "architecture"
label:
LABEL architecture="amd64"
LABEL architecture="ARMv7"
But a user decided to label images by Architectural style
But a user can label images by building architectural style:
LABEL architecture="Art Nouveau"
To prevent such conflicts, Docker uses the convention to namespace label-names,
using a reverse domain notation;
To prevent such conflicts, Docker namespaces label keys using a reverse domain
notation. This notation has the following guidelines:
- All (third-party) tools should namespace (prefix) their labels with the
reverse DNS notation of a domain controlled by the author of the tool. For
example, "com.example.some-label".
- Namespaced labels should only consist of lower-cased alphanumeric characters,
dots and dashes (in short, `[a-z0-9-.]`), should start *and* end with an alpha
numeric character, and may not contain consecutive dots or dashes.
- 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`.
- The `com.docker.*`, `io.docker.*` and `com.dockerproject.*` namespaces are
reserved for Docker's internal use.
- Labels *without* namespace (dots) are reserved for CLI use. This allows end-
users to add meta-data to their containers and images, without having to type
- Keys should only consist of lower-cased alphanumeric characters,
dots and dashes (for example, `[a-z0-9-.]`)
- Keys should start *and* end with an alpha numeric character
- Keys may not contain consecutive dots or dashes.
- 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.
> **Note:** Even though Docker does not *enforce* you to use namespaces,
> preventing to do so will likely result in conflicting usage of labels.
> If you're building a tool that uses labels, you *should* use namespaces
> for your labels.
These are guidelines and are not enforced. Docker does not *enforce* them.
Failing following these guidelines can result in conflicting labels. If you're
building a tool that uses labels, you *should* use namespaces for your label keys.
### Storing structured data in labels
Labels can store any type of data, as long as its stored as a string.
Label values can contain any data type as long as the value can be stored as a
string. For example, consider this JSON:
{
@ -68,31 +74,28 @@ Labels can store any type of data, as long as its stored as a string.
"aNestedArray": ["a", "b", "c"]
}
Which can be stored in a label by serializing it to a string first;
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.
> **Note:** Although the example above shows it's *possible* to store structured
> data in labels, Docker does not treat this data any other way than 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 should implement this.
If your tool needs to filter on nested properties, the tool itself should
implement this.
### Adding labels to images; the `LABEL` instruction
Adding labels to your
Adding labels to an image:
LABEL [<namespace>.]<name>[=<value>] ...
LABEL [<namespace>.]<key>[=<value>] ...
The `LABEL` instruction adds a label to your image, optionally setting its value.
Quotes surrounding name and value are optional, but required if they contain
white space characters. Alternatively, backslashes can be used.
Label values only support strings
Use surrounding quotes or backslashes for labels that contain
white space character:
LABEL vendor=ACME\ Incorporated
LABEL com.example.version.is-beta
@ -104,15 +107,19 @@ using this notation;
LABEL com.example.version="0.0.1-beta" com.example.release-date="2015-02-12"
Wrapping is allowed by using a backslash (`\`) as continuation marker;
Wrapping is allowed by using a backslash (`\`) as continuation marker:
LABEL vendor=ACME\ Incorporated \
com.example.is-beta \
com.example.version="0.0.1-beta" \
com.example.release-date="2015-02-12"
Docker recommends combining labels in a single `LABEL` instruction instead of
using a `LABEL` instruction for each label. Each instruction in a Dockerfile
produces a new layer that can result in an inefficient image if you use many
labels.
You can view the labels via `docker inspect`
You can view the labels via the `docker inspect` command:
$ docker inspect 4fa6e0f0c678
@ -129,27 +136,21 @@ You can view the labels via `docker inspect`
{"Vendor":"ACME Incorporated","com.example.is-beta":"","com.example.version":"0.0.1-beta","com.example.release-date":"2015-02-12"}
> **note:** We recommend combining labels in a single `LABEl` instruction in
> stead of using a `LABEL` instruction for each label. Each instruction in a
> Dockerfile produces a new layer, which can result in an inefficient image if
> many labels are used.
### Querying labels
Besides storing meta-data, labels can be used to filter your images and
containers.
List all running containers that have a `com.example.is-beta` label;
Besides storing metadata, you can filter images and labels by label. To list all
running containers that have a `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 a "color" label set to "blue";
List all running containers with a `color` label of `blue`:
$ docker ps --filter "label=color=blue"
List all images with "vendor" "ACME"
List all images with `vendor` `ACME`:
$ docker images --filter "label=vendor=ACME"
@ -157,7 +158,6 @@ List all images with "vendor" "ACME"
### Daemon labels
docker -d \
--dns 8.8.8.8 \
--dns 8.8.4.4 \
@ -165,7 +165,7 @@ List all images with "vendor" "ACME"
--label com.example.environment="production" \
--label com.example.storage="ssd"
And can be seen as part of the `docker info` output for the daemon;
These labels appear as part of the `docker info` output for the daemon:
docker -D info
Containers: 12