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