New users try 40+ cloud products for free, up to 12 months

 ✕

Deploy Docker Containers

on Amazon Elastic Container Service (Amazon ECS)

Amazon Elastic Container Service (Amazon ECS) is the service you use to run Docker applications on a scalable cluster. In this tutorial, you will learn how to run a Docker-enabled sample application on an Amazon ECS cluster behind a load balancer, test the sample application, and delete your resources to avoid charges.

Manage Your Amazon Web Services Resources

Step 1: Set up your first run with Amazon ECS

The Amazon ECS first run wizard will guide you through creating a cluster and launching a sample web application. In this step, you will enter the Amazon ECS console and launch the wizard.


a. Click here to open the Amazon ECS console first run wizard.

b. With Amazon ECS, you have the option to use Amazon Elastic Container Registry (Amazon ECR) to create an image repository and push an image to it as part of the first run wizard (see the screenshot to the right). This feature is currently available in select regions. 

  • If you do not have Amazon ECR options, skip to step 2.
  • If you have Amazon ECR options, uncheck the box next to Deploy a sample application onto an Amazon ECS Cluster and select Continue.
(click to zoom)

Step 2: Create a task definition

task definition is like a blueprint for your application. In this step, you will specify a task definition so Amazon ECS knows which Docker image to use for containers, how many containers to use in the task, and the resource allocation for each container.


The task definition comes pre-loaded with default configuration values.

  • Review the default values and select Next Step.

If you prefer to modify the configurations or would like to learn more, see Task Definition Parameters.

(click to zoom)

Step 3: Configure your service

Now that you have created a task definition, you will configure the Amazon ECS service. A service launches and maintains copies of the task definition in your cluster. For example, by running an application as a service, Amazon ECS will auto-recover any stopped tasks and maintain the number of copies you specify.


a. Configure service options:

  • Service Name: The default sample-webapp is a web-based "Hello World" application. It is meant to run indefinitely, so by running it as a service, it will restart if the task becomes unhealthy or unexpectedly stops.
  • Desired number of tasks: The default value of 1. This will create 1 copy of your task.
(click to zoom)

b. Elastic load balancing: You have the option to use a load balancer with your service. Amazon ECS can create an Elastic Load Balancing (ELB) load balancer to distribute the traffic across the container instances your task is launched on.

  • Container name: host port: select Simple-app:80.
  • The default values for ELB listener protocol, ELB listener port, and ELB health check are set up for the sample application. For more information on load balancing configuration, see Service Load Balancing.
(click to zoom)

c. Before you can attach a load balancer to an Amazon ECS service, you must create an Identity and Access Management (IAM) role for your services to use. This will allow Amazon ECS to make calls to the Amazon EC2 and Elastic Load Balancing APIs to register and deregister instances with your load balancers.

  • If you do not have a Service IAM Role already, Amazon ECS will create one named ecsServiceRole.
  • If you have an existing Amazon ECS service role, select it from the dropdown.
(click to zoom)

d. Review your settings and select Next Step.

(click to zoom)

Step 4: Configure your cluster

Your Amazon ECS tasks run on a cluster, which is the set of container instances running the Amazon ECS container agent. In this step, you will configure the cluster, review security settings, and set IAM roles.  


a. Follow the configuration settings below:

  • Cluster name: Enter sample-cluster.
  • EC2 instance type: The default t2.micro instance type. Instance types with more CPU and memory resources can handle more tasks. For more information on the different instance types, see Amazon EC2 Instance Types.
  • Number of instances: Leave the default value of 1 to launch one Amazon EC2 instance to launch into your cluster for tasks to be placed on. The more instances you have in your cluster, the more tasks you can place on them.  
  • Key pair: A key pair is required to SSH into your instances later on. You can continue by selecting None - unable to SSHselecting an existing key pair, or by creating one in the Amazon EC2 console. 
(click to zoom)

b. (Optional) Security Group: The default value (Anywhere) allows access from the entire Internet. You also have the option to choose a CIDR block that restricts access to your instances.

(click to zoom)

c. Container instance IAM role:

  • If you do not have an IAM role, the Amazon ECS wizard will create one for you.
  • If you have an existing container instance IAM role, select it from the dropdown list.
(click to zoom)

d. Select Review and Launch.

(click to zoom)

Step 5: Launch and view your resources

In previous steps, you have configured your task definition (which is like an application blueprint), the Amazon ECS service (which launches and maintains copies of your task definitions), and your cluster (which is the set of container instances running the container agent). In this step, you will review, launch, and view the resources you create.


a. You have a final chance to review your task definition, task configuration, and cluster configurations before launching.

  • Select Launch instance & run service
(click to zoom)

b. You are on a Launch Status page that shows the status of your launch and describes each step of the process. 

  • After the launch is complete, select View service.
(click to zoom)

Step 6: Open the Sample Application

In this step, you will verify that the sample application is up and running by pointing your browser to the load balancer DNS name.


a. On the sample-webapp page, click on your Load Balancer Name.

(click to zoom)

b. You will now test the sample application:

  • Copy the ELB DNS name.
  • Paste it into a new browser window.
  • Hit Enter on your keyboard to view the sample application (in this case, a static webpage).
(click to zoom)

Step 7: Delete Your Resources

Throughout this tutorial, you've launched three resources: an Amazon ECS cluster, an Amazon EC2 instance, and a load balancer. In this step, you will clean up all your resources to avoid unwanted charges.


a. Navigate back to the Amazon ECS console page 

  • Click on the cluster name (sample-cluster).
(click to zoom)

b. Select the checkbox next to sample-webapp and click Update.

(click to zoom)

c. To ensure you don't accidentally delete a service with active tasks, you need to stop all tasks before Amazon ECS will delete a service. 

  • Set the Number of tasks to 0 and select Update Service.
  • After you update your service, select Delete.
(click to zoom)

d. Delete the Amazon EC2 instances that were launched with your cluster:

  • Enter the Amazon EC2 console
  • In the left hand panel, select Instances.
  • Select the checkbox next to the instance named ECS Instance - EC2ContainerService-default.
  • Select Actions > Instance State > Terminate.
(click to zoom)

e. Delete your load balancers:

  • On the left panel, select Load Balancers.
  • Select the checkbox next to the load balancer you created for your service (it should start with EC2Contai-EcsElast). 
  • Right click and select Delete.
(click to zoom)

Congratulations!

Congratulations! You have learned how to configure, deploy, and delete your Docker-enabled application to Amazon Elastic Container Service (Amazon ECS). Amazon ECS is a highly scalable, high performance container management service that supports Docker containers and allows you to easily run applications on a managed cluster of Amazon EC2 instances.

Was this tutorial helpful?

Next Steps

Now that you have learned to deploy your Docker-enabled application to Amazon ECS, you can progress to the next tutorial where you will learn how to create a Docker Registry to store your container images. You’ll build a Docker image, push it to a repository and then use it to deploy an application on Amazon ECS.

Create a Docker Registry