読む時間の目安: 5 分

Docker ボリュームプラグイン

Docker Engine ボリュームプラグインは、Amazon EBS のような外部ストレージシステムと統合した Engine デプロイメントを可能にするものです。 そして単独の Docker ホスト上では維持できない、データボリュームの長期保存を可能にします。 詳細は プラグインのドキュメント を参照してください。

変更履歴

1.13.0

  • プラグインアーキテクチャー v2 を部分的に用いている場合、プラグインにより返されるパスで構成される mountpoints は、プラグイン設定内の PropagatedMount によって指定されるディレクトリ配下にマウントされるべき。 (#26398)

1.12.0

  • VolumeDriver.Get レスポンスに Status フィールドを追加。 (#21006)
  • VolumeDriver.Capabilities の追加。ボリュームドライバーのケーパビリティ（capability）を取得する。 (#22077)

1.10.0

  • VolumeDriver.Get の追加。 ボリュームの詳細情報を取得する。 (#16534)
  • VolumeDriver.List の追加。 ドライバーが所有する全ボリューム一覧を取得する。 (#16534)

1.8.0

  • ボリュームドライバープラグインに対する初めてのサポート。 (#14659)

コマンドラインによる変更

コンテナーからボリュームへアクセスするためには、docker container run コマンドの --volume フラグや --volume-driver フラグを用います。 --volume （または -v）フラグは、ボリューム名とホスト上のパスを指定します。 また --volume-driver フラグはドライバータイプを指定します。

$ docker volume create --driver=flocker volumename

$ docker container run -it --volume volumename:/data busybox sh

--volume

--volume （または -v）フラグは <volume_name>:<mountpoint> という書式の値をとります。 この値の 2 つの部分はコロン（:）によって区切ります。

  • ボリューム名は、人間が読み取れる文字を使って、ボリュームにつけた名前のことです。 / で始めることはできません。 これ以降では volume_name と呼び表わすことにします。
  • Mountpoint は、ホスト上のパス（v1 の場合）、またはプラグイン内のパス（v2 の場合）のいずれかであり、ボリュームが生成されている場所を示します。

volumedriver

volumename とともに volumedriver を指定すると、Flocker のようなプラグインが利用できるようになります。 これにより自ホストから、EBS 上などの外部にあるボリュームを管理できるようになります。

VolumeDriver の生成

コンテナーの生成エンドポイント（/containers/create）は、string 型の VolumeDriver を受け付け、ドライバー名を指定することができます。 指定されていない場合は、デフォルトの "local" になります。 （デフォルトドライバーはローカルボリューム向けのものです。）

ボリュームプラグインプロトコル

プラグインが有効化される際に VolumeDriver として自分自身を登録するのであれば、このプラグインは Docker デーモンに対して、ホストファイルシステム上の書き込み可能なパスを提供しなければなりません。 Docker デーモンはそのパスをコンテナーに提供して利用させます。 Docker デーモンはボリュームを利用できるようにするために、そのパスをバインドマウントしてコンテナーに提供しています。

メモ: ボリュームプラグインは、/var/lib/docker/ ディレクトリや /var/lib/docker/volumes にデータ書き込みを行ってはいけません。 /var/lib/docker/ ディレクトリは Docker により予約されています。

/VolumeDriver.Create

リクエスト

{
    "Name": "volume_name",
    "Opts": {}
}

プラグインに対して、指定するボリューム名によりユーザーがボリュームを生成したいということを伝えます。 プラグインはこのとき、ファイルシステム上のボリュームを明らかにすることは、（Mount が呼び出されるまでは）まだ必要ではありません。 Opts は、ユーザーリクエストを通じて受け渡されるドライバー固有オプションのマッピングです。

レスポンス

{
    "Err": ""
}

エラーが発生した場合は、文字列によるエラーを返します。

/VolumeDriver.Remove

リクエスト

{
    "Name": "volume_name"
}

指定されたボリュームをディスク上から削除します。 このリクエストは docker rm -v により、関連づいたコンテナーからボリュームを削除する際に実行されます。

レスポンス

{
    "Err": ""
}

エラーが発生した場合は、文字列によるエラーを返します。

/VolumeDriver.Mount

リクエスト

{
    "Name": "volume_name",
    "ID": "b87d7442095999a92b65b3d9691e697b61713829cc0ffd1bb72e4ccd51aa4d6c"
}

Docker は、ユーザーが指定するボリューム名によるボリュームを提供するものとして、このプラグインを必要とします。 Mount はコンテナーが起動するたびに 1 回だけ呼び出されます。 volume_name が重複して要求された場合、プラグインは各マウント要求を記録しておく必要があります。 そしてマウントが要求されたときにマウント処理を行い、これに対応するアンマウントの要求のときにマウント解除を行うことになります。

ID は、マウントを要求する呼び出し側の固有 ID です。

レスポンス

  • v1

    {
    "Mountpoint": "/path/to/directory/on/host",
    "Err": ""
}

  • v2

    {
    "Mountpoint": "/path/under/PropagatedMount",
    "Err": ""
}

Mountpoint は、ホスト上のパス（v1 の場合）、またはプラグイン内のパス（v2 の場合）のいずれかであり、ボリュームが生成されている場所を示します。

Err は空か、あるいはエラー文字列を含みます。

/VolumeDriver.Path

リクエスト

{
    "Name": "volume_name"
}

指定された volume_name のボリュームに対してパスを要求します。

レスポンス

  • v1

    {
    "Mountpoint": "/path/to/directory/on/host",
    "Err": ""
}

  • v2

    {
    "Mountpoint": "/path/under/PropagatedMount",
    "Err": ""
}

ホスト上のパス（v1 の場合）、またはプラグイン内のパス（v2 の場合）のいずれか、ボリュームが生成されている場所を返します。 エラーが発生した場合は、文字列によるエラーを返します。

Mountpoint は常に必要なものではありません。 ただしプラグインが利用できない状態になったときに、もう一度検索のために利用できます。

/VolumeDriver.Unmount

リクエスト

{
    "Name": "volume_name",
    "ID": "b87d7442095999a92b65b3d9691e697b61713829cc0ffd1bb72e4ccd51aa4d6c"
}

Docker は名前つきボリュームを利用していません。 Unmount はコンテナーが停止するたびに 1 回だけ呼び出されます。 プラグインは、この時点でボリュームを削除しておくのが安全かもしれません。

ID は、アンマウントを要求する呼び出し側の固有 ID です。

レスポンス

{
    "Err": ""
}

エラーが発生した場合は、文字列によるエラーを返します。

/VolumeDriver.Get

リクエスト

{
    "Name": "volume_name"
}

volume_name に関する情報を取得します。

レスポンス

  • v1

    {
  "Volume": {
    "Name": "volume_name",
    "Mountpoint": "/path/to/directory/on/host",
    "Status": {}
  },
  "Err": ""
}

  • v2

    {
  "Volume": {
    "Name": "volume_name",
    "Mountpoint": "/path/under/PropagatedMount",
    "Status": {}
  },
  "Err": ""
}

エラーが発生した場合は、文字列によるエラーを返します。 Mountpoint と Status は常に必要なものではありません。

/VolumeDriver.List

リクエスト

{}

プラグインに登録されているボリュームの一覧を取得します。

レスポンス

  • v1

    {
  "Volumes": [
    {
      "Name": "volume_name",
      "Mountpoint": "/path/to/directory/on/host"
    }
  ],
  "Err": ""
}

  • v2

    {
  "Volumes": [
    {
      "Name": "volume_name",
      "Mountpoint": "/path/under/PropagatedMount"
    }
  ],
  "Err": ""
}

エラーが発生した場合は、文字列によるエラーを返します。 Mountpoint は常に必要なものではありません。

/VolumeDriver.Capabilities

リクエスト

{}

ドライバーがサポートするケーパビリティ（capability）の一覧を取得します。

ドライバーは必ず Capalibities を実装しなければならないわけではありません。 実装されていなければデフォルトの値が用いられます。

レスポンス

{
  "Capabilities": {
    "Scope": "global"
  }
}

サポートされているスコープは global と local です。 Scope において他の値があると無視されて local が用いられます。 Scope はクラスターマネージャーに対して、さまざまな方法によりボリュームを取り扱えるようにします。 たとえば global スコープは、クラスターマネージャーに対して、ただ一度だけボリュームを生成すればよいことを伝えます。つまり Docker ホストの個々において、ボリューム生成は不要とします。 ケーパビリティの機能は将来、さらに充足されるかもしれません。

Examples, Usage, volume, docker, data, volumes, plugin, api