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

AWS CLI Walkthrough with a Fargate Task

The following steps will help you set up a cluster, register a task definition, run a task, and perform other common scenarios in Amazon ECS with the AWS CLI.

Important

Before you begin, be sure that you've completed the steps in Setting Up with Amazon ECS and that your AWS user has the required permissions specified in the Amazon ECS First Run Wizard IAM policy example.

Step 1: (Optional) Create a Cluster

Step 2: Register a Task Definition

Step 3: List Task Definitions

Step 4: Create a Service

Step 5: List Services

Step 6: Describe the Running Service

Step 1: (Optional) Create a Cluster

By default, your account receives a default cluster.

Note

The benefit of using the default cluster that is provided for you is that you don't have to specify the --cluster cluster_name option in the subsequent commands. If you do create your own, non-default, cluster you need to specify --cluster cluster_name for each command that you intend to use with that cluster.

Create your own cluster with a unique name with the following command:

aws ecs create-cluster --cluster-name fargate-cluster

Output:

{ "cluster": { "status": "ACTIVE", "statistics": [], "clusterName": "fargate-cluster", "registeredContainerInstancesCount": 0, "pendingTasksCount": 0, "runningTasksCount": 0, "activeServicesCount": 0, "clusterArn": "arn:aws:ecs:region:aws_account_id:cluster/fargate-cluster" } }

Step 2: Register a Task Definition

Before you can run a task on your ECS cluster, you must register a task definition. Task definitions are lists of containers grouped together. The following example is a simple task definition that creates a PHP web app. For more information about the available task definition parameters, see Amazon ECS Task Definitions.

{ "family": "sample-fargate", "networkMode": "awsvpc", "containerDefinitions": [ { "name": "fargate-app", "image": "httpd:2.4", "portMappings": [ { "containerPort": 80, "hostPort": 80, "protocol": "tcp" } ], "essential": true, "entryPoint": [ "sh", "-c" ], "command": [ "/bin/sh -c \"echo '<html> <head> <title>Amazon ECS Sample App</title> <style>body {margin-top: 40px; background-color: #333;} </style> </head><body> <div style=color:white;text-align:center> <h1>Amazon ECS Sample App</h1> <h2>Congratulations!</h2> <p>Your application is now running on a container in Amazon ECS.</p> </div></body></html>' > /usr/local/apache2/htdocs/index.html && httpd-foreground\"" ] } ], "requiresCompatibilities": [ "FARGATE" ], "cpu": "256", "memory": "512" }

The above example JSON can be passed to the AWS CLI in two ways: you can save the task definition JSON as a file and pass it with the --cli-input-json file://path_to_file.json option, or you can escape the quotation marks in the JSON and pass the JSON container definitions on the command line as in the below example. If you choose to pass the container definitions on the command line, your command additionally requires a --family parameter that is used to keep multiple versions of your task definition associated with each other.

To use a JSON file for container definitions:

aws ecs register-task-definition --cli-input-json file://$HOME/tasks/fargate-task.json

The register-task-definition returns a description of the task definition after it completes its registration.

{ "taskDefinition": { "status": "ACTIVE", "networkMode": "awsvpc", "family": "sample-fargate", "placementConstraints": [], "requiresAttributes": [ { "name": "com.amazonaws.ecs.capability.docker-remote-api.1.18" }, { "name": "ecs.capability.task-eni" } ], "cpu": "256", "compatibilities": [ "EC2", "FARGATE" ], "volumes": [], "memory": "512", "requiresCompatibilities": [ "FARGATE" ], "taskDefinitionArn": "arn:aws:ecs:region:aws_account_id:task-definition/sample-fargate:2", "containerDefinitions": [ { "environment": [], "name": "fargate-app", "mountPoints": [], "image": "httpd:2.4", "cpu": 0, "portMappings": [ { "protocol": "tcp", "containerPort": 80, "hostPort": 80 } ], "entryPoint": [ "sh", "-c" ], "command": [ "/bin/sh -c \"echo '<html> <head> <title>Amazon ECS Sample App</title> <style>body {margin-top: 40px; background-color: #333;} </style> </head><body> <div style=color:white;text-align:center> <h1>Amazon ECS Sample App</h1> <h2>Congratulations!</h2> <p>Your application is now running on a container in Amazon ECS.</p> </div></body></html>' > /usr/local/apache2/htdocs/index.html && httpd-foreground\"" ], "essential": true, "volumesFrom": [] } ], "revision": 2 } }

Step 3: List Task Definitions

You can list the task definitions for your account at any time with the list-task-definitions command. The output of this command shows the family and revision values that you can use together when calling run-task or start-task.

aws ecs list-task-definitions

Output:

{ "taskDefinitionArns": [ "arn:aws:ecs:region:aws_account_id:task-definition/sample-fargate:1", "arn:aws:ecs:region:aws_account_id:task-definition/sample-fargate:2" ] }

Step 4: Create a Service

After you have registered a task for your account, you can create a service for the registered task in your cluster. For this example, we will create a service where at least 2 instances of the sample-fargate:1 task definition will be kept running in your cluster.

aws ecs create-service --cluster fargate-cluster --service-name fargate-service --task-definition sample-fargate:1 --desired-count 2 --launch-type "FARGATE" --network-configuration "awsvpcConfiguration={subnets=[subnet-abcd1234],securityGroups=[sg-abcd1234]}"

Output:

{ "service": { "status": "ACTIVE", "taskDefinition": "arn:aws:ecs:region:aws_account_id:task-definition/sample-fargate:1", "pendingCount": 0, "launchType": "FARGATE", "loadBalancers": [], "roleArn": "arn:aws:iam::aws_account_id:role/aws-service-role/ecs.amazonaws.com/AWSServiceRoleForECS", "placementConstraints": [], "createdAt": 1510811361.128, "desiredCount": 2, "networkConfiguration": { "awsvpcConfiguration": { "subnets": [ "subnet-abcd1234" ], "securityGroups": [ "sg-abcd1234" ], "assignPublicIp": "DISABLED" } }, "platformVersion": "LATEST", "serviceName": "fargate-service", "clusterArn": "arn:aws:ecs:region:aws_account_id:cluster/fargate-cluster", "serviceArn": "arn:aws:ecs:region:aws_account_id:service/fargate-service", "deploymentConfiguration": { "maximumPercent": 200, "minimumHealthyPercent": 100 }, "deployments": [ { "status": "PRIMARY", "networkConfiguration": { "awsvpcConfiguration": { "subnets": [ "subnet-abcd1234" ], "securityGroups": [ "sg-abcd1234" ], "assignPublicIp": "DISABLED" } }, "pendingCount": 0, "launchType": "FARGATE", "createdAt": 1510811361.128, "desiredCount": 2, "taskDefinition": "arn:aws:ecs:region:aws_account_id:task-definition/sample-fargate:1", "updatedAt": 1510811361.128, "platformVersion": "0.0.1", "id": "ecs-svc/9223370526043414679", "runningCount": 0 } ], "events": [], "runningCount": 0, "placementStrategy": [] } }

Step 5: List Services

List the services for your cluster. You should see the service that you created in the previous section. You can take the service name or the full ARN that is returned from this command and use it to describe the service later.

aws ecs list-services --cluster fargate-cluster

Output:

{ "serviceArns": [ "arn:aws:ecs:region:aws_account_id:service/fargate-service" ] }

Step 6: Describe the Running Service

Describe the service using the service name retrieved earlier to get more information about the task.

aws ecs describe-services --cluster fargate-cluster --services fargate-service

Output:

{ "services": [ { "status": "ACTIVE", "taskDefinition": "arn:aws:ecs:region:aws_account_id:task-definition/sample-fargate:1", "pendingCount": 2, "launchType": "FARGATE", "loadBalancers": [], "roleArn": "arn:aws:iam::aws_account_id:role/aws-service-role/ecs.amazonaws.com/AWSServiceRoleForECS", "placementConstraints": [], "createdAt": 1510811361.128, "desiredCount": 2, "networkConfiguration": { "awsvpcConfiguration": { "subnets": [ "subnet-abcd1234" ], "securityGroups": [ "sg-abcd1234" ], "assignPublicIp": "DISABLED" } }, "platformVersion": "LATEST", "serviceName": "fargate-service", "clusterArn": "arn:aws:ecs:region:aws_account_id:cluster/fargate-cluster", "serviceArn": "arn:aws:ecs:region:aws_account_id:service/fargate-service", "deploymentConfiguration": { "maximumPercent": 200, "minimumHealthyPercent": 100 }, "deployments": [ { "status": "PRIMARY", "networkConfiguration": { "awsvpcConfiguration": { "subnets": [ "subnet-abcd1234" ], "securityGroups": [ "sg-abcd1234" ], "assignPublicIp": "DISABLED" } }, "pendingCount": 2, "launchType": "FARGATE", "createdAt": 1510811361.128, "desiredCount": 2, "taskDefinition": "arn:aws:ecs:region:aws_account_id:task-definition/sample-fargate:1", "updatedAt": 1510811361.128, "platformVersion": "0.0.1", "id": "ecs-svc/9223370526043414679", "runningCount": 0 } ], "events": [ { "message": "(service fargate-service) has started 2 tasks: (task 53c0de40-ea3b-489f-a352-623bf1235f08) (task d0aec985-901b-488f-9fb4-61b991b332a3).", "id": "92b8443e-67fb-4886-880c-07e73383ea83", "createdAt": 1510811841.408 }, { "message": "(service fargate-service) has started 2 tasks: (task b4911bee-7203-4113-99d4-e89ba457c626) (task cc5853e3-6e2d-4678-8312-74f8a7d76474).", "id": "d85c6ec6-a693-43b3-904a-a997e1fc844d", "createdAt": 1510811601.938 }, { "message": "(service fargate-service) has started 2 tasks: (task cba86182-52bf-42d7-9df8-b744699e6cfc) (task f4c1ad74-a5c6-4620-90cf-2aff118df5fc).", "id": "095703e1-0ca3-4379-a7c8-c0f1b8b95ace", "createdAt": 1510811364.691 } ], "runningCount": 0, "placementStrategy": [] } ], "failures": [] }