読む時間の目安: 5 分

Docker Engine が管理するプラグインシステム

Docker Engine のプラグインシステムは Docker Engine を使って、プラグインのインストール、起動、停止、削除を行うものです。

Docker Engine 1.12 またはそれ以前において利用可能な古いプラグインシステムに関しては 以前の Docker Engine プラグインの理解 を参照してください。

メモ: Docker Engine 管理のプラグインシステムは、現在 Windows デーモン上ではサポートされません。

プラグインのインストールと利用

プラグインは Docker イメージとして配布されます。 したがって Docker Hub やプライベートリポジトリからホスティングすることができます。

プラグインのインストールにはdocker plugin installコマンドを用います。 このコマンドは Docker Hub やプライベートリポジトリからプラグインをプルして、必要に応じて権限や機能の追加を求めた上で、そのプラグインを有効にします。

インストールされているプラグインを確認するにはdocker plugin lsコマンドを用います。 起動に成功しているプラグインは、有効なプラグインとして一覧に出力されます。

プラグインをインストールしたら、たとえばボリューム生成などのように、それまでとは違った Docker 操作を行うことができます。

以下の例ではsshfsプラグインをインストールします。 これが有効化されていることを確認した上で、ボリューム生成に利用します。

メモ: この例は説明目的で示しているにすぎません。 ボリュームが生成された後にボリューム詳細を確認すると、リモートホストの SSH パスワードが表示されてしまいます。 したがってこの例による作業を終えたら、できるだけ早くにボリュームを削除するようにしてください。

  1. sshfsプラグインをインストールします。

    $ docker plugin install vieux/sshfs

Plugin "vieux/sshfs" is requesting the following privileges:
- network: [host]
- capabilities: [CAP_SYS_ADMIN]
Do you grant the above permissions? [y/N] y

vieux/sshfs

    このプラグインは 2 つの権限を要求しています。

    • hostネットワークへのアクセスを必要とします。
    • ケーパビリティーCAP_SYS_ADMINを必要とします。 これによってプラグインからmountコマンドが実行できるようになります。

  2. docker plugin lsの出力から、このプラグインが有効化されたことを確認します。

    $ docker plugin ls

ID                    NAME                  TAG                 DESCRIPTION                   ENABLED
69553ca1d789          vieux/sshfs           latest              the `sshfs` plugin            true

  3. プラグインを利用してボリュームを生成します。 この例では、ホスト1.2.3.4上の/remoteディレクトリを、sshvolumeという名のボリュームとしてマウントします。

    このボリュームはこうしてコンテナーにマウントされます。

    $ docker volume create \
  -d vieux/sshfs \
  --name sshvolume \
  -o sshcmd=user@1.2.3.4:/remote \
  -o password=$(cat file_containing_password_for_remote_host)

sshvolume

  4. ボリュームの生成が成功したことを確認します。

    $ docker volume ls

DRIVER              NAME
vieux/sshfs         sshvolume

  5. ボリュームsshvolumeを利用するコンテナーを起動します。

    $ docker run --rm -v sshvolume:/data busybox ls /data

＜マシン 1.2.3.4 の /remote の内容一覧＞

  6. ボリュームsshvolumeを削除します。

    docker volume rm sshvolume

sshvolume

プラグインを無効にする場合はdocker plugin disableコマンドを用います。 また完全に削除するにはdocker plugin removeコマンドを用います。 これ以外に利用可能なコマンドやオプションについては コマンドラインリファレンス を参照してください。

プラグインの開発

rootfs ディレクトリ

rootfsディレクトリはそのプラグインのルートファイルシステムを表わします。 以下の例においては Dockerfile から生成しています。

メモ: /run/docker/pluginsディレクトリはプラグインのファイルシステム上に存在している必要があります。 これは Docker がプラグインと通信を行うために用いられます。

$ git clone https://github.com/vieux/docker-volume-sshfs
$ cd docker-volume-sshfs
$ docker build -t rootfsimage .
$ id=$(docker create rootfsimage true) # id was cd851ce43a403 when the image was created
$ sudo mkdir -p myplugin/rootfs
$ sudo docker export "$id" | sudo tar -x -C myplugin/rootfs
$ docker rm -vf "$id"
$ docker rmi rootfsimage

config.json ファイル

config.jsonファイルはプラグインを記述するものです。 プラグイン設定リファレンス を参照してください。

以下のようなconfig.jsonファイルがあったとします。

{
	"description": "sshFS plugin for Docker",
	"documentation": "https://docs.docker.com/engine/extend/plugins/",
	"entrypoint": ["/docker-volume-sshfs"],
	"network": {
		   "type": "host"
		   },
	"interface" : {
		   "types": ["docker.volumedriver/1.0"],
		   "socket": "sshfs.sock"
	},
	"linux": {
		"capabilities": ["CAP_SYS_ADMIN"]
	}
}

このプラグインは 1 つのボリュームドライバーです。 これはhostネットワークとケーパビリティーCAP_SYS_ADMINを必要とします。 エントリーポイント/docker-volume-sshfsを持ち、ソケットとして/run/docker/plugins/sshfs.sockを用いて Docker Engine とやりとりを行います。 このプラグインに対しての実行パラメーターはありません。

プラグインの生成

新たなプラグインはdocker plugin create <プラグイン名> ./path/to/plugin/dataを実行することで生成されます。 ここで/path/to/plugin/dataは、プラグインの設定ファイルconfig.jsonが置かれていて、サブディレクトリrootfsがこのプラグインのルートファイルシステムとなるようなディレクトリのことです。

プラグインの生成後はdocker plugin lsの実行によってそのプラグインの<プラグイン名>が表示されます。 プラグインはdocker plugin push <プラグイン名>の実行により、リモートリポジトリにプッシュすることができます。

プラグインのデバッグ

プラグインの標準出力は dockerd のログにリダイレクトされます。 ログエントリーにはplugin=<ID>というサフィックスがつきます。 以下に示すコマンド利用例は、プラグイン ID f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62 に対するものであり、これに対応する Docker デーモンのログエントリーを示しています。

$ docker plugin install tiborvass/sample-volume-plugin

INFO[0036] Starting...       Found 0 volumes on startup  plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62

$ docker volume create -d tiborvass/sample-volume-plugin samplevol

INFO[0193] Create Called...  Ensuring directory /data/samplevol exists on host...  plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62
INFO[0193] open /var/lib/docker/plugin-data/local-persist.json: no such file or directory  plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62
INFO[0193]                   Created volume samplevol with mountpoint /data/samplevol  plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62
INFO[0193] Path Called...    Returned path /data/samplevol  plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62

$ docker run -v samplevol:/tmp busybox sh

INFO[0421] Get Called...     Found samplevol                plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62
INFO[0421] Mount Called...   Mounted samplevol              plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62
INFO[0421] Path Called...    Returned path /data/samplevol  plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62
INFO[0421] Unmount Called... Unmounted samplevol            plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62

docker-runc によるログファイルおよびシェルの取得

docker-runcはデフォルトの Docker コンテナーランタイムであり、プラグインのデバッグに利用します。 プラグインログがファイルに対してリダイレクト出力される場合に、そのログを収集する目的で活用することができます。

$ sudo docker-runc --root /var/run/docker/plugins/runtime-root/moby-plugins list

ID                                                                 PID         STATUS      BUNDLE                                                                                                                                       CREATED                          OWNER
93f1e7dbfe11c938782c2993628c895cf28e2274072c4a346a6002446c949b25   15806       running     /run/docker/containerd/daemon/io.containerd.runtime.v1.linux/moby-plugins/93f1e7dbfe11c938782c2993628c895cf28e2274072c4a346a6002446c949b25   2018-02-08T21:40:08.621358213Z   root
9b4606d84e06b56df84fadf054a21374b247941c94ce405b0a261499d689d9c9   14992       running     /run/docker/containerd/daemon/io.containerd.runtime.v1.linux/moby-plugins/9b4606d84e06b56df84fadf054a21374b247941c94ce405b0a261499d689d9c9   2018-02-08T21:35:12.321325872Z   root
c5bb4b90941efcaccca999439ed06d6a6affdde7081bb34dc84126b57b3e793d   14984       running     /run/docker/containerd/daemon/io.containerd.runtime.v1.linux/moby-plugins/c5bb4b90941efcaccca999439ed06d6a6affdde7081bb34dc84126b57b3e793d   2018-02-08T21:35:12.321288966Z   root

$ sudo docker-runc --root /var/run/docker/plugins/runtime-root/moby-plugins exec 93f1e7dbfe11c938782c2993628c895cf28e2274072c4a346a6002446c949b25 cat /var/log/plugin.log

プラグインにビルトインのシェルがある場合、プラグインに対する exec 実行を以下のように行うことができます。

$ sudo docker-runc --root /var/run/docker/plugins/runtime-root/moby-plugins exec -t 93f1e7dbfe11c938782c2993628c895cf28e2274072c4a346a6002446c949b25 sh

curl 利用によるプラグインソケットデバッグ

プラグイン API ソケットが Docker デーモンとのやりとりに反応するかどうかの確認には curl を用います。 以下の例では Docker ホストから curl 7.47.0 を利用して、ボリュームプラグインおよびネットワークプラグインに API 呼び出しを行っています。 これによってプラグインがソケットを待ち受けていることを確認します。 プラグイン機能が適正に構築されているものであれば、こういった基本的なリクエストが動作します。 なおプラグインソケットは、ホスト上の/var/run/docker/plugins/<プラグインID>において利用可能です。

curl -H "Content-Type: application/json" -XPOST -d '{}' --unix-socket /var/run/docker/plugins/e8a37ba56fc879c991f7d7921901723c64df6b42b87e6a0b055771ecf8477a6d/plugin.sock http:/VolumeDriver.List

{"Mountpoint":"","Err":"","Volumes":[{"Name":"myvol1","Mountpoint":"/data/myvol1"},{"Name":"myvol2","Mountpoint":"/data/myvol2"}],"Volume":null}

curl -H "Content-Type: application/json" -XPOST -d '{}' --unix-socket /var/run/docker/plugins/45e00a7ce6185d6e365904c8bcf62eb724b1fe307e0d4e7ecc9f6c1eb7bcdb70/plugin.sock http:/NetworkDriver.GetCapabilities

{"Scope":"local"}

curl 7.5 またはそれ以降を利用する場合、URL の書式はhttp://hostname/APICallのようにします。 ここでhostnameはプラグインがインストールされている正確なホスト名を指定し、APICallはプラグイン API 呼び出しを指定します。

たとえばhttp://localhost/VolumeDriver.Listのようにします。

API, Usage, plugins, documentation, developer