Amazon Elastic Container Service
Developer Guide (API Version 2014-11-13)

Tutorial: Creating a Cluster with a Fargate Task Using the ECS CLI

This tutorial shows you how to set up a cluster and deploy a task using the Fargate launch type.


It is expected that you have completed the following prerequisites before continuing on:

Step 1: Create the Task Execution IAM Role

Amazon ECS needs permissions so that your Fargate task will be able to store logs in CloudWatch. This permission is covered by the task execution IAM role. For more information, see Amazon ECS Task Execution IAM Role.

Create the Task Execution IAM Role

  1. Create a file named execution-assume-role.json with the following contents:

    { "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "" }, "Action": "sts:AssumeRole" } ] }
  2. Using the AWS CLI, create the task execution role:

    aws iam --region us-east-1 create-role --role-name ecsExecutionRole --assume-role-policy-document file://execution-assume-role.json
  3. Using the AWS CLI, attach the task execution role policy:

    aws iam --region us-east-1 attach-role-policy --role-name ecsExecutionRole --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy

Step 2: Configure the ECS CLI

The ECS CLI requires credentials in order to make API requests on your behalf. It can pull credentials from environment variables, an AWS profile, or an Amazon ECS profile. For more information see Configuring the Amazon ECS CLI.

Create an ECS CLI Configuration

  1. Create a cluster configuration, which defines the AWS region to use, resource creation prefixes, and the cluster name to use with the Amazon ECS CLI:

    ecs-cli configure --cluster tutorial --region us-east-1 --default-launch-type FARGATE --config-name tutorial
  2. Create a CLI profile using your access key and secret key:

    ecs-cli configure profile --access-key AWS_ACCESS_KEY_ID --secret-key AWS_SECRET_ACCESS_KEY --profile-name tutorial


    If this is the first time you are configuring the ECS CLI these configurations will be marked as default. If this is not your first time configuring the ECS CLI, see ecs-cli configure default and ecs-cli configure profile default to set this as the default configuration and profile.

Step 3: Create a Cluster and Security Group

Create an Amazon ECS cluster with the ecs-cli up command. Since you specified Fargate as your default launch type in the cluster configuration, this command will create an empty cluster and a VPC configured with two public subnets.

ecs-cli up


This command may take a few minutes to complete as your resources are created. Take note of the VPC and subnet IDs that are created as they will be used later.

Using the AWS CLI create a security group using the VPC ID from the previous output:

aws ec2 create-security-group --group-name "my-sg" --description "My security group" --vpc-id "VPC_ID"

Using AWS CLI, add a security group rule to allow inbound access on port 80:

aws ec2 authorize-security-group-ingress --group-id "security_group_id" --protocol tcp --port 80 --cidr

Step 4: Create a Compose File

For this step, create a simple Docker compose file that creates a WordPress application. At this time, the Amazon ECS CLI supports Docker compose file syntax versions 1 and 2.

Here is the compose file, which you can call docker-compose.yml. The wordpress container exposes port 80 for inbound traffic to the web server. It also configures container logs to go to the CloudWatch log group created earlier. This is the recommended best practice for Fargate tasks.

version: '2' services: wordpress: image: wordpress ports: - "80:80" logging: driver: awslogs options: awslogs-group: tutorial awslogs-region: us-east-1 awslogs-stream-prefix: wordpress

In addition to the Docker compose information, there are some Amazon ECS specific parameters you need to specify for the service. Using the VPC, subnet, and security group IDs from the previous step, create a file named ecs-params.yml with the following content:

version: 1 task_definition: task_execution_role: ecsExecutionRole ecs_network_mode: awsvpc task_size: mem_limit: 0.5GB cpu_limit: 256 run_params: network_configuration: awsvpc_configuration: subnets: - "subnet ID 1" - "subnet ID 2" security_groups: - "security group ID" assign_public_ip: ENABLED


The assign_public_ip and task_size parameters are only valid for a Fargate task. This task definition will fail if the launch type is changed to EC2.

Step 5: Deploy the Compose File to a Cluster

After you create the compose file, you can deploy it to your cluster with ecs-cli compose service up. By default, the command looks for files called docker-compose.yml and ecs-params.yml in the current directory; you can specify a different docker compose file with the --file option, and a different ECS Params file with the --ecs-params option. By default, the resources created by this command have the current directory in their titles, but you can override that with the --project-name option. The --create-log-groups option will create the CloudWatch log groups for the container logs.

ecs-cli compose --project-name tutorial service up --create-log-groups

Step 6: View the Running Containers on a Cluster

After you deploy the compose file, you can view the containers that are running in the service with ecs-cli compose service ps.

ecs-cli compose --project-name tutorial service ps


WARN[0000] Skipping unsupported YAML option... option name=networks WARN[0000] Skipping unsupported YAML option for service... option name=networks service name=wordpress Name State Ports TaskDefinition a06a6642-12c5-4006-b1d1-033994580605/wordpress RUNNING>80/tcp tutorial:9

In the above example, you can see the wordpress container from your compose file, and also the IP address and port of the web server. If you point your web browser at that address, you should see the WordPress installation wizard. Also in the output is the task-id of the container. Copy the task ID; you will use it in the next step.

Step 7: View the Container Logs

View the logs for the task:

ecs-cli logs --task-id a06a6642-12c5-4006-b1d1-033994580605 --follow


The --follow option tells the ECS CLI to continously poll for logs.

Step 8: Scale the Tasks on the Cluster

You can scale up your task count to increase the number of instances of your application with ecs-cli compose service scale. In this example, the running count of the application is increased to two.

ecs-cli compose --project-name tutorial service scale 2

Now you should see two more containers in your cluster:

ecs-cli compose --project-name tutorial service ps


WARN[0000] Skipping unsupported YAML option... option name=networks WARN[0000] Skipping unsupported YAML option for service... option name=networks service name=wordpress Name State Ports TaskDefinition 880f09ed-613d-44bf-99bb-42ca44f82904/wordpress RUNNING>80/tcp tutorial:9 a06a6642-12c5-4006-b1d1-033994580/wordpress RUNNING>80/tcp tutorial:9

Step 9: Clean Up

When you are done with this tutorial, you should clean up your resources so they do not incur any more charges. First, delete the service so that it stops the existing containers and does not try to run any more tasks.

ecs-cli compose --project-name tutorial service down

Now, take down your cluster, which cleans up the resources that you created earlier with ecs-cli up.

ecs-cli down --force