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

イメージ、コンテナ、デーモンに対してラベルを通してメタデータを追加できます。ラベルには様々な使い方があります。例えば、メモの追加、イメージに対するライセンス情報の追加、ホストを識別するためです。

ラベルは <key> / <value> のペアです。Docker はラベルの値を 文字列 として保管します。複数のラベルを指定できますが、 <key> はユニークである必要があるため、重複時は上書きされます。同じ <key> を複数回指定したら、古いラベルは新しいラベルに置き換えられるため、都度値が変わります。Docker は常に指定した最新の key=value を使います。

注釈

デーモンのラベル機能は Docker 1.4.1 から追加されました。コンテナとイメージに対するラベルは、Docker 1.6.0 からです。

ラベルのキーと名前空間 ¶

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 [<名前空間>.]<key>=<value> ...

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

LABEL vendor=ACME\ Incorporated
LABEL com.example.version.is-beta=
LABEL com.example.version.is-production=""
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.is-production="" \
      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.is-production": "",
    "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.is-production":"", "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
Running: 5
Paused: 2
Stopped: 5
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

参考

Apply custom metadata: https://docs.docker.com/engine/userguide/labels-custom-metadata/

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

ラベルのキーと名前空間¶

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

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

クエリ・ラベル¶

コンテナ・ラベル¶

デーモン・ラベル¶