ボリューム・プラグインの記述

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 のようなプラグインが利用できるようになります。 これにより 1 つのホストから、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:

    {
        "Mountpoin": "/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": ""
    }
    

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

/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"
  }
}

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