github.com/vieux/docker@v0.6.3-0.20161004191708-e097c2a938c7/docs/userguide/labels-custom-metadata.md (about)

     1  <!--[metadata]>
     2  +++
     3  title = "Managing Docker object labels"
     4  description = "Description of labels, which are used to manage metadata on Docker objects."
     5  keywords = ["Usage, user guide, labels, metadata, docker, documentation, examples, annotating"]
     6  [menu.main]
     7  parent = "engine_guide"
     8  weight=100
     9  +++
    10  <![end-metadata]-->
    11  
    12  # About labels
    13  
    14  Labels are a mechanism for applying metadata to Docker objects, including:
    15  
    16  - Images
    17  - Containers
    18  - Local daemons
    19  - Volumes
    20  - Networks
    21  - Swarm nodes
    22  - Swarm services
    23  
    24  You can use labels to organize your images, record licensing information, annotate
    25  relationships between containers, volumes, and networks, or in any way that makes
    26  sense for your business or application.
    27  
    28  # Label keys and values
    29  
    30  A label is a key-value pair, stored as a string. You can specify multiple labels
    31  for an object, but each key-value pair must be unique within an object. If the
    32  same key is given multiple values, the most-recently-written value overwrites
    33  all previous values.
    34  
    35  ## Key format recommendations
    36  
    37  A label _key_ is the left-hand side of the key-value pair. Keys are alphanumeric
    38  strings which may contain periods (`.`) and hyphens (`-`). Most Docker users use
    39  images created by other organizations, and the following guidelines help to
    40  prevent inadvertent duplication of labels across objects, especially if you plan
    41  to use labels as a mechanism for automation.
    42  
    43  - Authors of third-party tools should prefix each label key with the
    44    reverse DNS notation of a domain they own, such as `com.example.some-label`.
    45  
    46  - Do not use a domain in your label key without the domain owner's permission.
    47  
    48  - The `com.docker.*`, `io.docker.*` and `org.dockerproject.*` namespaces are
    49    reserved by Docker for internal use.
    50  
    51  - Label keys should begin and end with a lower-case letter and should only
    52    contain lower-case alphanumeric characters, the period character (`.`), and
    53    the hyphen character (`-`). Consecutive periods or hyphens are not allowed.
    54  
    55  - The period character (`.`) separates namespace "fields". Label keys without
    56    namespaces are reserved for CLI use, allowing users of the CLI to interactively
    57    label Docker objects using shorter typing-friendly strings.
    58  
    59  These guidelines are not currently enforced and additional guidelines may apply
    60  to specific use cases.
    61  
    62  ## Value guidelines
    63  
    64  Label values can contain any data type that can be represented as a string,
    65  including (but not limited to) JSON, XML, CSV, or YAML. The only requirement is
    66  that the value be serialized to a string first, using a mechanism specific to
    67  the type of structure. For instance, to serialize JSON into a string, you might
    68  use the `JSON.stringify()` JavaScript method.
    69  
    70  Since Docker does not deserialize the value, you cannot treat a JSON or XML
    71  document as a nested structure when querying or filtering by label value unless
    72  you build this functionality into third-party tooling.
    73  
    74  # Managing labels on objects
    75  
    76  Each type of object with support for labels has mechanisms for adding and
    77  managing them and using them as they relate to that type of object. These links
    78  provide a good place to start learning about how you can use labels in your
    79  Docker deployments.
    80  
    81  Labels on images, containers, local daemons, volumes, and networks are static for
    82  the lifetime of the object. To change these labels you must recreate the object.
    83  Labels on swarm nodes and services can be updated dynamically.
    84  
    85  
    86  - Images and containers
    87    - [Adding labels to images](../reference/builder.md#label)
    88    - [Overriding a container's labels at runtime](../reference/commandline/run.md#set-metadata-on-container-l-label-label-file)
    89    - [Inspecting labels on images or containers](../reference/commandline/inspect.md)
    90    - [Filtering images by label](../reference/commandline/inspect.md#filtering)
    91    - [Filtering containers by label](../reference/commandline/ps.md#filtering)
    92  
    93  - Local Docker daemons
    94    - [Adding labels to a Docker daemon at runtime](../reference/commandline/dockerd.md)
    95    - [Inspecting a Docker daemon's labels](../reference/commandline/info.md)
    96  
    97  - Volumes
    98    - [Adding labels to volumes](../reference/commandline/volume_create.md)
    99    - [Inspecting a volume's labels](../reference/commandline/volume_inspect.md)
   100    - [Filtering volumes by label](../reference/commandline/volume_ls.md#filtering)
   101  
   102  - Networks
   103    - [Adding labels to a network](../reference/commandline/network_create.md)
   104    - [Inspecting a network's labels](../reference/commandline/network_inspect.md)
   105    - [Filtering networks by label](../reference/commandline/network_ls.md#filtering)
   106  
   107  - Swarm nodes
   108    - [Adding or updating a swarm node's labels](../reference/commandline/node_update.md#add-label-metadata-to-a-node)
   109    - [Inspecting a swarm node's labels](../reference/commandline/node_inspect.md)
   110    - [Filtering swarm nodes by label](../reference/commandline/node_ls.md#filtering)
   111  
   112  - Swarm services
   113    - [Adding labels when creating a swarm service](../reference/commandline/service_create.md#set-metadata-on-a-service-l-label)
   114    - [Updating a swarm service's labels](../reference/commandline/service_update.md)
   115    - [Inspecting a swarm service's labels](../reference/commandline/service_inspect.md)
   116    - [Filtering swarm services by label](../reference/commandline/service_ls.md#filtering)