Getting Started with Amazon ECS
Let's get started with Amazon EC2 Container Service (Amazon ECS) by creating a task definition, scheduling tasks, and configuring a cluster in the Amazon ECS console.
If you walk through the Amazon ECS first run wizard in a region that supports Amazon EC2 Container Registry (Amazon ECR), then you will optionally be able to create an Amazon ECR image repository and push an image to it. For more information on Amazon ECR, see the Amazon EC2 Container Registry User Guide.
Amazon ECR is available in the following regions:
|US East (N. Virginia)||us-east-1|
|US West (Oregon)||us-west-2|
The Amazon ECS first run wizard will guide you through the process to get started with Amazon ECS. The wizard gives you the option of creating a cluster and launching our sample web application, or if you already have a Docker image you would like to launch in Amazon ECS, you can create a task definition with that image and use that for your cluster instead.
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.
Choose your Amazon ECS first run wizard configuration options
Open the Amazon ECS console first run wizard at https://console.aws.amazon.com/ecs/home#/firstRun.
If your console is active in a region that supports Amazon ECR, then you are given the option to create an image repository and push an image to it as a part of the Amazon ECS first run wizard. If you do not see the options below, then you are not in a supported Amazon ECR region, and you can proceed to the next procedure, Create a task definition.
To create an Amazon ECS cluster and deploy a container application to it, check the top option. To create an Amazon ECR repository and push an image to it, which you can use in your Amazon ECS task definitions, check the bottom option. Choose Continue to proceed.
If you've chosen to create an Amazon ECR repository, then complete the next two sections of the first run wizard, Configure repository and Build, tag, and push Docker image . If you are not creating an Amazon ECR repository, skip ahead to Create a task definition.
A repository is a place that you store Docker images in Amazon ECR. Every time you push or pull an image from Amazon ECR, you specify the registry and repository location to tell Docker where to push the image to or where to pull it from.
For Repository name, enter a unique name for your repository and choose Next step.
Build, tag, and push Docker image
In this section of the wizard, you use the Docker CLI to tag an existing local image (that you have built from a Dockerfile or pulled from another registry, such as Docker Hub) and then push the tagged image to your Amazon ECR registry.
Retrieve the docker login command that you can use to authenticate your Docker client to your registry by pasting the aws ecr get-login command from the console into a terminal window.
The get-login command is available in the AWS CLI starting with version 1.9.15. You can check your AWS CLI version with the aws --version command.
Run the docker login command that was returned in the previous step. This command provides an authorization token that is valid for 12 hours.
When you execute this docker login command, the command string can be visible by other users on your system in a process list (ps -e) display. Because the docker login command contains authentication credentials, there is a risk that other users on your system could view them this way and use them to gain push and pull access to your repositories. If you are not on a secure system, you should consider this risk and log in interactively by omitting the
-poption, and then entering the password when prompted.
(Optional) If you have a Dockerfile for the image you want to push, build the image and tag it for your new repository by pasting the docker build command from the console into a terminal window (make sure you are in the same directory as your Dockerfile).
Tag the image for your Amazon ECR registry and your new repository by pasting the docker tag command from the console into a terminal window. The console command assumes that your image was built from a Dockerfile in the previous step; if you did not build your image from a Dockerfile, replace the first instance of
with the image ID or image name of your local image that you want to push.
Push the newly tagged image to your Amazon ECR repository by pasting the docker push command into a terminal window.
Choose Done to finish.
Create a task definition
A task definition is like a blue print for your application. Every time you launch a task in Amazon ECS, you specify a task definition so the service knows which Docker image to use for containers, how many containers to use in the task, and the resource allocation for each container.
Configure your task definition parameters.
The first run wizard comes preloaded with a task definition, and you can see the
simple-appcontainer defined in the image above. You can optionally rename the task definition or review and edit the resources used by the container (such as CPU units and memory) by choosing the container name and editing the values shown (CPU units are under the Advanced container configuration menu). Task definitions created in the first run wizard are limited to a single container for simplicity's sake. You can create multi-container task definitions later in the Amazon ECS console.
If you are using an Amazon ECR image in your task definition, be sure to use the full
registry/repository:tagnaming for your Amazon ECR images. For example,
For more information on what each of these task definition parameters does, see Task Definition Parameters.
Choose Next step to continue.
In this section of the wizard, you select how you would like to configure the Amazon ECS service that is created from your task definition. A service launches and maintains a specified number of copies of the task definition in your cluster. The Amazon ECS sample application is a web-based "Hello World" style application that is meant to run indefinitely, so by running it as a service, it will restart if the task becomes unhealthy or unexpectedly stops.
In the Service Name field, select a name for your service.
In the Desired number of tasks field, enter the number of tasks you would like to launch with your specified task definition.
If your task definition contains static port mappings, the number of container instances you launch in the next section of the wizard must be greater than or equal to the number of tasks specified here.
(Optional) You can choose to use an Elastic Load Balancing load balancer with your service. When a task is launched from a service that is configured to use a load balancer, the container instance that the task is launched on is registered with the load balancer and traffic from the load balancer is distributed across the instances in the load balancer.
Elastic Load Balancing load balancers do incur cost while they exist in your AWS resources. For more information on Elastic Load Balancing pricing, see Elastic Load Balancing Pricing.
Complete the following steps to use a load balancer with your service.
In the Elastic load balancing section, choose the Container name: host port menu, and then choose simple-app:80. The default values here are set up for the sample application, but you can configure different listener options for the load balancer. For more information, see Service Load Balancing.
In the Service IAM Role section, choose the Select IAM role for service menu, and then choose an existing Amazon ECS service (
ecsServiceRole) role that you have already created, or click Create new role to create the required IAM role for your service.
Review your load balancer settings and click Next Step.
In this section of the wizard, you name your cluster, and then configure the container instances that your tasks can be placed on, the address range that you can reach your instances and load balancer from, and the IAM roles to use with your container instances that let Amazon ECS take care of this configuration for you.
In the Cluster name field, choose a name for your cluster.
In the EC2 instance type field, choose the instance type to use for your container instances. Instance types with more CPU and memory resources can handle more tasks. For more information on the different instance types, see Amazon EC2 Instances.
In the Number of instances field, type the number of Amazon EC2 instances you want 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. Amazon EC2 instances incur costs while they exist in your AWS resources. For more information, see Amazon EC2 Pricing.
If you created a service with more than one desired task in it that exposes container ports on to container instance ports, such as the Amazon ECS sample application, you need to specify at least that many instances here.
Select a key pair name to use with your container instances. This is required for you to log into your instances with SSH; if you do not specify a key pair here, you cannot connect to your container instances with SSH. If you do not have a key pair, you can create one in the Amazon EC2 console at https://console.aws.amazon.com/ec2/.
(Optional) In the Security Group section, you can choose a CIDR block that restricts access to your instances. The default value (Anywhere)allows access from the entire Internet.
In the Container instance IAM role section, choose an existing Amazon ECS container instance (
ecsInstanceRole) role that you have already created, or choose Create new role to create the required IAM role for your container instances.
Click Review and Launch to proceed.
Review your task definition, task configuration, and cluster configurations and click Launch Instance & Run Service to finish. You are directed to a Launch Status page that shows the status of your launch and describes each step of the process (this can take a few minutes to complete while your Auto Scaling group is created and populated).
After the launch is complete, choose View service to view your service in the Amazon ECS console.