How do I mount an Amazon EFS file system on an Amazon ECS container or a task that runs on Fargate?

Resolution

Important: The following resolution applies to the Fargate version 1.4.0 and later. These versions have persistent storage that you can define at the task and container level in Amazon ECS. Fargate versions 1.3.0 or earlier don't support the use of persistent storage with Amazon EFS.

Prerequisites

You must have the following:

• Amazon ECS cluster
• Amazon Virtual Private Cloud (Amazon VPC)

Create and configure an Amazon EFS file system

1. Create an Amazon EFS file system, and then note the Amazon EFS ID and security group ID.
   Note: Your Amazon EFS file system, Amazon ECS cluster, and Fargate tasks must all be in the same Amazon VPC.
2. Edit the security group rules of your EFS file system to allow inbound connections. You must allow connections on port 2049 from the security group associated with your Fargate task or service.
3. Update the security group of your Amazon ECS service to allow outbound connections on port 2049 to your Amazon EFS file system's security group.

Create a task definition

1. Open the Amazon ECS console.
2. From the navigation pane, choose Task Definitions,
3. In Create new Task Definition, choose Create new Task Definition.
4. In the Task definition configuration section, for Task definition family, enter a name for your task definition.
5. In the Infrastructure requirements section:
   For Launch type, select AWS Fargate.
   For Task size, choose the CPU and memory values for the task.
   Note: Fargate supports specific combinations for CPU and memory. For more information on supported CPU and memory combinations for Fargate, see Task size.
   (Optional) For Task role and Task execution role, select the task and task execution IAM role to use for the task.
   For more information on the task role and task execution role, see IAM Roles for Amazon ECS.
6. In the Container - 1 section:
   For Name, enter a name for the container.
   For Image URI, provide the image URI for your container.
   For Essential container, confirm Yes is selected.
   (Optional) For Port mappings, if your container is listening on a specific port, then input the Container port and select the Protocol and App Protocol configurations.
   (Optional) For Log collection, select to Use log collection. By default, an Amazon CloudWatch log configuration is present.
   Note: Cloudwatch log collection requires a task execution role.
7. In the Storage section, under Volumes, select Add volume. A Volume - 1 section will appear.
8. In the Volume - 1 section.
   Under Volume name, give a name to your volume.
   For Configuration type, select Configure at task definition creation.
   For Volume type, select EFS.
   For File system ID, select the Amazon EFS file system ID which you would like to attach to this task.
   (Optional) Specify an alternative value for Root directory and specify an EFS Access Point under Access point ID.
   (Optional) Select Advanced configurations and specify custom options for Transit encryption and IAM authorization.
9. Under Container mount points, select Add mount point.
   For Container, select your container name.
   For Source volume, select the Amazon EFS volume you created.
   For Container path, enter the full path for your Amazon EFS volume mount. The contents of the Amazon EFS volume are available at this path from within the container.
10. Select Create.

In the following example, the JSON task definition uses an infinite loop to keep the task running. The task definition creates a data volume named efs-test. The nginx container mounts the Any_Container_Path path.

Example of the JSON task definition:

{
  "family": "sample-fargate-test",
  "networkMode": "awsvpc",
  "executionRoleArn": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole",
  "containerDefinitions": [
    {
      "name": "fargate-app",
      "image": "nginx",
      "portMappings": [
        {
          "containerPort": 80,
          "hostPort": 80,
          "protocol": "tcp"
        }
      ],
      "essential": true,
      "entryPoint": [
        "sh",
        "-c"
      ],
      "command": [
        "df -h && while true; do echo \"RUNNING\"; done"
      ],
      "mountPoints": [
        {
          "sourceVolume": "efs-test",
          "containerPath": "Any_Container_Path"
        }
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "AWS_LOG_GROUP_PATH",
          "awslogs-region": "AWS_REGION",
          "awslogs-stream-prefix": "AWS_STREAM_PREFIX"
        }
      }
    }
  ],
  "volumes": [
    {
      "name": "efs-test",
      "efsVolumeConfiguration": {
        "fileSystemId": "FILE_SYSTEM_ID"
      }
    }
  ],
  "requiresCompatibilities": [
    "FARGATE"
  ],
  "cpu": "256",
  "memory": "512"
}

Note: Replace FILE_SYSTEM_ID with your Amazon EFS file system ID. AWS_LOG_GROUP_PATH with your CloudWatch log group name. AWS_REGION with your AWS Region and AWS_STREAM_PREFIX with your log stream prefix. Also, confirm that your task definition specifies a task execution role Amazon Resource Name (ARN), which is required for the awslogs log driver.

To mount Amazon EFS file systems at different container paths, define multiple mount points and volumes in your task definition.

Run a Fargate task and check your task logs

1. Run a Fargate task using the task definition that you created earlier.
   Important: Use Fargate platform version 1.4.0 to run your task.
2. To verify that your Amazon EFS file system is successfully mounted to your Fargate container, check your task logs.
   The output of df-h looks similar to the following:

   2020-10-27 15:15:35Filesystem 1K-blocks Used Available Use% Mounted on
   
   2020-10-27 15:15:35
   overlay 30832548 9859324 19383976 34% /
   
   2020-10-27 15:15:35
   tmpfs 65536 0 65536 0% /dev
   
   2020-10-27 15:15:35
   shm 2018788 0 2018788 0% /dev/shm
   
   2020-10-27 15:15:35
   tmpfs 2018788 0 2018788 0% /sys/fs/cgroup
   
   2020-10-27 15:15:35
   fs-xxxxxxxx.efs.us-east-1.amazonaws.com:/ 9007199254739968 0 9007199254739968 0% /Any_Container_Path
   
   2020-10-27 15:15:35
   /dev/xvdcz 30832548 9859324 19383976 34% /etc/hosts
   
   2020-10-27 15:15:35
   tmpfs 2018788 0 2018788 0% /proc/acpi
   
   2020-10-27 15:15:35
   tmpfs 2018788 0 2018788 0% /sys/firmware
   
   2020-10-27 15:15:35
   tmpfs 2018788 0 2018788 0% /proc/scsi
   
   RUNNING

Related information

Security and access controls for Amazon EFS volumes

Specify an Amazon EFS file system in an Amazon ECS task definition

Configuring Amazon EFS file systems for Amazon ECS using the console