docker/docker — pull request #9013 by squaremo (2014-11-06 23:08:34+00:00)
Title: Container attribute docs

This PR describes "Container attributes", that is, metadata for containers.

## Motivation

The motivation for attributes is to be able to "hang" values on a container so that clients -- e.g., plugins -- can examine them and react accordingly. For example, a weave plugin might attach a container to the weave network based on a `weaveIPs` attribute.

Attributes can be set while the container is running, and are visible to consumers of the remote API and to command-line tooling, but not in general from within the container.

## Synopsis

Command line:

```bash
# Run a container with an attribute set to a value
docker run -ti --attr='animal="Dog"' ubuntu
# Set an attribute on a container (whether it's running or not)
docker attr animal '"Fox"'
# Get an attribute value
docker inspect --format='{{ .Attributes.animal }}'
```
NB that attributes get JSON literals, hence the quoting; I'll discuss that below.

`Dockerfile`:

```
ATTR animal "Goat"
```

## Design choices

### Keys

Keys are restricted to valid go identifiers, so there is no structure to them (e.g., you can't set an attribute with a key `foo.bar`).

This is so it's easy to pull values out with `docker inspect`; although there's no structure to keys when *setting* attributes, the values may be maps and arrays, and you can reach down into them with the `format` argument.

```bash
docker attr animals '["deer", "otter", "seal"]'
docker inspect --format='{{ index .Attributes.animals 0 }}'
```

### JSON values

Values are JSON literals. This necessitates quoting, when used on the command line, which is awkward. The upside is that you can have structured values, like lists of labels or IP addresses or animals.

### Update semantics

The given semantics eschew transactions and fine-grained operations; you can inspect an attribute then set it, or you can just stomp on whatever value it has already; but there's no operation for say, adding an entry to an array-valued attribute, atomically. This is to keep things simple to implement, mainly.

### null for delete

The literal `null` is used to remove an attribute. This is consistent with what you get if you ask `docker inspect` for a field that doesn't exist -- i.e., `null` means missing.

### Events

There's an event `"update"` that gets fired whenever container attributes are changed. This is so that clients can react to changes in whatever attributes they were interested in.

It doesn't carry any additional information: clients are expected to go and look for a new value and react accordingly. Possibly the key could be included in the event, so clients don't end up spamming docker inspect.