github.com/jogo/docker@v1.7.0-rc1/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 # Inspect labels on container 133 $ docker inspect -f "{{json .Config.Labels }}" 4fa6e0f0c678 134 135 {"Vendor":"ACME Incorporated","com.example.is-beta":"","com.example.version":"0.0.1-beta","com.example.release-date":"2015-02-12"} 136 137 # Inspect labels on images 138 $ docker inspect -f "{{json .ContainerConfig.Labels }}" myimage 139 140 141 ## Query labels 142 143 Besides storing metadata, you can filter images and containers by label. To list all 144 running containers that the `com.example.is-beta` label: 145 146 # List all running containers that have a `com.example.is-beta` label 147 $ docker ps --filter "label=com.example.is-beta" 148 149 List all running containers with a `color` label of `blue`: 150 151 $ docker ps --filter "label=color=blue" 152 153 List all images with `vendor` `ACME`: 154 155 $ docker images --filter "label=vendor=ACME" 156 157 158 ## Daemon labels 159 160 161 docker -d \ 162 --dns 8.8.8.8 \ 163 --dns 8.8.4.4 \ 164 -H unix:///var/run/docker.sock \ 165 --label com.example.environment="production" \ 166 --label com.example.storage="ssd" 167 168 These labels appear as part of the `docker info` output for the daemon: 169 170 docker -D info 171 Containers: 12 172 Images: 672 173 Storage Driver: aufs 174 Root Dir: /var/lib/docker/aufs 175 Backing Filesystem: extfs 176 Dirs: 697 177 Execution Driver: native-0.2 178 Logging Driver: json-file 179 Kernel Version: 3.13.0-32-generic 180 Operating System: Ubuntu 14.04.1 LTS 181 CPUs: 1 182 Total Memory: 994.1 MiB 183 Name: docker.example.com 184 ID: RC3P:JTCT:32YS:XYSB:YUBG:VFED:AAJZ:W3YW:76XO:D7NN:TEVU:UCRW 185 Debug mode (server): false 186 Debug mode (client): true 187 File Descriptors: 11 188 Goroutines: 14 189 EventsListeners: 0 190 Init Path: /usr/bin/docker 191 Docker Root Dir: /var/lib/docker 192 WARNING: No swap limit support 193 Labels: 194 com.example.environment=production 195 com.example.storage=ssd