Docker オブジェクト・ラベル

目次

ラベル（label）とは、 Docker オブジェクトに対してメタデータを設定する仕組みです。Docker オブジェクトとは以下の通りです：

  • イメージ
  • コンテナ
  • ローカル・デーモン
  • ボリューム
  • ネットワーク
  • Swarm ノード
  • Swarm サービス

ラベルはさまざまな目的で利用することができます。 イメージを構成したり、ライセンス情報を記録したり、コンテナー、ボリューム、ネットワーク間の関係性を書きとめたりといったものです。 業務やアプリケーションにとって意義のあることなら、どのようなものでも含めて構いません。

ラベルのキーとバリュー

ラベルはキーバリュー・ペアの形式であり、文字列として保存されます。 オブジェクトに対しては複数のラベルを指定することができますが、各キーバリュー・ペアは 1 つのオブジェクト内で一意である必要があります。 1 つのキーに対して複数の値が設定されていた場合、古い値は最後に書き込まれた値により上書きされます。

推奨されるキーの書式

ラベルにおけるキーは、キーバリュー・ペアの左側を指します。 キーに含めることができる文字は、英数字、ピリオド（.）、ハイフン（-）です。 Docker ユーザが利用するイメージは、たいていは他の組織が作り出したものであるため、ここに示すガイドラインに従っていれば、オブジェクト間でのラベル定義を不用意に重複させるようなことがなくなります。 自動化の仕組みの中でラベルを利用する場合は、特にこのことが重要になります。

  • サードパーティ製ツールの開発者は、各ラベルのプリフィックスとして、自身が所有するドメインの逆 DNS 記法を用いるようにします。 たとえば com.example.some-label といったものです。
  • ドメイン所有者の許可なく、ラベルのキーにそのドメイン名を使ってはいけません。
  • 以下の名前空間 com.docker.*, io.docker.*, org.dockerproject.* は、Docker が内部利用のために予約しています。
  • ラベルのキーの始まりと終わりの 1 文字は英小文字とします。 そして文字列全体は、英小文字と数字、ピリオド（.）、ハイフン（-）を用いるようにします。 そしてピリオドとハイフンは連続して用いないようにします。
  • ピリオド（.）は名前空間の「項目」を区切るものです。 ラベルのキーに名前空間が指定されていないものは、CLI が用いるものとしています。 ユーザにとって CLI 実行の際、Docker オブジェクトに対して入力しやすい短いラベル文字列を指定できるようにするためです。

上のようなガイドラインは現時点において強制されるものではありません。 特定の用途において、さらに追加のガイドラインが適用されるかもしれません。

バリューに関するガイドライン

ラベルのバリューには、文字列として表現できるものであれば、どんな型のデータでも含めることができます。 たとえば JSON, XML, CSV, YAML があり、これ以外にもまだあります。 唯一必要になることは、そのデータ型の構造に従った形で、文字列としてシリアライズされたものであることです。 たとえば JSON データを文字列にシリアライズするには、JavaScript メソッドでは JSON.stringify() を利用するかもしれません。

Docker ではそのバリューをデシリアライズしないため、ラベルを用いた検索やフィルタリングをする際には、ネスト構造になっている JSON や XML ドキュメントを取り扱うことはできません。 これを実現するためにはサードパーティ製のツール類に、そういった機能を組み入れる必要があります。

オブジェクトにおけるラベルの管理

ラベルがサポートされている各オブジェクトには、ラベルの追加や管理を行う機能が備わっていて、そのオブジェクトに関連づいたラベルとして取り扱うことができます。 以下に示すリンクは、Docker デプロイにおいて利用するラベルを学ぶ上で役立つものです。

イメージ、コンテナ、ローカル・デーモン、ボリューム、ネットワークといったオブジェクトにおいては、そのオブジェクトが存在する間、ラベルは静的で不変なものです。 ラベルを変更するためにはオブジェクトを再生成する必要があります。 Swarm ノードと Swarm サービスにおけるラベルは動的に変更することができます。

参考

Docker object labels
https://docs.docker.com/config/labels-custom-metadata/