github.com/xuyutom/docker@v1.6.0/docs/sources/userguide/labels-custom-metadata.md (about) 1 page_title: Apply custom metadata 2 page_description: Learn how to work with custom metadata in Docker, using labels. 3 page_keywords: Usage, user guide, labels, metadata, docker, documentation, examples, annotating 4 5 # Apply custom metadata 6 7 You can apply metadata to your images, containers, or daemons via 8 labels. Metadata can serve a wide range of uses. Use labels to add notes or 9 licensing information to an image or to identify a host. 10 11 A label is a `<key>` / `<value>` pair. Docker stores the label values as 12 *strings*. You can specify multiple labels but each `<key>` / `<value>` must be 13 unique to avoid overwriting. If you specify the same `key` several times but with 14 different values, newer labels overwrite previous labels. Docker uses 15 the last `key=value` you supply. 16 17 >**Note:** Support for daemon-labels was added in Docker 1.4.1. Labels on 18 >containers and images are new in Docker 1.6.0 19 20 ## Label keys (namespaces) 21 22 Docker puts no hard restrictions on the label `key` you. However, labels with 23 simple keys can conflict. For example, you can categorize your images by using a 24 chip "architecture" label: 25 26 LABEL architecture="amd64" 27 28 LABEL architecture="ARMv7" 29 30 But a user can label images by building architectural style: 31 32 LABEL architecture="Art Nouveau" 33 34 To prevent naming conflicts, Docker namespaces label keys using a reverse domain 35 notation. Use the following guidelines to name your keys: 36 37 - All (third-party) tools should prefix their keys with the 38 reverse DNS notation of a domain controlled by the author. For 39 example, `com.example.some-label`. 40 41 - The `com.docker.*`, `io.docker.*` and `com.dockerproject.*` namespaces are 42 reserved for Docker's internal use. 43 44 - Keys should only consist of lower-cased alphanumeric characters, 45 dots and dashes (for example, `[a-z0-9-.]`) 46 47 - Keys should start *and* end with an alpha numeric character 48 49 - Keys may not contain consecutive dots or dashes. 50 51 - Keys *without* namespace (dots) are reserved for CLI use. This allows end- 52 users to add metadata to their containers and images without having to type 53 cumbersome namespaces on the command-line. 54 55 56 These are guidelines and Docker does not *enforce* them. Failing following these 57 guidelines can result in conflicting labels. If you're building a tool that uses 58 labels, you *should* use namespaces for your label keys. 59 60 61 ## Store structured data in labels 62 63 Label values can contain any data type that can be stored as a string. For 64 example, consider this JSON: 65 66 67 { 68 "Description": "A containerized foobar", 69 "Usage": "docker run --rm example/foobar [args]", 70 "License": "GPL", 71 "Version": "0.0.1-beta", 72 "aBoolean": true, 73 "aNumber" : 0.01234, 74 "aNestedArray": ["a", "b", "c"] 75 } 76 77 You can store this struct in a label by serializing it to a string first: 78 79 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\"]}" 80 81 While it is *possible* to store structured data in label values, Docker treats 82 this data as a 'regular' string. This means that Docker doesn't offer ways to 83 query (filter) based on nested properties. If your tool needs to filter on 84 nested properties, the tool itself should implement this. 85 86 87 ## Add labels to images; the `LABEL` instruction 88 89 Adding labels to an image: 90 91 92 LABEL [<namespace>.]<key>[=<value>] ... 93 94 The `LABEL` instruction adds a label to your image, optionally setting its value. 95 Use surrounding quotes or backslashes for labels that contain 96 white space character: 97 98 LABEL vendor=ACME\ Incorporated 99 LABEL com.example.version.is-beta 100 LABEL com.example.version="0.0.1-beta" 101 LABEL com.example.release-date="2015-02-12" 102 103 The `LABEL` instruction supports setting multiple labels in a single instruction 104 using this notation: 105 106 LABEL com.example.version="0.0.1-beta" com.example.release-date="2015-02-12" 107 108 Wrapping is allowed by using a backslash (`\`) as continuation marker: 109 110 LABEL vendor=ACME\ Incorporated \ 111 com.example.is-beta \ 112 com.example.version="0.0.1-beta" \ 113 com.example.release-date="2015-02-12" 114 115 Docker recommends you add multiple labels in a single `LABEL` instruction. Using 116 individual instructions for each label can result in an inefficient image. This 117 is because each `LABEL` instruction in a Dockerfile produces a new IMAGE layer. 118 119 You can view the labels via the `docker inspect` command: 120 121 $ docker inspect 4fa6e0f0c678 122 123 ... 124 "Labels": { 125 "vendor": "ACME Incorporated", 126 "com.example.is-beta": "", 127 "com.example.version": "0.0.1-beta", 128 "com.example.release-date": "2015-02-12" 129 } 130 ... 131 132 $ docker inspect -f "{{json .Labels }}" 4fa6e0f0c678 133 134 {"Vendor":"ACME Incorporated","com.example.is-beta":"","com.example.version":"0.0.1-beta","com.example.release-date":"2015-02-12"} 135 136 137 ## Query labels 138 139 Besides storing metadata, you can filter images and containers by label. To list all 140 running containers that the `com.example.is-beta` label: 141 142 # List all running containers that have a `com.example.is-beta` label 143 $ docker ps --filter "label=com.example.is-beta" 144 145 List all running containers with a `color` label of `blue`: 146 147 $ docker ps --filter "label=color=blue" 148 149 List all images with `vendor` `ACME`: 150 151 $ docker images --filter "label=vendor=ACME" 152 153 154 ## Daemon labels 155 156 157 docker -d \ 158 --dns 8.8.8.8 \ 159 --dns 8.8.4.4 \ 160 -H unix:///var/run/docker.sock \ 161 --label com.example.environment="production" \ 162 --label com.example.storage="ssd" 163 164 These labels appear as part of the `docker info` output for the daemon: 165 166 docker -D info 167 Containers: 12 168 Images: 672 169 Storage Driver: aufs 170 Root Dir: /var/lib/docker/aufs 171 Backing Filesystem: extfs 172 Dirs: 697 173 Execution Driver: native-0.2 174 Kernel Version: 3.13.0-32-generic 175 Operating System: Ubuntu 14.04.1 LTS 176 CPUs: 1 177 Total Memory: 994.1 MiB 178 Name: docker.example.com 179 ID: RC3P:JTCT:32YS:XYSB:YUBG:VFED:AAJZ:W3YW:76XO:D7NN:TEVU:UCRW 180 Debug mode (server): false 181 Debug mode (client): true 182 Fds: 11 183 Goroutines: 14 184 EventsListeners: 0 185 Init Path: /usr/bin/docker 186 Docker Root Dir: /var/lib/docker 187 WARNING: No swap limit support 188 Labels: 189 com.example.environment=production 190 com.example.storage=ssd