Bind mounts
With bind mounts, a file or directory on the host machine is mounted into a
container. To use bind mount host volumes, specify a host
and optional
sourcePath
value in your task definition. For more information, see
Using bind
mounts
For information on the task storage for Amazon ECS on Fargate tasks, see Fargate Task Storage.
Some common use cases for bind mounts are:
-
To provide persistent data volumes for use with containers
-
To define an empty, nonpersistent data volume and mount it on multiple containers on the same container instance
-
To share defined data volumes at different locations on different containers on the same container instance
Specifying a bind mount in your task definition
Before your containers can use bind mount host 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 bind
mount host volume, specify a host
value and optional
sourcePath
value.
The following task definition JSON snippet shows the syntax for the
volumes
and mountPoints
objects for a
container:
{ "family": "", ... "containerDefinitions" : [ { "mountPoints" : [ { "containerPath" : "
/path/to/mount_volume
", "sourceVolume" : "string
" } ], "name" : "string
" } ], ... "volumes" : [ { "host" : { "sourcePath" : "string
" }, "name" : "string
" } ] }
name
-
Type: String
Required: No
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 definitionmountPoints
object. host
-
Required: No
This parameter is specified when using bind mounts. To use Docker volumes, specify a
dockerVolumeConfiguration
instead. The contents of thehost
parameter determine whether your bind mount data volume persists on the host container instance and where it is stored. If thehost
parameter is empty, then the Docker daemon assigns a host path for your data volume, but the data is not guaranteed to persist after the containers associated with it stop running.Bind mount host volumes are supported when using either the EC2 or Fargate launch types.
Windows containers can mount whole directories on the same drive as
$env:ProgramData
.sourcePath
-
Type: String
Required: No
When the
host
parameter is used, specify asourcePath
to declare the path on the host container instance that is presented to the container. If this parameter is empty, then the Docker daemon has assigned a host path for you. If thehost
parameter contains asourcePath
file location, then the data volume persists at the specified location on the host container instance until you delete it manually. If thesourcePath
value does not exist on the host container instance, the Docker daemon creates it. If the location does exist, the contents of the source path folder are exported.
mountPoints
-
Type: Object Array
Required: No
The mount points for data volumes in your container.
This parameter maps to
Volumes
in the Create a containersection of the Docker Remote API and the --volume
option to docker run. 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 usedThe name of the volume to mount.
containerPath
-
Type: String
Required: Yes, when
mountPoints
are usedThe 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 isfalse
, then the container can write to the volume. The default value isfalse
.
Examples
To provide nonpersistent empty storage for containers using a bind mount
In some cases, you want containers to share the same empty data volume, but you aren't interested in keeping the data after the task has finished. For example, you may have two database containers that need to access the same scratch file storage location during a task. This task can be achieved using either a Docker volume or a bind mount host volume.
-
In the task definition
volumes
section, define a bind mount with the namedatabase_scratch
.Note Because the
database_scratch
bind mount does not specify a source path, the Docker daemon manages the bind mount for you. When no containers reference this bind mount, the Amazon ECS container agent task cleanup service eventually deletes it (by default, this happens 3 hours after the container exits, but you can configure this duration with theECS_ENGINE_TASK_CLEANUP_WAIT_DURATION
agent variable). For more information, see Amazon ECS Container Agent Configuration. If you need this data to persist, specify asourcePath
value for the bind mount."volumes": [ { "name": "
database_scratch
", "host": {} } ] -
In the
containerDefinitions
section, create the database container definitions so that they mount the nonpersistent storage."containerDefinitions": [ { "name": "
database1
", "image": "my-repo/database
", "cpu": 100, "memory": 100, "essential": true, "mountPoints": [ { "sourceVolume": "database_scratch
", "containerPath": "/var/scratch
" } ] }, { "name": "database2
", "image": "my-repo/database
", "cpu": 100, "memory": 100, "essential": true, "mountPoints": [ { "sourceVolume": "database_scratch
", "containerPath": "/var/scratch
" } ] } ]
To provide persistent storage for containers using a bind mount
When using bind mounts, if a sourcePath
value is specified
the data persists even after all containers that referenced it have stopped.
Any files that exist at the sourcePath
are presented to the
containers at the containerPath
value, and any files that are
written to the containerPath
value are written to the
sourcePath
value on the container instance.
Amazon ECS doesn't sync your storage across container instances. Tasks that use persistent storage can be placed on any container instance in your cluster that has available capacity. If your tasks require persistent storage after stopping and restarting, you should always specify the same container instance at task launch time with the AWS CLI start-task command.
-
In the task definition
volumes
section, define a bind mount withname
andsourcePath
values."volumes": [ { "name": "
webdata
", "host": { "sourcePath": "/ecs/webdata
" } } ] -
In the
containerDefinitions
section, define a container withmountPoints
values that reference the name of the defined bind mount and thecontainerPath
value to mount the bind mount at on the container."containerDefinitions": [ { "name": "web", "image": "nginx", "cpu": 99, "memory": 100, "portMappings": [ { "containerPort": 80, "hostPort": 80 } ], "essential": true, "mountPoints": [ { "sourceVolume": "
webdata
", "containerPath": "/usr/share/nginx/html
" } ] } ]
To mount a defined volume on multiple containers
You can define a data volume in a task definition and mount that volume at
different locations on different containers. For example, your host
container has a website data folder at /data/webroot
,
and you may want to mount that data volume as read-only on two different web
servers that have different document roots.
-
In the task definition
volumes
section, define a data volume with the namewebroot
and the source path/data/webroot
."volumes": [ { "name": "
webroot
", "host": { "sourcePath": "/data/webroot
" } } ] -
In the
containerDefinitions
section, define a container for each web server withmountPoints
values that associate thewebroot
volume with thecontainerPath
value pointing to the document root for that container."containerDefinitions": [ { "name": "
web-server-1
", "image": "my-repo/ubuntu-apache
", "cpu": 100, "memory": 100, "portMappings": [ { "containerPort": 80, "hostPort": 80 } ], "essential": true, "mountPoints": [ { "sourceVolume": "webroot
", "containerPath": "/var/www/html
", "readOnly": true } ] }, { "name": "web-server-2
", "image": "my-repo/sles11-apache
", "cpu": 100, "memory": 100, "portMappings": [ { "containerPort": 8080, "hostPort": 8080 } ], "essential": true, "mountPoints": [ { "sourceVolume": "webroot
", "containerPath": "/srv/www/htdocs
", "readOnly": true } ] } ]
To mount volumes from another container using
volumesFrom
You can define one or more volumes on a container, and then use the
volumesFrom
parameter in a different container definition
(within the same task) to mount all of the volumes from the
sourceContainer
at their originally defined mount points.
The volumesFrom
parameter applies to volumes defined in the
task definition, and those that are built into the image with a
Dockerfile.
-
(Optional) To share a volume that is built into an image, you need to build the image with the volume declared in a
VOLUME
instruction. The following example Dockerfile uses anhttpd
image and then adds a volume and mounts it atdockerfile_volume
in the Apache document root (which is the folder used by thehttpd
web server):FROM httpd VOLUME ["/usr/local/apache2/htdocs/dockerfile_volume"]
You can build an image with this Dockerfile and push it to a repository, such as Docker Hub, and use it in your task definition. The example
my-repo/httpd_dockerfile_volume
image used in the following steps was built with the above Dockerfile. -
Create a task definition that defines your other volumes and mount points for the containers. In this example
volumes
section, you create an empty volume calledempty
, which the Docker daemon manages. There is also a host volume defined calledhost_etc
, which exports the/etc
folder on the host container instance.{ "family": "test-volumes-from", "volumes": [ { "name": "empty", "host": {} }, { "name": "host_etc", "host": { "sourcePath": "/etc" } } ],
In the container definitions section, create a container that mounts the volumes defined earlier. In this example, the
web
container (which uses the image built with a volume in the Dockerfile) mounts theempty
andhost_etc
volumes."containerDefinitions": [ { "name": "web", "image": "
my-repo/httpd_dockerfile_volume
", "cpu": 100, "memory": 500, "portMappings": [ { "containerPort": 80, "hostPort": 80 } ], "mountPoints": [ { "sourceVolume": "empty", "containerPath": "/usr/local/apache2/htdocs/empty_volume" }, { "sourceVolume": "host_etc", "containerPath": "/usr/local/apache2/htdocs/host_etc" } ], "essential": true },Create another container that uses
volumesFrom
to mount all of the volumes that are associated with theweb
container. All of the volumes on theweb
container are likewise mounted on thebusybox
container (including the volume specified in the Dockerfile that was used to build themy-repo/httpd_dockerfile_volume
image).{ "name": "busybox", "image": "busybox", "volumesFrom": [ { "sourceContainer": "web" } ], "cpu": 100, "memory": 500, "entryPoint": [ "sh", "-c" ], "command": [ "echo $(date) > /usr/local/apache2/htdocs/empty_volume/date && echo $(date) > /usr/local/apache2/htdocs/host_etc/date && echo $(date) > /usr/local/apache2/htdocs/dockerfile_volume/date" ], "essential": false } ] }
When this task is run, the two containers mount the volumes, and the
command
in thebusybox
container writes the date and time to a file calleddate
in each of the volume folders. The folders are then visible at the website displayed by theweb
container.Note Because the
busybox
container runs a quick command and then exits, it must be set as"essential": false
in the container definition. Otherwise, it stops the entire task when it exits.