# Amazon ECS での Docker ボリュームの使用
<a name="docker-volumes"></a>

Docker ボリュームを使用している場合は、組み込みの `local` ドライバーまたはサードパーティーのボリュームドライバーを使用できます。Docker ボリュームは Docker で管理され、ディレクトリはボリュームデータを含むコンテナインスタンスの `/var/lib/docker/volumes` に作成されます。

Docker ボリュームを使用するには、タスク定義で `dockerVolumeConfiguration` を指定します。詳細については、Docker ドキュメントの「[Volumes](https://docs.docker.com/engine/storage/volumes/)」を参照してください。

Docker ボリュームの一般的ユースケースは以下のとおりです。
+ コンテナで使用する永続データボリュームを提供する
+ 定義したデータボリュームを同じコンテナインスタンス上の異なるコンテナにある別々の場所で共有する
+ 空の非永続データボリュームを定義し、同じタスク内の複数のコンテナにマウントする
+ サードパーティー製ドライバーによって管理されるタスクに、データボリュームを提供する

## Docker ボリュームの使用に関する考慮事項
<a name="docker-volume-considerations"></a>

Docker ボリュームを使用する際は、以下の点を考慮します。
+ Docker ボリュームは、EC2 起動タイプ、または外部インスタンスを使用する場合にのみサポートされます。
+ Windows コンテナでは、`local` ドライバーの使用のみサポートされます。
+ サードパーティー製ドライバーを使用する場合は、コンテナエージェントを起動する前に、必ずドライバーをコンテナインスタンスにインストールしアクティブ化しておきます。エージェントを開始する前にサードパーティー製ドライバーがアクティブ化されていない場合は、以下のいずれかのコマンドを使用してコンテナエージェントを再起動することが可能です。
  + Amazon ECS に最適化された Amazon Linux 2 AMI の場合:

    ```
    sudo systemctl restart ecs
    ```
  + Amazon ECS に最適化された Amazon Linux AMI の場合:

    ```
    sudo stop ecs && sudo start ecs
    ```

タスク定義で Docker ボリュームを指定する方法については、「[Amazon ECS タスク定義で Docker ボリュームを指定する](specify-volume-config.md)」を参照してください。

# Amazon ECS タスク定義で Docker ボリュームを指定する
<a name="specify-volume-config"></a>

コンテナでデータボリュームを使用するには、ボリュームを指定し、タスク定義でポイント設定をマウントする必要があります。このセクションでは、コンテナのボリューム設定について説明します。Docker ボリュームを使用する`dockerVolumeConfiguration` を指定します。バインドマウントのホストボリュームを使用するタスクで、`host` とオプションの `sourcePath` を指定します。

次のタスク定義の JSON スニペットに、コンテナの `volumes` と `mountPoints` オブジェクト用の構文を示します。

```
{
    "containerDefinitions": [
        {
            "mountPoints": [
                {
                    "sourceVolume": "string",
                    "containerPath": "/path/to/mount_volume",
                    "readOnly": boolean
                }
            ]
        }
    ],
    "volumes": [
        {
            "name": "string",
            "dockerVolumeConfiguration": {
                "scope": "string",
                "autoprovision": boolean,
                "driver": "string",
                "driverOpts": {
                    "key": "value"
                },
                "labels": {
                    "key": "value"
                }
            }
        }
    ]
}
```

`name`  
タイプ: 文字列  
必須: いいえ  
ボリュームの名前。最大 255 文字の英字 (大文字と小文字の区別あり)、数字、ハイフン (`-`)、アンダースコア (`_`) を使用できます。この名前は、コンテナ定義 `mountPoints` オブジェクトの `sourceVolume` パラメータで参照されます。

`dockerVolumeConfiguration`  
タイプ: [DockerVolumeConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DockerVolumeConfiguration.html) オブジェクト  
必須: いいえ  
このパラメータは、Docker ボリュームを使用する場合に指定します。Docker ボリュームは、EC2 インスタンスでタスクを実行する場合にのみサポートされます。Windows コンテナでは、`local` ドライバーの使用のみがサポートされます。バインドマウントを使用するには、代わりに `host` を指定します。    
`scope`  
タイプ: 文字列  
有効な値: `task` \$1 `shared`  
必須: いいえ  
Docker ボリュームのスコープ。これにより、ボリュームのライフサイクルが決定されます。Docker ボリュームの範囲が `task` の場合は、タスクが開始すると自動的にプロビジョンされ、タスクが停止すると破棄されます。Docker ボリュームの範囲が `shared` の場合は、タスクの停止後も保持されます。  
`autoprovision`  
タイプ: ブール値  
デフォルト値: `false`  
必須: いいえ  
この値が `true` の場合、既に存在していない場合は Docker ボリュームが作成されます。このフィールドは、`scope` が `shared` の場合にのみ使用されます。`scope` が `task` の場合、このパラメータは省略する必要があります。  
`driver`  
タイプ: 文字列  
必須: いいえ  
使用する Docker ボリュームドライバー。この名前はタスク配置に使用されるため、ドライバー値は Docker で提供されているドライバー名と一致する必要があります。ドライバーが Docker プラグイン CLI を使用してインストールされた場合は、`docker plugin ls` を使用してコンテナインスタンスからドライバー名を取得します。ドライバーが別の方法でインストール済みである場合は、Docker プラグイン検出を使用してドライバー名を取得します。  
`driverOpts`  
タイプ: 文字列  
必須: いいえ  
パススルーする Docker ドライバー固有のオプションのマップ。このパラメータは、Docker の「Create a volume」セクションの `DriverOpts` にマッピングされます。  
`labels`  
タイプ: 文字列  
必須: いいえ  
Docker ボリュームに追加するカスタムメタデータ。

`mountPoints`  
タイプ: オブジェクト配列  
必須: いいえ  
コンテナでのデータボリュームのマウントポイント。このパラメータは creat-container Docker API の `Volumes` にマッピングされ、docker run の `--volume` オプションにマッピングされます。  
Windows コンテナは `$env:ProgramData` と同じドライブに全部のディレクトリをマウントできます。Windows コンテナは、別のドライブにディレクトリをマウントすることはできません。また、マウントポイントは複数のドライブにまたがることはできません。Amazon EBS ボリュームを Amazon ECS タスクに直接アタッチするには、マウントポイントを指定する必要があります。    
`sourceVolume`  
タイプ: 文字列  
必須: はい (`mountPoints` を使用する場合)  
マウントするボリュームの名前。  
`containerPath`  
タイプ: 文字列  
必須: はい (`mountPoints` を使用する場合)  
ボリュームをマウントするコンテナ内のパス。  
`readOnly`  
タイプ: ブール値  
必須: いいえ  
この値が `true` の場合、コンテナはボリュームへの読み取り専用アクセスを許可されます。この値が `false` の場合、コンテナはボリュームに書き込むことができます。デフォルト値は `false` です。  
Windows オペレーティングシステムを実行している EC2 インスタンスで実行されるタスクの場合、 値をデフォルト の `false` のままにします。

# Amazon ECS の Docker ボリュームの例
<a name="docker-volume-examples"></a>

次の例は、コンテナにエフェメラルストレージを提供する方法、複数のコンテナに共有ボリュームを提供する方法、およびコンテナに NFS 永続ストレージを提供する方法を示しています。

**Docker ボリュームを使用してコンテナの一時ストレージを提供する**

この例では、コンテナは空のデータボリュームを使用しており、これはタスクが完了した後に破棄されます。ユースケースの一例としては、タスクの実行中に一部のスクラッチファイルストレージにアクセスする必要のあるコンテナが考えられます。このタスクは、Docker ボリュームを使用して行うことができます。

1. タスク定義の `volumes` セクションで、`name` および `DockerVolumeConfiguration` 値を使用して、データボリュームを定義します。この例では、タスクが停止した後にボリュームが削除されるように、範囲に `task` を指定して、組み込みの `local` ドライバーを使用します。

   ```
   "volumes": [
       {
           "name": "scratch",
           "dockerVolumeConfiguration" : {
               "scope": "task",
               "driver": "local",
               "labels": {
                   "scratch": "space"
               }
           }
       }
   ]
   ```

1. `containerDefinitions` セクションで、定義したボリュームの名前を参照する `mountPoints` 値と、コンテナにボリュームをマウントするための `containerPath` 値を使用して、コンテナを定義します。

   ```
   "containerDefinitions": [
       {
           "name": "container-1",
           "mountPoints": [
               {
                 "sourceVolume": "scratch",
                 "containerPath": "/var/scratch"
               }
           ]
       }
   ]
   ```

**Docker ボリュームを使用して複数のコンテナの永続的ストレージを提供するには**

この例では、複数のコンテナで使用する共有ボリュームが必要で、また、使用するタスクの内の 1 つが停止した後も、このボリュームを維持する必要があります。組み込みの `local` ドライバーは使用中です。このためボリュームは、コンテナインスタンスのライフサイクルに紐付けられたままです。

1. タスク定義の `volumes` セクションで、`name` および `DockerVolumeConfiguration` 値を使用して、データボリュームを定義します。この例では、`shared` スコープをボリュームが維持されるように指定し、自動プロビジョニングを `true` に設定します。これは、使用するためのボリュームが作成されるようにするためです。また、組み込みの `local` ドライバーも使用します。

   ```
   "volumes": [
       {
           "name": "database",
           "dockerVolumeConfiguration" : {
               "scope": "shared",
               "autoprovision": true,
               "driver": "local",
               "labels": {
                   "database": "database_name"
               }
           }
       }
   ]
   ```

1. `containerDefinitions` セクションで、定義したボリュームの名前を参照する `mountPoints` 値と、コンテナにボリュームをマウントするための `containerPath` 値を使用して、コンテナを定義します。

   ```
   "containerDefinitions": [
       {
           "name": "container-1",
           "mountPoints": [
           {
             "sourceVolume": "database",
             "containerPath": "/var/database"
           }
         ]
       },
       {
         "name": "container-2",
         "mountPoints": [
           {
             "sourceVolume": "database",
             "containerPath": "/var/database"
           }
         ]
       }
     ]
   ```

**Docker ボリュームを使用してコンテナの NFS 永続的ストレージを提供する**

 この例では、コンテナはタスクの開始時に自動的にマウントされ、タスクの停止時にアンマウントされる NFS データボリュームを使用します。これは Docker ビルトイン `local` ドライバーを使用します。ユースケースの一例としては、ローカル NFS ストレージがあり、ECS Anywhere タスクからアクセスする必要がある場合があります。これは、NFS ドライバーオプションの Docker ボリュームを使用して実現できます。

1. タスク定義の `volumes` セクションで、`name` および `DockerVolumeConfiguration` 値を使用して、データボリュームを定義します。この例では、タスクが停止した後にボリュームがアンマウントされるように `task` のスコープを指定してください。`local` ドライバーを使用し、`type`、`device`、および `o` オプションを適宜使用して `driverOpts` を設定します。`NFS_SERVER` は NFS サーバーエンドポイントに置き換えます。

   ```
   "volumes": [
          {
              "name": "NFS",
              "dockerVolumeConfiguration" : {
                  "scope": "task",
                  "driver": "local",
                  "driverOpts": {
                      "type": "nfs",
                      "device": "$NFS_SERVER:/mnt/nfs",
                      "o": "addr=$NFS_SERVER"
                  }
              }
          }
      ]
   ```

1. `containerDefinitions` セクションで、定義したボリュームの名前を参照する `mountPoints` 値と、コンテナにボリュームをマウントするための `containerPath` 値を使用して、コンテナを定義します。

   ```
   "containerDefinitions": [
          {
              "name": "container-1",
              "mountPoints": [
                  {
                    "sourceVolume": "NFS",
                    "containerPath": "/var/nfsmount"
                  }
              ]
          }
      ]
   ```