Tutorial: Using Amazon EFS file systems with Amazon ECS using the console - Amazon Elastic Container Service
Step 1: Create an Amazon ECS clusterStep 2: Create a security group for Amazon EC2 instances and the Amazon EFS file systemStep 3: Create an Amazon EFS file systemStep 4: Add content to the Amazon EFS file systemStep 5: Create a task definitionStep 6: Run a task and view the results

Tutorial: Using Amazon EFS file systems with Amazon ECS using the console

Amazon Elastic File System (Amazon EFS) provides simple, scalable file storage for use with your Amazon ECS tasks. With Amazon EFS, storage capacity is elastic, growing and shrinking automatically as you add and remove files. Your applications can have the storage they need, when they need it.

You can use Amazon EFS file systems with Amazon ECS to access file system data across your fleet of Amazon ECS tasks. That way, your tasks have access to the same persistent storage, no matter the infrastructure or container instance on which they land. When you reference your Amazon EFS file system and container mount point in your Amazon ECS task definition, Amazon ECS takes care of mounting the file system in your container. The following sections help you get started using Amazon EFS with Amazon ECS.

This feature is supported by tasks that use both the EC2 and Fargate launch types, however this tutorial will use an Amazon ECS task that uses the EC2 launch type. This tutorial is also meant to be followed step by step, however if you already have some of these resources created on your account then you may be able to skip some steps.

Note

Amazon EFS may not be available in all Regions. For more information about which Regions support Amazon EFS, see Amazon Elastic File System Endpoints and Quotas in the AWS General Reference.

Step 1: Create an Amazon ECS cluster

Use the following steps to create an Amazon ECS cluster.

To create a new cluster (Amazon ECS console)

Before you begin, assign the appropriate IAM permission. For more information, see Cluster examples.

  1. Open the console at https://console.aws.amazon.com/ecs/v2.

  2. From the navigation bar, select the Region to use.

  3. In the navigation pane, choose Clusters.

  4. On the Clusters page, choose Create cluster.

  5. Under Cluster configuration, for Cluster name, enter EFS-tutorial for the cluster name.

  6. (Optional) To change the VPC and subnets where your tasks and services launch, under Networking, perform any of the following operations:

    • To remove a subnet, under Subnets, choose X for each subnet that you want to remove.

    • To change to a VPC other than the default VPC, under VPC, choose an existing VPC, and then under Subnets, select each subnet.

  7. To add Amazon EC2 instances to your cluster, expand Infrastructure, and then select Amazon EC2 instances. Next, configure the Auto Scaling group which acts as the capacity provider:

    1. To create a Auto Scaling group, from Auto Scaling group (ASG), select Create new group, and then provide the following details about the group:

      • For Operating system/Architecture, choose Amazon Linux 2.

      • For EC2 instance type, choose t2.micro.

        For SSH key pair, choose the pair that proves your identity when you connect to the instance.

      • For Capacity, enter 1.

  8. Choose Create.

Step 2: Create a security group for Amazon EC2 instances and the Amazon EFS file system

In this step, you create a security group for your Amazon EC2 instances that allows inbound network traffic on port 80 and your Amazon EFS file system that allows inbound access from your container instances.

Create a security group for your Amazon EC2 instances with the following options:

  • Security group name - a unique name for your security group.

  • VPC - the VPC that you identified earlier for your cluster.

  • Inbound rule

    • Type - HTTP

    • Source - 0.0.0.0/0.

Create a security group for your Amazon EFS file system with the following options:

  • Security group name - a unique name for your security group. For example, EFS-access-for-sg-dc025fa2.

  • VPC - the VPC that you identified earlier for your cluster.

  • Inbound rule

    • Type - NFS

    • Source - Custom with the ID of the security group you created for your instances.

For information about how to create a security group, see Create a security group in the Amazon EC2 User Guide for Linux Instances.

Step 3: Create an Amazon EFS file system

In this step, you create an Amazon EFS file system.

To create an Amazon EFS file system for Amazon ECS tasks.

  1. Open the Amazon Elastic File System console at https://console.aws.amazon.com/efs/.

  2. Choose Create file system.

  3. Enter a name for your file system and then choose the VPC that your container instances are hosted in. By default, each subnet in the specified VPC receives a mount target that uses the default security group for that VPC. Then, choose Customize.

    Important

    Your Amazon EFS file system, your Amazon ECS cluster, container instances, and tasks must be in the same VPC.

  4. On the File system settings page, configure optional settings and then under Performance settings, choose the Bursting throughput mode for your file system. After you have configured settings, select Next.

    1. (Optional) Add tags for your file system. For example, you could specify a unique name for the file system by entering that name in the Value column next to the Name key.

    2. (Optional) Enable lifecycle management to save money on infrequently accessed storage. For more information, see EFS Lifecycle Management in the Amazon Elastic File System User Guide.

    3. (Optional) Enable encryption. Select the check box to enable encryption of your Amazon EFS file system at rest.

  5. On the Network access page, under Mount targets, replace the existing security group configuration for every availability zone with the security group you created for the file system in Step 2: Create a security group for Amazon EC2 instances and the Amazon EFS file system and then choose Next.

  6. You do not need to configure File system policy for this tutorial, so you can skip the section by choosing Next.

  7. Review your file system options and choose Create to complete the process.

  8. From the File systems screen, record the File system ID. In the next step, you will reference this value in your Amazon ECS task definition.

Step 4: Add content to the Amazon EFS file system

In this step, you mount the Amazon EFS file system to an Amazon EC2 instance and add content to it. This is for testing purposes in this tutorial, to illustrate the persistent nature of the data. When using this feature you would normally have your application or another method of writing data to your Amazon EFS file system.

To create an Amazon EC2 instance and mount the Amazon EFS file system

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. Choose Launch Instance.

  3. Under Application and OS Images (Amazon Machine Image), select the Amazon Linux 2 AMI (HVM).

  4. Under Instance type, keep the default instance type, t2.micro.

  5. Under Key pair (login), select a key pair for SSH access to the instance.

  6. Under Network settings, select the VPC that you specified for your Amazon EFS file system and Amazon ECS cluster. Select a subnet and the instance security group created in Step 2: Create a security group for Amazon EC2 instances and the Amazon EFS file system. Configure the instance's security group. Ensure that Auto-assign public IP is enabled.

  7. Under Configure storage, choose the Edit button for file systems and then choose EFS. Select the file system you created in Step 3: Create an Amazon EFS file system. You can optionally change the mount point or leave the default value.

    Important

    Your must select a subnet before you can add a file system to the instance.

  8. Uncheck the Automatically create and attach security groups check box since you created a security group for your file system earlier. Leave the other check box checked. Choose Add shared file system.

  9. Under Advanced Details, ensure that the user data script is populated automatically with the Amazon EFS file system mounting steps.

  10. Under Summary, ensure the Number of instances is 1. Choose Launch instance.

  11. On the Launch an instance page, choose View all instances to see the status of your instances. Initially, the Instance state status is PENDING. After the state changes to RUNNING and the instance passes all status checks, the instance is ready for use.

Now, you connect to the Amazon EC2 instance and add content to the Amazon EFS file system.

To connect to the Amazon EC2 instance and add content to the Amazon EFS file system

  1. SSH to the Amazon EC2 instance you created. For more information, see Connect to Your Linux Instance in the Amazon EC2 User Guide for Linux Instances.

  2. From the terminal window, run the df -T command to verify that the Amazon EFS file system is mounted. In the following output, we have highlighted the Amazon EFS file system mount.

    $ df -T
Filesystem     Type            1K-blocks    Used        Available Use% Mounted on
devtmpfs       devtmpfs           485468       0           485468   0% /dev
tmpfs          tmpfs              503480       0           503480   0% /dev/shm
tmpfs          tmpfs              503480     424           503056   1% /run
tmpfs          tmpfs              503480       0           503480   0% /sys/fs/cgroup
/dev/xvda1     xfs               8376300 1310952          7065348  16% /
127.0.0.1:/    nfs4     9007199254739968       0 9007199254739968   0% /mnt/efs/fs1
tmpfs          tmpfs              100700       0           100700   0% /run/user/1000

  3. Navigate to the directory that the Amazon EFS file system is mounted at. In the example above, that is /mnt/efs/fs1.

  4. Create a file named index.html with the following content:

    <html>
    <body>
        <h1>It Works!</h1>
        <p>You are using an Amazon EFS file system for persistent container storage.</p>
    </body>
</html>

Step 5: Create a task definition

The following task definition creates a data volume named efs-html. The nginx container mounts the host data volume at the NGINX root, /usr/share/nginx/html.

To create a new task definition using the Amazon ECS console

  1. Open the console at https://console.aws.amazon.com/ecs/v2.

  2. In the navigation pane, choose Task definitions.

  3. Choose Create new task definition, Create new task definition with JSON.

  4. In the JSON editor box, copy and paste the following JSON text, replacing the fileSystemId with the ID of your Amazon EFS file system.

    {
    "containerDefinitions": [
        {
            "memory": 128,
            "portMappings": [
                {
                    "hostPort": 80,
                    "containerPort": 80,
                    "protocol": "tcp"
                }
            ],
            "essential": true,
            "mountPoints": [
                {
                    "containerPath": "/usr/share/nginx/html",
                    "sourceVolume": "efs-html"
                }
            ],
            "name": "nginx",
            "image": "nginx"
        }
    ],
    "volumes": [
        {
            "name": "efs-html",
            "efsVolumeConfiguration": {
                "fileSystemId": "fs-1324abcd",
                "transitEncryption": "ENABLED"
            }
        }
    ],
    "family": "efs-tutorial"
}

  5. Choose Create.

Step 6: Run a task and view the results

Now that your Amazon EFS file system is created and there is web content for the NGINX container to serve, you can run a task using the task definition that you created. The NGINX web server serves your simple HTML page. If you update the content in your Amazon EFS file system, those changes are propagated to any containers that have also mounted that file system.

The task runs in the subnet that you defined for the cluster.

To run a task and view the results using the console

  1. Open the console at https://console.aws.amazon.com/ecs/v2.

  2. On the Clusters page, select the cluster to run the standalone task in.

    Determine the resource from where you launch the service.

    To start a service from Steps

    Clusters

    1. On the Clusters page, select the cluster to create the service in.

    2. From the Tasks tab, choose Run new task.
    Launch type

    1. On the Task page, choose the task definition.

    2. If there is more than one revision, select the revision.

    3. Choose Create, Run task.

  3. (Optional) Choose how your scheduled task is distributed across your cluster infrastructure. Expand Compute configuration, and then do the following:

    Distribution method Steps
    Launch type

    1. In the Compute options section, select Launch type.

    2. For Launch type, choose EC2.

  4. For Application type, choose Task.

  5. For Task definition, choose the efs-tutorial task definition that you created earlier .

    Important

    The console validates the selection to ensure that the selected task definition family and revision is compatible with the defined compute configuration.

  6. For Desired tasks, enter 1.

  7. Choose Create.

  8. On the Cluster page, choose Infrastructure.

  9. Under Container Instances, choose the container instance to connect to.

  10. On the Container Instance page, under Networking, record the Public IP for your instance.

  11. Open a browser and enter the public IP address browser, You should see the following message:

    It works!
You are using an Amazon EFS file system for persistent container storage.
    Note

    If you do not see the message, make sure that the security group for your container instance allows inbound network traffic on port 80 and the security group for your file system allows inbound access from the container instance.