github.com/vincentwoo/docker@v0.7.3-0.20160116130405-82401a4b13c0/docs/userguide/labels-custom-metadata.md (about)

     1  <!--[metadata]>
     2  +++
     3  title = "Apply custom metadata"
     4  description = "Learn how to work with custom metadata in Docker, using labels."
     5  keywords = ["Usage, user guide, labels, metadata, docker, documentation, examples,  annotating"]
     6  [menu.main]
     7  parent = "mn_use_docker"
     8  +++
     9  <![end-metadata]-->
    10  
    11  # Apply custom metadata
    12  
    13  You can apply metadata to your images, containers, or daemons via
    14  labels. Labels serve a wide range of uses, such as adding notes or licensing
    15  information to an image, or to identify a host.
    16  
    17  A label is a `<key>` / `<value>` pair. Docker stores the label values as
    18  *strings*. You can specify multiple labels but each `<key>` must be
    19  unique or the value will be overwritten. If you specify the same `key` several
    20  times but with different values, newer labels overwrite previous labels. Docker
    21  uses the last `key=value` you supply.
    22  
    23  >**Note:** Support for daemon-labels was added in Docker 1.4.1. Labels on
    24  >containers and images are new in Docker 1.6.0
    25  
    26  ## Label keys (namespaces)
    27  
    28  Docker puts no hard restrictions on the `key` used for a label. However, using
    29  simple keys can easily lead to conflicts. For example, you have chosen to
    30  categorize your images by CPU architecture using "architecture" labels in
    31  your Dockerfiles:
    32  
    33      LABEL architecture="amd64"
    34  
    35      LABEL architecture="ARMv7"
    36  
    37  Another user may apply the same label based on a building's "architecture":
    38  
    39      LABEL architecture="Art Nouveau"
    40  
    41  To prevent naming conflicts, Docker recommends using namespaces to label keys
    42  using reverse domain notation. Use the following guidelines to name your keys:
    43  
    44  - All (third-party) tools should prefix their keys with the
    45    reverse DNS notation of a domain controlled by the author. For
    46    example, `com.example.some-label`.
    47  
    48  - The `com.docker.*`, `io.docker.*` and `org.dockerproject.*` namespaces are
    49    reserved for Docker's internal use.
    50  
    51  - Keys should only consist of lower-cased alphanumeric characters,
    52    dots and dashes (for example, `[a-z0-9-.]`).
    53  
    54  - Keys should start *and* end with an alpha numeric character.
    55  
    56  - Keys may not contain consecutive dots or dashes.
    57  
    58  - Keys *without* namespace (dots) are reserved for CLI use. This allows end-
    59    users to add metadata to their containers and images without having to type
    60    cumbersome namespaces on the command-line.
    61  
    62  
    63  These are simply guidelines and Docker does not *enforce* them. However, for
    64  the benefit of the community, you *should* use namespaces for your label keys.
    65  
    66  
    67  ## Store structured data in labels
    68  
    69  Label values can contain any data type as long as it can be represented as a
    70  string. For example, consider this JSON document:
    71  
    72  
    73      {
    74          "Description": "A containerized foobar",
    75          "Usage": "docker run --rm example/foobar [args]",
    76          "License": "GPL",
    77          "Version": "0.0.1-beta",
    78          "aBoolean": true,
    79          "aNumber" : 0.01234,
    80          "aNestedArray": ["a", "b", "c"]
    81      }
    82  
    83  You can store this struct in a label by serializing it to a string first:
    84  
    85      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\"]}"
    86  
    87  While it is *possible* to store structured data in label values, Docker treats
    88  this data as a 'regular' string. This means that Docker doesn't offer ways to
    89  query (filter) based on nested properties. If your tool needs to filter on
    90  nested properties, the tool itself needs to implement this functionality.
    91  
    92  
    93  ## Add labels to images
    94  
    95  To add labels to an image, use the `LABEL` instruction in your Dockerfile:
    96  
    97  
    98      LABEL [<namespace>.]<key>=<value> ...
    99  
   100  The `LABEL` instruction adds a label to your image. A `LABEL` consists of a `<key>`
   101  and a `<value>`.
   102  Use an empty string for labels  that don't have a `<value>`,
   103  Use surrounding quotes or backslashes for labels that contain
   104  white space characters in the `<value>`:
   105  
   106      LABEL vendor=ACME\ Incorporated
   107      LABEL com.example.version.is-beta=
   108      LABEL com.example.version.is-production=""
   109      LABEL com.example.version="0.0.1-beta"
   110      LABEL com.example.release-date="2015-02-12"
   111  
   112  The `LABEL` instruction also supports setting multiple `<key>` / `<value>` pairs
   113  in a single instruction:
   114  
   115      LABEL com.example.version="0.0.1-beta" com.example.release-date="2015-02-12"
   116  
   117  Long lines can be split up by using a backslash (`\`) as continuation marker:
   118  
   119      LABEL vendor=ACME\ Incorporated \
   120            com.example.is-beta= \
   121            com.example.is-production="" \
   122            com.example.version="0.0.1-beta" \
   123            com.example.release-date="2015-02-12"
   124  
   125  Docker recommends you add multiple labels in a single `LABEL` instruction. Using
   126  individual instructions for each label can result in an inefficient image. This
   127  is because each `LABEL` instruction in a Dockerfile produces a new IMAGE layer.
   128  
   129  You can view the labels via the `docker inspect` command:
   130  
   131      $ docker inspect 4fa6e0f0c678
   132  
   133      ...
   134      "Labels": {
   135          "vendor": "ACME Incorporated",
   136          "com.example.is-beta": "",
   137          "com.example.is-production": "",
   138          "com.example.version": "0.0.1-beta",
   139          "com.example.release-date": "2015-02-12"
   140      }
   141      ...
   142  
   143      # Inspect labels on container
   144      $ docker inspect -f "{{json .Config.Labels }}" 4fa6e0f0c678
   145  
   146      {"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"}
   147  
   148      # Inspect labels on images
   149      $ docker inspect -f "{{json .ContainerConfig.Labels }}" myimage
   150  
   151  
   152  ## Query labels
   153  
   154  Besides storing metadata, you can filter images and containers by label. To list all
   155  running containers that have the `com.example.is-beta` label:
   156  
   157      # List all running containers that have a `com.example.is-beta` label
   158      $ docker ps --filter "label=com.example.is-beta"
   159  
   160  List all running containers with the label `color` that have a value `blue`:
   161  
   162      $ docker ps --filter "label=color=blue"
   163  
   164  List all images with the label `vendor` that have the value `ACME`:
   165  
   166      $ docker images --filter "label=vendor=ACME"
   167  
   168  
   169  ## Container labels
   170  
   171      docker run \
   172         -d \
   173         --label com.example.group="webservers" \
   174         --label com.example.environment="production" \
   175         busybox \
   176         top
   177  
   178  Please refer to the [Query labels](#query-labels) section above for information
   179  on how to query labels set on a container.
   180  
   181  
   182  ## Daemon labels
   183  
   184      docker daemon \
   185        --dns 8.8.8.8 \
   186        --dns 8.8.4.4 \
   187        -H unix:///var/run/docker.sock \
   188        --label com.example.environment="production" \
   189        --label com.example.storage="ssd"
   190  
   191  These labels appear as part of the `docker info` output for the daemon:
   192  
   193      $ docker -D info
   194      Containers: 12
   195       Running: 5
   196       Paused: 2
   197       Stopped: 5
   198      Images: 672
   199      Server Version: 1.9.0
   200      Storage Driver: aufs
   201       Root Dir: /var/lib/docker/aufs
   202       Backing Filesystem: extfs
   203       Dirs: 697
   204       Dirperm1 Supported: true
   205      Execution Driver: native-0.2
   206      Logging Driver: json-file
   207      Kernel Version: 3.19.0-22-generic
   208      Operating System: Ubuntu 15.04
   209      CPUs: 24
   210      Total Memory: 62.86 GiB
   211      Name: docker
   212      ID: I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S
   213      Debug mode (server): true
   214       File Descriptors: 59
   215       Goroutines: 159
   216       System Time: 2015-09-23T14:04:20.699842089+08:00
   217       EventsListeners: 0
   218       Init SHA1:
   219       Init Path: /usr/bin/docker
   220       Docker Root Dir: /var/lib/docker
   221       Http Proxy: http://test:test@localhost:8080
   222       Https Proxy: https://test:test@localhost:8080
   223      WARNING: No swap limit support
   224      Username: svendowideit
   225      Registry: [https://index.docker.io/v1/]
   226      Labels:
   227       com.example.environment=production
   228       com.example.storage=ssd