Step 1: Create an Amazon ECS cluster Step 2: Create a security group for Amazon EC2 instances and the Amazon EFS file system Step 3: Create an Amazon EFS file system Step 4: Add content to the Amazon EFS file system Step 5: Create a task definition Step 6: Run a task and view the results

Configuring Amazon EFS file systems for Amazon ECS using the console

Learn how to use Amazon Elastic File System (Amazon EFS) file systems with Amazon ECS.

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 Amazon ECS cluster examples.

Open the console at https://console.aws.amazon.com/ecs/v2.
From the navigation bar, select the Region to use.
In the navigation pane, choose Clusters.
On the Clusters page, choose Create cluster.
Under Cluster configuration, for Cluster name, enter EFS-tutorial for the cluster name.
(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.
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.
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 for your Amazon EC2 instance in the Amazon EC2 User Guide.

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.

Open the Amazon Elastic File System console at https://console.aws.amazon.com/efs/.
Choose Create file system.
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.

Note
This tutorial assumes that your Amazon EFS file system, Amazon ECS cluster, container instances, and tasks are in the same VPC. For more information about mounting a file system from a different VPC, see Walkthrough: Mount a file system from a different VPC in the Amazon EFS User Guide.
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.
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.
You do not need to configure File system policy for this tutorial, so you can skip the section by choosing Next.
Review your file system options and choose Create to complete the process.
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

Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.
Choose Launch Instance.
Under Application and OS Images (Amazon Machine Image), select the Amazon Linux 2 AMI (HVM).
Under Instance type, keep the default instance type, t2.micro.
Under Key pair (login), select a key pair for SSH access to the instance.
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.
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.
Clear the Automatically create and attach security groups. Leave the other check box selected. Choose Add shared file system.
Under Advanced Details, ensure that the user data script is populated automatically with the Amazon EFS file system mounting steps.
Under Summary, ensure the Number of instances is 1. Choose Launch instance.
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

SSH to the Amazon EC2 instance you created. For more information, see Connect to your Linux instance using SSH in the Amazon EC2 User Guide.

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

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

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

Open the console at https://console.aws.amazon.com/ecs/v2.
In the navigation pane, choose Task definitions.
Choose Create new task definition, Create new task definition with JSON.

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": "public.ecr.aws/docker/library/nginx:latest"
        }
    ],
    "volumes": [
        {
            "name": "efs-html",
            "efsVolumeConfiguration": {
                "fileSystemId": "fs-1324abcd",
                "transitEncryption": "ENABLED"
            }
        }
    ],
    "family": "efs-tutorial",
    "executionRoleArn":"arn:aws:iam::111122223333:role/ecsTaskExecutionRole"
}

Note

You can add the following permissions to your Amazon ECS task execution IAM role to allow the Amazon ECS agent to locate and mount an Amazon EFS file system to a task at startup.

elasticfilesystem:ClientMount
elasticfilesystem:ClientWrite
elasticfilesystem:DescribeMountTargets
elasticfilesystem:DescribeFileSystems

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

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

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	On the Clusters page, select the cluster to create the service in. From the Tasks tab, choose Run new task.
Launch type	On the Task page, choose the task definition. If there is more than one revision, select the revision. Choose Create, Run task.

(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	In the Compute options section, select Launch type. For Launch type, choose EC2.

For Application type, choose Task.
For Task definition, choose the efs-tutorial task definition that you created earlier .
For Desired tasks, enter 1.
Choose Create.
On the Cluster page, choose Infrastructure.
Under Container Instances, choose the container instance to connect to.
On the Container Instance page, under Networking, record the Public IP for your instance.
Open a browser and enter the public IP address. 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.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Specify an Amazon EFS file system in a task definition

FSx for Windows File Server

Configuring Amazon EFS file systems for Amazon ECS using the console

Step 1: Create an Amazon ECS cluster

To create a new cluster (Amazon ECS console)

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

Step 3: Create an Amazon EFS file system

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

Note

Step 4: Add content to the Amazon EFS file system

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

Important

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

Step 5: Create a task definition

To create a new task definition using the Amazon ECS console

Note

Step 6: Run a task and view the results

To run a task and view the results using the console

Note