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:
parent
03cea0ef23
commit
fae92d5f0a
10 changed files with 111 additions and 111 deletions
|
@ -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>...]`
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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**' ]
|
||||
|
|
|
@ -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`
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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>...]
|
||||
|
|
|
@ -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
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Add table
Reference in a new issue