カスタム・メタデータ追加¶

ラベル・キー（名前空間）¶

Docker は key の使用にあたり、厳密な制約を設けていません。しかしながら、単純な key であれば重複の可能性があります。例えば、Dockerfile の中で「architecture」ラベルを使って CPU アーキテクチャ毎にイメージを分類する場合です。

LABEL architecture="amd64"
LABEL architecture="ARMv7"

他のユーザも、同じラベルを構築時の「architecture」（構築担当者）としてラベル付けするかもしれません。

LABEL architecture="Art Nouveau"

このような名前の衝突を避けるために、Docker が推奨するのはラベルの key を使うにあたり、逆ドメイン表記による名前空間を使う方法です。

• 全ての（サードパーティー製）ツールは、キーの頭に作者が管理するドメインの逆 DNS 表記を付けるべきです。例： com.example.some-label

• 名前空間 com.docker.* と io.docker.* と org.dockerproject.* は、Docker の内部利用のために予約されています。

• キーはアルファベットの小文字、ドット、ダッシュのみに統一されるべきです（例： [a-z0-9-.] ）。

• キーは連続したドットやダッシュを含みません。

• ネームスペース（ドット）が ない キーは CLI で使うために予約されています。これにより、エンドユーザはコマンドライン上で各々のコンテナやイメージに対してメタデータを追加するとき、面倒な名前空間を指定する必要がありません。

これらは簡単なガイドラインであり、Docker は 強制しません 。しかしながら、コミュニティの利益を考えるならば、自分のラベルのキーで名前空間を使う べき でしょう。

構造化されたデータをラベルに保存¶

ラベルの値は文字列に代表されるような、あらゆる種類のデータを含められミズ得。例えば、次のような JSON ドキュメントを考えます。

{
    "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"]
}

この構造を保管するには、文字列を１行に並べてラベルにできます。

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\"]}"

ラベルの値に構造化データを保管できるかもしれませんが、Docker はこのデータを「普通の」文字列として扱います。これが意味するのは、Docker は深く掘り下げた（ネストする）問い合わせ（フィルタ）手法を提供しません。ツールが何らかの設定項目をフィルタする必要があれば、ツール自身で処理する機能の実装が必要です。

ラベルをイメージに追加¶

イメージにラベルを追加するには、Dockerfile で LABEL 命令を使います。

LABEL [<namespace>.]<key>[=<value>] ...

LABEL 命令はイメージにラベルを追加し、オプションで値も追加します。 <値> に空白文字列を踏む場合、ラベルをクォートで囲むかバックスラッシュを使います。

LABEL vendor=ACME\ Incorporated
LABEL com.example.version.is-beta
LABEL com.example.version="0.0.1-beta"
LABEL com.example.release-date="2015-02-12"

また、LABEL 命令は１行で複数の <key> / <value> ペアの設定をサポートしています。

LABEL com.example.version="0.0.1-beta" com.example.release-date="2015-02-12"

長い行は、バックスラッシュ（）を継続マーカーとして使い、分割できます。

LABEL vendor=ACME\ Incorporated \
      com.example.is-beta \
      com.example.version="0.0.1-beta" \
      com.example.release-date="2015-02-12"

Docker が推奨するのは、複数のラベルを１つの LABEL 命令にする方法です。ラベル毎に命令を使うと、非効率なイメージになってしまいます。これは Dockerfile が LABEL 命令ごとに新しいイメージ・レイヤを作るためです。

ラベルの情報は docker inspect コマンドでも確認できます。

$ docker inspect 4fa6e0f0c678

...
"Labels": {
    "vendor": "ACME Incorporated",
    "com.example.is-beta": "",
    "com.example.version": "0.0.1-beta",
    "com.example.release-date": "2015-02-12"
}
...

# Inspect labels on container
$ docker inspect -f "{{json .Config.Labels }}" 4fa6e0f0c678

{"Vendor":"ACME Incorporated","com.example.is-beta":"","com.example.version":"0.0.1-beta","com.example.release-date":"2015-02-12"}

# Inspect labels on images
$ docker inspect -f "{{json .ContainerConfig.Labels }}" myimage

クエリ・ラベル¶

メタデータの保管とは別に、ラベルによってイメージとコンテナをフィルタ出来ます。 com.example.is-beta ラベルを持っている実行中のコンテナを全て表示するには、次のようにします。

# List all running containers that have a `com.example.is-beta` label
$ docker ps --filter "label=com.example.is-beta"

ラベル color が blue の全コンテナを表示します。

$ docker ps --filter "label=color=blue"

ラベル vendor が ACME の全イメージを表示します。

$ docker images --filter "label=vendor=ACME"

コンテナ・ラベル¶

docker run \
   -d \
   --label com.example.group="webservers" \
   --label com.example.environment="production" \
   busybox \
   top

コンテナにクエリ・ラベルをセットするには、先ほどの クエリ・ラベル セクションをご覧ください。

デーモン・ラベル¶

docker daemon \
  --dns 8.8.8.8 \
  --dns 8.8.4.4 \
  -H unix:///var/run/docker.sock \
  --label com.example.environment="production" \
  --label com.example.storage="ssd"

これらのラベルは docker info によるデーモンの出力で表示されます。

$ docker -D info Containers: 12 Images: 672 Server Version: 1.9.0 Storage Driver: aufs

Root Dir: /var/lib/docker/aufs Backing Filesystem: extfs Dirs: 697 Dirperm1 Supported: true

Execution Driver: native-0.2 Logging Driver: json-file Kernel Version: 3.19.0-22-generic Operating System: Ubuntu 15.04 CPUs: 24 Total Memory: 62.86 GiB Name: docker ID: I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S Debug mode (server): true

File Descriptors: 59 Goroutines: 159 System Time: 2015-09-23T14:04:20.699842089+08:00 EventsListeners: 0 Init SHA1: Init Path: /usr/bin/docker Docker Root Dir: /var/lib/docker Http Proxy: http://test:test@localhost:8080 Https Proxy: https://test:test@localhost:8080

WARNING: No swap limit support Username: svendowideit Registry: [https://index.docker.io/v1/] Labels:

com.example.environment=production com.example.storage=ssd