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

Amazon ECS CLI Tutorial

This simple tutorial shows a few of the different commands and capabilities of the Amazon ECS CLI. Before you can start this tutorial, you must install and configure the Amazon ECS CLI. For more information, see Installing the Amazon ECS CLI.

Step 1: Create your Cluster

The first action you should take is to create a cluster of Amazon ECS container instances that you can launch your containers on with the ecs-cli up command. There are many options that you can choose to configure your cluster with this command, but most of them are optional. In this example, you create a simple cluster of two t2.medium container instances that use the id_rsa key pair for SSH access (substitute your own key pair here).

By default, the security group created for your container instances opens port 80 for inbound traffic. You can use the --port option to specify a different port to open, or if you have more complicated security group requirements, you can specify an existing security group to use with the --security-group option.

Copy
ecs-cli up --keypair id_rsa --capability-iam --size 2 --instance-type t2.medium

Output:


INFO[0000] Created cluster                               cluster=ecs-cli-demo
INFO[0000] Waiting for your cluster resources to be created
INFO[0001] Cloudformation stack status                   stackStatus=CREATE_IN_PROGRESS
INFO[0061] Cloudformation stack status                   stackStatus=CREATE_IN_PROGRESS
INFO[0121] Cloudformation stack status                   stackStatus=CREATE_IN_PROGRESS
INFO[0182] Cloudformation stack status                   stackStatus=CREATE_IN_PROGRESS

This command may take a few minutes to complete as your resources are created. Now that you have a cluster, you can create a Docker compose file and deploy it.

Step 2: Create a Compose File

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

The following parameters are supported in compose files for the Amazon ECS CLI:

  • command

  • cpu_shares

  • dns

  • dns_search

  • entrypoint

  • environment: If an environment variable value is not specified in the compose file, but it exists in the shell environment, the shell environment variable value is passed to the task definition that is created for any associated tasks or services.

    Important

    We do not recommend using plaintext environment variables for sensitive information, such as credential data.

  • env_file

    Important

    We do not recommend using plaintext environment variables for sensitive information, such as credential data.

  • extra_hosts

  • hostname

  • image

  • labels

  • links

  • log_driver (Compose file version 1 only)

  • log_opt (Compose file version 1 only)

  • logging (Compose file version 2 only)

    • driver

    • options

  • mem_limit (in bytes)

  • mem_reservation (in bytes)

  • ports

  • privileged

  • read_only

  • security_opt

  • ulimits

  • user

  • volumes

  • volumes_from

  • working_dir

Important

The build directive is not supported at this time.

For more information about Docker compose file syntax, see the Compose file reference in the Docker documentation.

Here is the compose file, which you can call hello-world.yml. Each container has 100 CPU units and 500 MiB of memory. The wordpress container exposes port 80 to the container instance for inbound traffic to the web server.

Copy
version: '2' services: wordpress: image: wordpress cpu_shares: 100 mem_limit: 524288000 ports: - "80:80" links: - mysql mysql: image: mysql cpu_shares: 100 mem_limit: 524288000 environment: MYSQL_ROOT_PASSWORD: password

Step 3: Deploy the Compose File to a Cluster

After you create the compose file, you can deploy it to your cluster with the ecs-cli compose up command. By default, the command looks for a file called docker-compose.yml in the current directory, but you can specify a different file with the --file option. By default, the resources created by this command have the current directory in the title, but you can override that with the --project-name project_name option.

Copy
ecs-cli compose --file hello-world.yml up

Output:

INFO[0000] Using ECS task definition                     TaskDefinition=ecscompose-docker-compose:2
INFO[0000] Starting container...                         container=340488e0-a307-4322-b41c-99f1b70e97f9/wordpress
INFO[0000] Starting container...                         container=340488e0-a307-4322-b41c-99f1b70e97f9/mysql
INFO[0000] Describe ECS container status                 container=340488e0-a307-4322-b41c-99f1b70e97f9/wordpress desiredStatus=RUNNING lastStatus=PENDING taskDefinition=ecscompose-docker-compose:2
INFO[0000] Describe ECS container status                 container=340488e0-a307-4322-b41c-99f1b70e97f9/mysql desiredStatus=RUNNING lastStatus=PENDING taskDefinition=ecscompose-docker-compose:2
INFO[0054] Started container...                          container=340488e0-a307-4322-b41c-99f1b70e97f9/wordpress desiredStatus=RUNNING lastStatus=RUNNING taskDefinition=ecscompose-docker-compose:2
INFO[0054] Started container...                          container=340488e0-a307-4322-b41c-99f1b70e97f9/mysql desiredStatus=RUNNING lastStatus=RUNNING taskDefinition=ecscompose-docker-compose:2

Step 4: View the Running Containers on a Cluster

After you deploy the compose file, you can view the containers that are running on your cluster with the ecs-cli ps command.

Copy
ecs-cli ps

Output:

Name                                            State    Ports                     TaskDefinition
340488e0-a307-4322-b41c-99f1b70e97f9/wordpress  RUNNING  52.89.204.137:80->80/tcp  ecscompose-docker-compose:2
340488e0-a307-4322-b41c-99f1b70e97f9/mysql      RUNNING                            ecscompose-docker-compose:2

In the above example, you can see the wordpress and mysql containers from your compose file, and also the IP address and port of the web server. If you point a web browser to that address, you should see the WordPress installation wizard.

Step 5: Scale the Tasks on a Cluster

You can scale your task count up so you could have more instances of your application with the ecs-cli compose scale command. In this example, you can increase the count of your application to two.

Copy
ecs-cli compose --file hello-world.yml scale 2

Now you should see two more containers in your cluster.

Copy
ecs-cli ps

Output:

Name                                            State    Ports                     TaskDefinition
340488e0-a307-4322-b41c-99f1b70e97f9/wordpress  RUNNING  52.89.204.137:80->80/tcp  ecscompose-docker-compose:2
340488e0-a307-4322-b41c-99f1b70e97f9/mysql      RUNNING                            ecscompose-docker-compose:2
f80d82d5-3724-4f2f-86b1-5ee5891ce995/mysql      RUNNING                            ecscompose-docker-compose:2
f80d82d5-3724-4f2f-86b1-5ee5891ce995/wordpress  RUNNING  52.89.205.89:80->80/tcp   ecscompose-docker-compose:2

Step 6: Create an ECS Service from a Compose File

Now that you know that your containers work properly, you can make sure that they are replaced if they fail or stop. You can do this by creating a service from your compose file with the ecs-cli compose service up command. This command creates a task definition from the latest compose file (if it does not already exist) and creates an ECS service with it, with a desired count of 1.

Before starting your service, stop the containers from your compose file with the ecs-cli compose down command so that you have an empty cluster to work with.

Copy
ecs-cli compose --file hello-world.yml down

Output:

INFO[0000] Stopping container...                         container=340488e0-a307-4322-b41c-99f1b70e97f9/wordpress
INFO[0000] Stopping container...                         container=340488e0-a307-4322-b41c-99f1b70e97f9/mysql
INFO[0000] Stopping container...                         container=f80d82d5-3724-4f2f-86b1-5ee5891ce995/mysql
INFO[0000] Stopping container...                         container=f80d82d5-3724-4f2f-86b1-5ee5891ce995/wordpress
INFO[0000] Describe ECS container status                 container=f80d82d5-3724-4f2f-86b1-5ee5891ce995/mysql desiredStatus=STOPPED lastStatus=RUNNING taskDefinition=ecscompose-docker-compose:2
INFO[0000] Describe ECS container status                 container=f80d82d5-3724-4f2f-86b1-5ee5891ce995/wordpress desiredStatus=STOPPED lastStatus=RUNNING taskDefinition=ecscompose-docker-compose:2
INFO[0000] Describe ECS container status                 container=340488e0-a307-4322-b41c-99f1b70e97f9/wordpress desiredStatus=STOPPED lastStatus=RUNNING taskDefinition=ecscompose-docker-compose:2
INFO[0000] Describe ECS container status                 container=340488e0-a307-4322-b41c-99f1b70e97f9/mysql desiredStatus=STOPPED lastStatus=RUNNING taskDefinition=ecscompose-docker-compose:2
INFO[0006] Stopped container...                          container=340488e0-a307-4322-b41c-99f1b70e97f9/wordpress desiredStatus=STOPPED lastStatus=STOPPED taskDefinition=ecscompose-docker-compose:2
INFO[0006] Stopped container...                          container=340488e0-a307-4322-b41c-99f1b70e97f9/mysql desiredStatus=STOPPED lastStatus=STOPPED taskDefinition=ecscompose-docker-compose:2
INFO[0006] Stopped container...                          container=f80d82d5-3724-4f2f-86b1-5ee5891ce995/mysql desiredStatus=STOPPED lastStatus=STOPPED taskDefinition=ecscompose-docker-compose:2
INFO[0006] Stopped container...                          container=f80d82d5-3724-4f2f-86b1-5ee5891ce995/wordpress desiredStatus=STOPPED lastStatus=STOPPED taskDefinition=ecscompose-docker-compose:2

Now you can create your service.

Copy
ecs-cli compose --file hello-world.yml service up

Output:

INFO[0000] Using ECS task definition                     TaskDefinition=ecscompose-docker-compose:2
INFO[0000] Created an ECS Service                        serviceName=ecscompose-service-docker-compose taskDefinition=ecscompose-docker-compose:2
INFO[0000] Updated ECS service successfully              desiredCount=1 serviceName=ecscompose-service-docker-compose
INFO[0000] Describe ECS Service status                   desiredCount=1 runningCount=0 serviceName=ecscompose-service-docker-compose
INFO[0015] ECS Service has reached a stable state        desiredCount=1 runningCount=1 serviceName=ecscompose-service-docker-compose

Step 7: 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.

Copy
ecs-cli compose --file hello-world.yml service rm

Output:

INFO[0000] Updated ECS service successfully              desiredCount=0 serviceName=ecscompose-service-docker-compose
INFO[0000] Describe ECS Service status                   desiredCount=0 runningCount=1 serviceName=ecscompose-service-docker-compose
INFO[0015] ECS Service has reached a stable state        desiredCount=0 runningCount=0 serviceName=ecscompose-service-docker-compose
INFO[0015] Deleted ECS service                           service=ecscompose-service-docker-compose
INFO[0015] ECS Service has reached a stable state        desiredCount=0 runningCount=0 serviceName=ecscompose-service-docker-compose

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

Copy
ecs-cli down --force

Output:

INFO[0000] Waiting for your cluster resources to be deleted
INFO[0000] Cloudformation stack status                   stackStatus=DELETE_IN_PROGRESS
INFO[0061] Cloudformation stack status                   stackStatus=DELETE_IN_PROGRESS
INFO[0121] Deleted cluster                               cluster=ecs-cli-demo