Docker Volumes

When using Docker volumes, the built-in local driver or a third-party
volume driver can be used. Docker volumes are managed by Docker and a directory is
created in /var/lib/docker/volumes on the container instance that
contains the volume data.

To use Docker volumes, specify a dockerVolumeConfiguration in your
task definition. For more information, see Using Volumes.

Some common use cases for Docker volumes are:

To provide persistent data volumes for use with containers

To share a defined data volume at different locations on different
containers on the same container instance

To define an empty, nonpersistent data volume and mount it on multiple
containers within the same task

To provide a data volume to your task that is managed by a third-party
driver

Docker Volume
Considerations

The following should be considered when using Docker volumes:

Docker volumes are only supported when using the EC2
launch type.

Windows containers only support the use of the local
driver.

If a third-party driver is used, it should be installed and active on
the container instance prior to the container agent starting. If the
third-party driver is not active prior to the agent starting, you can
restart the container agent using one of the following commands:

For the Amazon ECS-optimized Amazon Linux 2 AMI:

sudo systemctl restart ecs

For the Amazon ECS-optimized Amazon Linux AMI:

sudo stop ecs && sudo start ecs

Specifying a Docker Volume in your Task
Definition

Before your containers can use data volumes, you must specify the volume and
mount point configurations in your task definition. This section describes the
volume configuration for a container. For tasks that use a Docker volume,
specify a dockerVolumeConfiguration. For tasks that use a bind
mount host volume, specify a host and optional
sourcePath.

The task definition JSON shown below shows the syntax for the
volumes and mountPoints objects for a
container.

The name of the volume. Up to 255 letters (uppercase and lowercase),
numbers, hyphens, and underscores are allowed. This name is referenced
in the sourceVolume parameter of container definition
mountPoints.

dockerVolumeConfiguration

Type: Object

Required: No

This parameter is specified when using Docker volumes. Docker volumes are only
supported when using the EC2 launch type. Windows containers only support
the use of the local driver. To use bind mounts, specify a
host instead.

scope

Type: String

Valid Values: task | shared

Required: No

The scope for the Docker volume, which determines its lifecycle. Docker
volumes that are scoped to a task are automatically provisioned
when the task starts destroyed when the task is cleaned up. Docker volumes that
are scoped as shared persist after the task stops.

autoprovision

Type: Boolean

Default value: false

Required: No

If this value is true, the Docker volume is created if it
does not already exist. This field is only used if the scope is
shared. If the scope is task then
this parameter must either be omitted or set to false.

driver

Type: String

Required: No

The Docker volume driver to use. The driver value must match the driver
name provided by Docker because it is used for task placement. If the driver
was installed using the Docker plugin CLI, use docker plugin ls
to retrieve the driver name from your container instance. If the driver was
installed using another method, use Docker plugin discovery to retrieve the
driver name. For more information, see Docker plugin discovery. This parameter maps to
Driver in the Create a
volume section of the Docker Remote API and the
--driver option to docker volume create.

Windows containers can mount whole directories on the same drive as
$env:ProgramData. Windows containers cannot mount
directories on a different drive, and mount point cannot be across
drives.

sourceVolume

Type: String

Required: Yes, when mountPoints are
used

The name of the volume to mount.

containerPath

Type: String

Required: Yes, when mountPoints are
used

The path on the container to mount the volume at.

readOnly

Type: Boolean

Required: No

If this value is true, the container has
read-only access to the volume. If this value is
false, then the container can write to the
volume. The default value is false.

Examples

The following are examples showing the use of Docker volumes.

To provide nonpersistent storage for a container using a Docker
volume

In this example, you want a container to use an empty data volume that you
aren't interested in keeping after the task has finished. For example, you
may have a container that needs to access some scratch file storage location
during a task. This task can be achieved using a Docker volume.

In the task definition volumes section, define a data
volume with name and DockerVolumeConfiguration
values. In this example, we specify the scope as task so
the volume is deleted after the task stops and use the built-in
local driver.

In this example, you want a shared volume for multiple containers to use
and you want it to persist after any single task using it has stopped. The
built-in local driver is being used so the volume is still tied
to the lifecycle of the container instance.

In the task definition volumes section, define a data
volume with name and DockerVolumeConfiguration
values. In this example, specify a shared scope so the
volume persists, set autoprovision to true so that the
volume is created for use, and use the built-in local
driver.