Amazon EC2 Container Service Developer Guide AWS

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 321 [warning: Documents this large are best viewed by clicking the View PDF Link!]

Amazon EC2 Container Service
Developer Guide
API Version 2014-11-13
Amazon EC2 Container Service Developer Guide
Amazon EC2 Container Service: Developer Guide
Copyright © 2017 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner
that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not
owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by
Amazon.
Amazon EC2 Container Service Developer Guide
Table of Contents
What is Amazon ECS? ......................................................................................................................... 1
Features of Amazon ECS ............................................................................................................. 1
Containers and Images ....................................................................................................... 3
Task Definitions ................................................................................................................. 3
Tasks and Scheduling ......................................................................................................... 4
Clusters ............................................................................................................................. 4
Container Agent ................................................................................................................. 4
How to Get Started with Amazon ECS .......................................................................................... 5
Related Services ......................................................................................................................... 5
Accessing Amazon ECS ................................................................................................................ 6
Pricing ...................................................................................................................................... 7
Setting Up ........................................................................................................................................ 8
Sign Up for AWS ........................................................................................................................ 8
Create an IAM User .................................................................................................................... 9
Create an IAM Role for your Container Instances and Services ........................................................ 10
Create a Key Pair ..................................................................................................................... 10
(Optional) Install the Amazon ECS Command Line Interface (CLI) .................................................... 12
Docker Basics ................................................................................................................................... 13
Installing Docker ...................................................................................................................... 13
(Optional) Sign up for a Docker Hub Account ............................................................................... 14
(Optional) Amazon EC2 Container Registry .................................................................................. 14
Create a Docker Image and Upload it to Docker Hub .................................................................... 15
Next Steps ............................................................................................................................... 17
Getting Started ................................................................................................................................ 20
Cleaning Up ..................................................................................................................................... 24
Scale Down Services ................................................................................................................. 24
Delete Services ........................................................................................................................ 25
Deregister Container Instances ................................................................................................... 25
Delete a Cluster ....................................................................................................................... 25
Delete the AWS CloudFormation Stack ........................................................................................ 26
Clusters ........................................................................................................................................... 27
Cluster Concepts ...................................................................................................................... 27
Creating a Cluster .................................................................................................................... 27
Scaling a Cluster ...................................................................................................................... 29
Deleting a Cluster .................................................................................................................... 30
Container Instances .......................................................................................................................... 32
Container Instance Concepts ...................................................................................................... 32
Container Instance Lifecycle ....................................................................................................... 33
Check the Instance Role for Your Account ................................................................................... 34
Container Instance AMIs ............................................................................................................ 34
Amazon ECS-Optimized AMI .............................................................................................. 34
Launching a Container Instance .................................................................................................. 42
Bootstrap Container Instances .................................................................................................... 45
Amazon ECS Container Agent ............................................................................................ 46
Docker Daemon ............................................................................................................... 46
cloud-init-per Utility ........................................................................................................ 46
MIME Multi Part Archive .................................................................................................... 47
Example User Data Scripts ................................................................................................. 48
Connect to Your Container Instance ............................................................................................ 51
CloudWatch Logs ..................................................................................................................... 52
CloudWatch Logs IAM Policy .............................................................................................. 52
Installing the CloudWatch Logs Agent ................................................................................. 53
Configuring and Starting the CloudWatch Logs Agent ........................................................... 53
Viewing CloudWatch Logs ................................................................................................. 56
API Version 2014-11-13
iii
Amazon EC2 Container Service Developer Guide
Configuring CloudWatch Logs at Launch with User Data ........................................................ 57
Container Instance Draining ....................................................................................................... 59
Draining Instances ............................................................................................................ 59
Managing Container Instances Remotely ..................................................................................... 60
Run Command IAM Policy ................................................................................................. 60
Installing the SSM Agent on the Amazon ECS-optimized AMI ................................................. 61
Using Run Command ........................................................................................................ 61
Starting a Task at Container Instance Launch Time ....................................................................... 63
Deregister Container Instance .................................................................................................... 65
Container Agent ............................................................................................................................... 68
Installing the Amazon ECS Container Agent ................................................................................. 68
Container Agent Versions .......................................................................................................... 71
Amazon ECS-Optimized AMI Container Agent Versions .......................................................... 72
Updating the Amazon ECS Container Agent ................................................................................. 73
Checking Your Amazon ECS Container Agent Version ............................................................ 73
Updating the Amazon ECS Container Agent on the Amazon ECS-Optimized AMI ....................... 75
Manually Updating the Amazon ECS Container Agent (for Non-Amazon ECS-optimized AMIs) ...... 77
Amazon ECS Container Agent Configuration ................................................................................ 79
Available Parameters ........................................................................................................ 80
Storing Container Instance Configuration in Amazon S3 ........................................................ 84
Automated Task and Image Cleanup ........................................................................................... 85
Tunable Parameters .......................................................................................................... 86
Cleanup Workflow ............................................................................................................ 86
Private Registry Authentication .................................................................................................. 86
Authentication Formats ..................................................................................................... 87
Enabling Private Registries ................................................................................................ 88
Amazon ECS Container Agent Introspection ................................................................................. 90
HTTP Proxy Configuration ......................................................................................................... 91
Task Definitions ................................................................................................................................ 93
Application Architecture ............................................................................................................ 94
Creating a Task Definition ......................................................................................................... 95
Task Definition Template ................................................................................................... 96
Task Definition Parameters ........................................................................................................ 98
Family ............................................................................................................................. 98
Task Role ........................................................................................................................ 98
Network Mode ................................................................................................................. 99
Container Definitions ........................................................................................................ 99
Task Placement Constraints ............................................................................................. 111
Volumes ........................................................................................................................ 111
Using Data Volumes in Tasks ................................................................................................... 112
Using the awslogs Log Driver ................................................................................................... 117
Enabling the awslogs Log Driver on your Container Instances ............................................... 117
Creating Your Log Groups ................................................................................................ 117
Available awslogs Log Driver Options ................................................................................ 118
Specifying a Log Configuration in your Task Definition ........................................................ 119
Viewing awslogs Container Logs in CloudWatch Logs .......................................................... 120
Example Task Definitions ......................................................................................................... 122
WordPress and MySQL .................................................................................................... 122
awslogs Log Driver ......................................................................................................... 123
Amazon ECR Image and Task Definition IAM Role ............................................................... 124
Entrypoint with Command ............................................................................................... 124
Updating a Task Definition ...................................................................................................... 125
Deregistering Task Definitions .................................................................................................. 125
Scheduling Tasks ............................................................................................................................ 126
Running Tasks ........................................................................................................................ 127
Task Placement ...................................................................................................................... 128
Task Placement Strategies ............................................................................................... 129
API Version 2014-11-13
iv
Amazon EC2 Container Service Developer Guide
Task Placement Constraints ............................................................................................. 130
Cluster Query Language .................................................................................................. 134
Task Life Cycle ....................................................................................................................... 136
Services ......................................................................................................................................... 138
Service Concepts .................................................................................................................... 138
Service Definition Parameters .................................................................................................. 139
Service Load Balancing ............................................................................................................ 141
Load Balancing Concepts ................................................................................................. 144
Check the Service Role for your Account ........................................................................... 144
Creating a Load Balancer ................................................................................................. 145
Service Auto Scaling ............................................................................................................... 152
Service Auto Scaling Required IAM Permissions .................................................................. 153
Service Auto Scaling Concepts ......................................................................................... 153
Amazon ECS Console Experience ...................................................................................... 154
AWS CLI and SDK Experience ........................................................................................... 154
Tutorial: Service Auto Scaling ........................................................................................... 154
Creating a Service ................................................................................................................... 160
Configuring Basic Service Parameters ................................................................................ 160
(Optional) Configuring Your Service to Use a Load Balancer ................................................. 161
(Optional) Configuring Your Service to Use Service Auto Scaling ........................................... 163
Review and Create Your Service ....................................................................................... 165
Updating a Service ................................................................................................................. 165
Deleting a Service .................................................................................................................. 166
Repositories ................................................................................................................................... 168
Using Amazon ECR Images with Amazon ECS ............................................................................. 169
Monitoring ..................................................................................................................................... 170
Monitoring Tools .................................................................................................................... 171
Automated Tools ............................................................................................................ 171
Manual Tools ................................................................................................................. 171
CloudWatch Metrics ................................................................................................................ 172
Enabling CloudWatch Metrics ........................................................................................... 172
Available Metrics and Dimensions ..................................................................................... 172
Cluster Reservation ......................................................................................................... 175
Cluster Utilization ........................................................................................................... 176
Service Utilization ........................................................................................................... 177
Service RUNNING Task Count ............................................................................................. 177
Viewing Amazon ECS Metrics ........................................................................................... 178
Tutorial: Scaling with CloudWatch Alarms .......................................................................... 182
CloudWatch Events ................................................................................................................. 187
Amazon ECS Events ........................................................................................................ 187
Handling Events ............................................................................................................. 192
Tutorial: Listening for Amazon ECS CloudWatch Events ....................................................... 194
Tutorial: Sending Amazon Simple Notification Service Alerts for Task Stopped Events .............. 195
IAM Policies, Roles, and Permissions ................................................................................................. 198
Policy Structure ...................................................................................................................... 199
Policy Syntax ................................................................................................................. 199
Actions for Amazon ECS .................................................................................................. 200
Amazon Resource Names for Amazon ECS ......................................................................... 200
Condition Keys for Amazon ECS ....................................................................................... 201
Testing Permissions ........................................................................................................ 202
Supported Resource-Level Permissions ...................................................................................... 203
Creating IAM Policies .............................................................................................................. 205
Managed Policies .................................................................................................................... 205
Amazon ECS Managed Policies ......................................................................................... 206
Amazon ECR Managed Policies ......................................................................................... 208
Amazon ECS Container Instance IAM Role .................................................................................. 210
Adding Amazon S3 Read-only Access to your Container Instance Role .................................... 212
API Version 2014-11-13
v
Amazon EC2 Container Service Developer Guide
Amazon ECS Service Scheduler IAM Role ................................................................................... 212
Amazon ECS Service Auto Scaling IAM Role ............................................................................... 214
Amazon EC2 Container Service Task Role ................................................................................ 215
IAM Roles for Tasks ................................................................................................................ 216
Benefits of Using IAM Roles for Tasks ............................................................................... 217
Enabling Task IAM Roles on your Container Instances .......................................................... 217
Creating an IAM Role and Policy for your Tasks .................................................................. 218
Using a Supported AWS SDK ........................................................................................... 219
Specifying an IAM Role for your Tasks ............................................................................... 219
Amazon ECS IAM Policy Examples ............................................................................................ 220
Amazon ECS First Run Wizard .......................................................................................... 220
Clusters ......................................................................................................................... 222
Container Instances ......................................................................................................... 223
Task Definitions .............................................................................................................. 224
Run Tasks ...................................................................................................................... 225
Start Tasks ..................................................................................................................... 225
List and Describe Tasks ................................................................................................... 226
Create Services ............................................................................................................... 226
Update Services ............................................................................................................. 227
Using the ECS CLI ........................................................................................................................... 228
Installing the Amazon ECS CLI ................................................................................................. 228
Configuring the Amazon ECS CLI .............................................................................................. 229
Amazon ECS CLI Tutorial ......................................................................................................... 230
Step 1: Create your Cluster .............................................................................................. 230
Step 2: Create a Compose File ......................................................................................... 231
Step 3: Deploy the Compose File to a Cluster ..................................................................... 232
Step 4: View the Running Containers on a Cluster .............................................................. 232
Step 5: Scale the Tasks on a Cluster ................................................................................. 233
Step 6: Create an ECS Service from a Compose File ............................................................ 233
Step 7: Clean Up ............................................................................................................ 234
Amazon ECS Command Line Reference ..................................................................................... 235
ecs-cli ........................................................................................................................... 235
ecs-cli configure ............................................................................................................. 237
ecs-cli up ....................................................................................................................... 240
ecs-cli down ................................................................................................................... 243
ecs-cli scale ................................................................................................................... 244
ecs-cli ps ....................................................................................................................... 244
ecs-cli push .................................................................................................................... 245
ecs-cli pull ..................................................................................................................... 246
ecs-cli images ................................................................................................................ 247
ecs-cli license ................................................................................................................. 249
ecs-cli compose .............................................................................................................. 250
ecs-cli compose service ................................................................................................... 252
Using the AWS CLI ......................................................................................................................... 259
Step 1: (Optional) Create a Cluster ........................................................................................... 259
Step 2: Launch an Instance with the Amazon ECS AMI ................................................................. 260
Step 3: List Container Instances ................................................................................................ 261
Step 4: Describe your Container Instance ................................................................................... 261
Step 5: Register a Task Definition ............................................................................................. 263
Step 6: List Task Definitions ..................................................................................................... 264
Step 7: Run a Task ................................................................................................................. 265
Step 8: List Tasks ................................................................................................................... 265
Step 9: Describe the Running Task ............................................................................................ 266
Common Use Cases ........................................................................................................................ 267
Microservices .......................................................................................................................... 267
Auto Scaling .................................................................................................................. 268
Service Discovery ............................................................................................................ 268
API Version 2014-11-13
vi
Amazon EC2 Container Service Developer Guide
Authorization and Secrets Management ............................................................................ 268
Logging ......................................................................................................................... 268
Continuous Integration and Continuous Deployment ........................................................... 269
Batch Jobs ............................................................................................................................. 269
Service Limits ................................................................................................................................. 270
CloudTrail Logging .......................................................................................................................... 271
Amazon ECS Information in CloudTrail ...................................................................................... 271
Understanding Amazon ECS Log File Entries .............................................................................. 272
Troubleshooting ............................................................................................................................. 273
Checking Stopped Tasks for Errors ............................................................................................ 273
Service Event Messages ........................................................................................................... 275
CannotCreateContainerError: API error (500): devmapper ..................................................... 277
Troubleshooting Service Load Balancers .................................................................................... 278
Enabling Docker Debug Output ................................................................................................ 280
Amazon ECS Log File Locations ................................................................................................ 281
Amazon ECS Container Agent Log .................................................................................... 281
Amazon ECS ecs-init Log .............................................................................................. 281
IAM Roles for Tasks Credential Audit Log ........................................................................... 281
Amazon ECS Logs Collector ..................................................................................................... 282
Agent Introspection Diagnostics ............................................................................................... 283
Docker Diagnostics ................................................................................................................. 284
List Docker Containers .................................................................................................... 284
View Docker Logs ........................................................................................................... 285
Inspect Docker Containers ............................................................................................... 285
API failures Error Messages ................................................................................................... 286
Windows Containers (Beta) .............................................................................................................. 288
Windows Container Caveats ..................................................................................................... 288
Windows Containers AWS CloudFormation Template ................................................................... 289
Getting Started with Windows Containers ................................................................................. 302
Step 1: Create a Windows Cluster ..................................................................................... 302
Step 2: Launching a Windows Container Instance into your Cluster ........................................ 302
Step 3: Register a Windows Task Definition ........................................................................ 305
Step 4: Create a Service with Your Task Definition .............................................................. 307
Step 5: View Your Service ................................................................................................ 307
Windows Task Definitions ........................................................................................................ 308
Windows Task Definition Parameters ................................................................................. 308
Windows Sample Task Definitions ..................................................................................... 311
Windows IAM Roles for Tasks ................................................................................................... 311
IAM Roles for Task Container Bootstrap Script .................................................................... 312
Pushing Windows Images to Amazon ECR .................................................................................. 312
AWS Glossary ................................................................................................................................. 314
API Version 2014-11-13
vii
Amazon EC2 Container Service Developer Guide
Features of Amazon ECS
What is Amazon EC2 Container
Service?
Amazon EC2 Container Service (Amazon ECS) is a highly scalable, fast, container management service
that makes it easy to run, stop, and manage Docker containers on a cluster of Amazon Elastic Compute
Cloud (Amazon EC2) instances. Amazon ECS lets you launch and stop container-based applications with
simple API calls, allows you to get the state of your cluster from a centralized service, and gives you
access to many familiar Amazon EC2 features.
You can use Amazon ECS to schedule the placement of containers across your cluster based on your
resource needs, isolation policies, and availability requirements. Amazon ECS eliminates the need for
you to operate your own cluster management and configuration management systems or worry about
scaling your management infrastructure.
Amazon ECS can be used to create a consistent deployment and build experience, manage and scale
batch and Extract-Transform-Load (ETL) workloads, and build sophisticated application architectures on
a microservices model. For more information about Amazon ECS use cases and scenarios, see Container
Use Cases.
AWS Elastic Beanstalk can also be used to rapidly develop, test, and deploy Docker containers in
conjunction with other components of your application infrastructure; however, using Amazon ECS
directly provides more fine-grained control and access to a wider set of use cases. For more information,
see the AWS Elastic Beanstalk Developer Guide.
Features of Amazon ECS
Amazon ECS is a regional service that simplifies running application containers in a highly available
manner across multiple Availability Zones within a region. You can create Amazon ECS clusters within a
new or existing VPC. After a cluster is up and running, you can define task definitions and services that
specify which Docker container images to run across your clusters. Container images are stored in and
pulled from container registries, which may exist within or outside of your AWS infrastructure.
API Version 2014-11-13
1
Amazon EC2 Container Service Developer Guide
Features of Amazon ECS
API Version 2014-11-13
2
Amazon EC2 Container Service Developer Guide
Containers and Images
The following sections dive into these individual elements of the Amazon ECS architecture in more
detail.
Containers and Images
To deploy applications on Amazon ECS, your application components must be architected to run in
containers. A Docker container is a standardized unit of software development, containing everything
that your software application needs to run: code, runtime, system tools, system libraries, etc. Containers
are created from a read-only template called an image.
Images are typically built from a Dockerfile, a plain text file that specifies all of the components that are
included in the container. These images are then stored in a registry from which they can be downloaded
and run on your container instances. For more information about container technology, see Docker
Basics (p. 13).
Task Definitions
To prepare your application to run on Amazon ECS, you create a task definition. The task definition
is a text file in JSON format that describes one or more containers that form your application. It can
be thought of as a blueprint for your application. Task definitions specify various parameters for your
application, such as which containers to use and the repositories in which they are located, which ports
should be opened on the container instance for your application, and what data volumes should be used
with the containers in the task. For more information about creating task definitions, see Amazon ECS
Task Definitions (p. 93).
The following is an example of a simple task definition containing a single container that runs an
Nginx web server. For a more extended example demonstrating the use of multiple containers in a task
definition, see Example Task Definitions (p. 122).
{
"family": "webserver",
"containerDefinitions": [
{
"name": "web",
"image": "nginx",
"cpu": 99,
"memory": 100,
"portMappings": [{
"containerPort": 80,
API Version 2014-11-13
3
Amazon EC2 Container Service Developer Guide
Tasks and Scheduling
"hostPort": 80
}]
}]
}
Tasks and Scheduling
A task is the instantiation of a task definition on a container instance within your cluster. After you have
created a task definition for your application within Amazon ECS, you can specify the number of tasks
that will run on your cluster.
The Amazon ECS task scheduler is responsible for placing tasks on container instances. There are several
different scheduling options available. For example, you can define a service that runs and maintains a
specified number of tasks simultaneously. For more information about the different scheduling options
available, see Scheduling Amazon ECS Tasks (p. 126).
Clusters
When you run tasks using Amazon ECS, you place them on a cluster, which is a logical grouping of EC2
instances. Amazon ECS downloads your container images from a registry that you specify, and runs those
images on the container instances within your cluster.
For more information about creating clusters, see Amazon ECS Clusters (p. 27). For more information
about creating container instances, see Amazon ECS Container Instances (p. 32).
Container Agent
The container agent runs on each instance within an Amazon ECS cluster. It sends information about
the instance's current running tasks and resource utilization to Amazon ECS, and starts and stops tasks
whenever it receives a request from Amazon ECS. For more information, see Amazon ECS Container
Agent (p. 68).
API Version 2014-11-13
4
Amazon EC2 Container Service Developer Guide
How to Get Started with Amazon ECS
How to Get Started with Amazon ECS
If you are using Amazon ECS for the first time, the AWS Management Console for Amazon ECS provides a
first-run wizard that steps you through defining a task definition for a web server, configuring a service,
and launching your first cluster. The first-run wizard is highly recommended for users who have no prior
experience with Amazon ECS. For more information, see the Getting Started with Amazon ECS (p. 20)
tutorial.
Alternatively, you can install the AWS Command Line Interface (AWS CLI) to use Amazon ECS. For more
information, see Setting Up with Amazon ECS (p. 8).
Related Services
Amazon ECS can be used in conjunction with the following AWS services:
AWS Identity and Access Management
IAM is a web service that helps you securely control access to AWS resources for your users. Use
IAM to control who can use your AWS resources (authentication) and what resources they can use
in which ways (authorization). In Amazon ECS, IAM can be used to control access at the container
instance level using IAM roles, and at the task level using IAM task roles. For more information, see
Amazon ECS IAM Policies, Roles, and Permissions (p. 198).
Auto Scaling
Auto Scaling is a web service that enables you to automatically launch or terminate EC2 instances
based on user-defined policies, health status checks, and schedules. You can use Auto Scaling to
API Version 2014-11-13
5
Amazon EC2 Container Service Developer Guide
Accessing Amazon ECS
scale out and scale in the container instances within a cluster in response to a number of metrics. For
more information, see Tutorial: Scaling Container Instances with CloudWatch Alarms (p. 182).
Elastic Load Balancing
Elastic Load Balancing automatically distributes incoming application traffic across multiple
EC2 instances in the cloud. It enables you to achieve greater levels of fault tolerance in your
applications, seamlessly providing the required amount of load balancing capacity needed to
distribute application traffic. You can use Elastic Load Balancing to create an endpoint that balances
traffic across services in a cluster. For more information, see Service Load Balancing (p. 141).
Amazon EC2 Container Registry
Amazon ECR is a managed AWS Docker registry service that is secure, scalable, and reliable. Amazon
ECR supports private Docker repositories with resource-based permissions using IAM so that specific
users or EC2 instances can access repositories and images. Developers can use the Docker CLI to
push, pull, and manage images. For more information, see the Amazon EC2 Container Registry User
Guide.
AWS CloudFormation
AWS CloudFormation gives developers and systems administrators an easy way to create and
manage a collection of related AWS resources, provisioning and updating them in an orderly and
predictable fashion. You can define clusters, task definitions, and services as entities in an AWS
CloudFormation script. For more information, see AWS CloudFormation Template Reference.
Accessing Amazon ECS
You can work with Amazon ECS in any of the following ways:
AWS Management Console
The console is a browser-based interface to manage Amazon ECS resources. For a tutorial that
guides you through the console, see Getting Started with Amazon ECS (p. 20).
AWS command line tools
You can use the AWS command line tools to issue commands at your system's command line to
perform Amazon ECS and AWS tasks; this can be faster and more convenient than using the console.
The command line tools are also useful for building scripts that perform AWS tasks.
AWS provides two sets of command line tools: the AWS Command Line Interface (AWS CLI) and the
AWS Tools for Windows PowerShell. For more information, see the AWS Command Line Interface
User Guide and the AWS Tools for Windows PowerShell User Guide.
Amazon ECS CLI
In addition to using the AWS CLI to access Amazon ECS resources, you can use the Amazon ECS CLI,
which provides high-level commands to simplify creating, updating, and monitoring clusters and
tasks from a local development environment using Docker Compose. For more information, see
Using the Amazon ECS Command Line Interface (p. 228).
AWS SDKs
We also provide SDKs that enable you to access Amazon ECS from a variety of programming
languages. The SDKs automatically take care of tasks such as:
• Cryptographically signing your service requests
• Retrying requests
• Handling error responses
For more information about available SDKs, see Tools for Amazon Web Services.
API Version 2014-11-13
6
Amazon EC2 Container Service Developer Guide
Pricing
Pricing
There is no additional charge for using Amazon ECS beyond the underlying AWS resources used to host
your applications. For more information, see Amazon EC2 Container Service Pricing.
API Version 2014-11-13
7
Amazon EC2 Container Service Developer Guide
Sign Up for AWS
Setting Up with Amazon ECS
If you've already signed up for Amazon Web Services (AWS) and have been using Amazon Elastic
Compute Cloud (Amazon EC2), you are close to being able to use Amazon ECS. The set up process for
the two services is very similar, as Amazon ECS uses EC2 instances in the clusters. The following guide
prepares you for launching your first cluster using either the Amazon ECS first-run wizard or the Amazon
ECS Command Line Interface (CLI).
Note
Because Amazon ECS uses many components of Amazon EC2, you use the Amazon EC2 console
for many of these steps.
Complete the following tasks to get set up for Amazon ECS. If you have already completed any of these
steps, you may skip them and move on to installing the custom AWS CLI.
1. Sign Up for AWS (p. 8)
2. Create an IAM User (p. 9)
3. Create an IAM Role for your Container Instances and Services (p. 10)
4. Create a Key Pair (p. 10)
5. (Optional) Install the Amazon ECS Command Line Interface (CLI) (p. 12)
Sign Up for AWS
When you sign up for AWS, your AWS account is automatically signed up for all services, including
Amazon EC2 and Amazon ECS. You are charged only for the services that you use.
If you have an AWS account already, skip to the next task. If you don't have an AWS account, use the
following procedure to create one.
To create an AWS account
1. Open https://aws.amazon.com/, and then choose Create an AWS Account.
2. Follow the online instructions.
Part of the sign-up procedure involves receiving a phone call and entering a PIN using the phone
keypad.
Note your AWS account number, because you'll need it for the next task.
API Version 2014-11-13
8
Amazon EC2 Container Service Developer Guide
Create an IAM User
Create an IAM User
Services in AWS, such as Amazon EC2 and Amazon ECS, require that you provide credentials when you
access them, so that the service can determine whether you have permission to access its resources. The
console requires your password. You can create access keys for your AWS account to access the command
line interface or API. However, we don't recommend that you access AWS using the credentials for your
AWS account; we recommend that you use AWS Identity and Access Management (IAM) instead. Create
an IAM user, and then add the user to an IAM group with administrative permissions or and grant this
user administrative permissions. You can then access AWS using a special URL and the credentials for the
IAM user.
If you signed up for AWS but have not created an IAM user for yourself, you can create one using the IAM
console.
To create an IAM user for yourself and add the user to an Administrators group
1. Sign in to the IAM console at https://console.aws.amazon.com/iam/.
2. In the navigation pane, choose Users, and then choose Add user.
3. For User name, type a user name, such as Administrator. The name can consist of letters, digits,
and the following characters: plus (+), equal (=), comma (,), period (.), at (@), underscore (_), and
hyphen (-). The name is not case sensitive and can be a maximum of 64 characters in length.
4. Select the check box next to AWS Management Console access, select Custom password, and then
type the new user's password in the text box. You can optionally select Require password reset to
force the user to select a new password the next time the user signs in.
5. Choose Next: Permissions.
6. On the Set permissions for user page, choose Add user to group.
7. Choose Create group.
8. In the Create group dialog box, type the name for the new group. The name can consist of letters,
digits, and the following characters: plus (+), equal (=), comma (,), period (.), at (@), underscore (_),
and hyphen (-). The name is not case sensitive and can be a maximum of 128 characters in length.
9. For Filter, choose Job function.
10. In the policy list, select the check box for AdministratorAccess. Then choose Create group.
11. Back in the list of groups, select the check box for your new group. Choose Refresh if necessary to
see the group in the list.
12. Choose Next: Review to see the list of group memberships to be added to the new user. When you
are ready to proceed, choose Create user.
You can use this same process to create more groups and users, and to give your users access to your
AWS account resources. To learn about using policies to restrict users' permissions to specific AWS
resources, go to Access Management and Example Policies for Administering AWS Resources.
To sign in as this new IAM user, sign out of the AWS console, then use the following URL, where
your_aws_account_id is your AWS account number without the hyphens (for example, if your AWS
account number is 1234-5678-9012, your AWS account ID is 123456789012):
https://your_aws_account_id.signin.aws.amazon.com/console/
Enter the IAM user name and password that you just created. When you're signed in, the navigation bar
displays "your_user_name @ your_aws_account_id".
If you don't want the URL for your sign-in page to contain your AWS account ID, you can create an
account alias. From the IAM dashboard, choose Create Account Alias and enter an alias, such as your
company name. To sign in after you create an account alias, use the following URL:
API Version 2014-11-13
9
Amazon EC2 Container Service Developer Guide
Create an IAM Role for your
Container Instances and Services
https://your_account_alias.signin.aws.amazon.com/console/
To verify the sign-in link for IAM users for your account, open the IAM console and check under IAM
users sign-in link on the dashboard.
For more information about IAM, see the AWS Identity and Access Management User Guide.
Create an IAM Role for your Container Instances
and Services
Before the Amazon ECS agent can register container instance into a cluster, the agent must know which
account credentials to use. You can create an IAM role that allows the agent to know which account
it should register the container instance with. When you launch an instance with the Amazon ECS-
optimized AMI provided by Amazon using this role, the agent automatically registers the container
instance into your default cluster.
The Amazon ECS container agent also makes calls to the Amazon EC2 and Elastic Load Balancing APIs on
your behalf, so container instances can be registered and deregistered with load balancers. Before you
can attach a load balancer to an Amazon ECS service, you must create an IAM role for your services to
use before you start them. This requirement applies to any Amazon ECS service that you plan to use with
a load balancer.
Note
The Amazon ECS instance and service roles are automatically created for you in the console first
run experience, so if you intend to use the Amazon ECS console, you can move ahead to Create
a Key Pair (p. 10). If you do not intend to use the Amazon ECS console, and instead plan to
use the AWS CLI, complete the procedures in Amazon ECS Container Instance IAM Role (p. 210)
and Amazon ECS Service Scheduler IAM Role (p. 212) before launching container instances or
using Elastic Load Balancing load balancers with services.
Create a Key Pair
AWS uses public-key cryptography to secure the login information for your instance. A Linux instance,
such as an Amazon ECS container instance, has no password to use for SSH access; you use a key pair to
log in to your instance securely. You specify the name of the key pair when you launch your container
instance, then provide the private key when you log in using SSH.
If you haven't created a key pair already, you can create one using the Amazon EC2 console. Note that if
you plan to launch instances in multiple regions, you'll need to create a key pair in each region. For more
information about regions, see Regions and Availability Zones in the Amazon EC2 User Guide for Linux
Instances.
To create a key pair
1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.
2. From the navigation bar, select a region for the key pair. You can select any region that's available to
you, regardless of your location: however, key pairs are specific to a region. For example, if you plan
to launch an instance in the US East (N. Virginia) region, you must create a key pair for the instance
in the same region.
Note
Amazon ECS is available in the following regions:
API Version 2014-11-13
10
Amazon EC2 Container Service Developer Guide
Create a Key Pair
Region Name Region
US East (N. Virginia) us-east-1
US East (Ohio) us-east-2
US West (N.
California)
us-west-1
US West (Oregon) us-west-2
EU (Ireland) eu-west-1
EU (London) eu-west-2
EU (Frankfurt) eu-central-1
Asia Pacific (Tokyo) ap-northeast-1
Asia Pacific
(Singapore)
ap-southeast-1
Asia Pacific (Sydney) ap-southeast-2
Canada (Central) ca-central-1
3. Choose Key Pairs in the navigation pane.
4. Choose Create Key Pair.
5. Enter a name for the new key pair in the Key pair name field of the Create Key Pair dialog box, and
then choose Create. Choose a name that is easy for you to remember, such as your IAM user name,
followed by -key-pair, plus the region name. For example, me-key-pair-useast1.
6. The private key file is automatically downloaded by your browser. The base file name is the name
you specified as the name of your key pair, and the file name extension is .pem. Save the private key
file in a safe place.
Important
This is the only chance for you to save the private key file. You'll need to provide the name
of your key pair when you launch an instance and the corresponding private key each time
you connect to the instance.
7. If you will use an SSH client on a Mac or Linux computer to connect to your Linux instance, use the
following command to set the permissions of your private key file so that only you can read it.
$ chmod 400 your_user_name-key-pair-region_name.pem
For more information, see Amazon EC2 Key Pairs in the Amazon EC2 User Guide for Linux Instances.
To connect to your instance using your key pair
To connect to your Linux instance from a computer running Mac or Linux, specify the .pem file to your
SSH client with the -i option and the path to your private key. To connect to your Linux instance from a
computer running Windows, you can use either MindTerm or PuTTY. If you plan to use PuTTY, you'll need
to install it and use the following procedure to convert the .pem file to a .ppk file.
(Optional) To prepare to connect to a Linux instance from Windows using PuTTY
1. Download and install PuTTY from http://www.chiark.greenend.org.uk/~sgtatham/putty/. Be sure
to install the entire suite.
API Version 2014-11-13
11
Amazon EC2 Container Service Developer Guide
(Optional) Install the Amazon ECS
Command Line Interface (CLI)
2. Start PuTTYgen (for example, from the Start menu, choose All Programs, PuTTY, and PuTTYgen).
3. Under Type of key to generate, choose SSH-2 RSA.
4. Choose Load. By default, PuTTYgen displays only files with the extension .ppk. To locate your .pem
file, choose the option to display files of all types.
5. Select the private key file that you created in the previous procedure and choose Open. Choose OK
to dismiss the confirmation dialog box.
6. Choose Save private key. PuTTYgen displays a warning about saving the key without a passphrase.
Choose Yes.
7. Specify the same name for the key that you used for the key pair. PuTTY automatically adds the
.ppk file extension.
(Optional) Install the Amazon ECS Command Line
Interface (CLI)
Note
This step is not required if you use the first-run wizard to create your cluster.
The Amazon EC2 Container Service (Amazon ECS) command line interface (CLI) provides high-level
commands to simplify creating, updating, and monitoring clusters and tasks from a local development
environment. The Amazon ECS CLI supports Docker Compose, a popular open-source tool for defining
and running multi-container applications. For more information about installing and using the Amazon
ECS CLI, see Using the Amazon ECS Command Line Interface (p. 228).
You can also choose to use Amazon ECS through the AWS CLI. However, you will need to create your VPC
and security groups separately, whereas both the Amazon ECS CLI and the first-run wizard will create
this necessary infrastructure for you. For information about installing the AWS CLI or upgrading it to the
latest version, see Installing the AWS Command Line Interface in the AWS Command Line Interface User
Guide.
API Version 2014-11-13
12
Amazon EC2 Container Service Developer Guide
Installing Docker
Docker Basics
Docker is a technology that allows you to build, run, test, and deploy distributed applications that are
based on Linux containers. Amazon ECS uses Docker images in task definitions to launch containers on
EC2 instances in your clusters. For Amazon ECS product details, featured customer case studies, and
FAQs, see the Amazon EC2 Container Service product detail pages.
The documentation in this guide assumes that readers possess a basic understanding of what Docker is
and how it works. For more information about Docker, see What is Docker? and the Docker User Guide.
Topics
•Installing Docker (p. 13)
•(Optional) Sign up for a Docker Hub Account (p. 14)
•(Optional) Amazon EC2 Container Registry (p. 14)
•Create a Docker Image and Upload it to Docker Hub (p. 15)
•Next Steps (p. 17)
Installing Docker
Docker is available on many different operating systems, including most modern Linux distributions, like
Ubuntu, and even Mac OSX and Windows. For more information about how to install Docker on your
particular operating system, go to the Docker installation guide.
You don't even need a local development system to use Docker. If you are using Amazon EC2 already, you
can launch an Amazon Linux instance and install Docker to get started.
To install Docker on an Amazon Linux instance
1. Launch an instance with the Amazon Linux AMI. For more information, see Launching an Instance in
the Amazon EC2 User Guide for Linux Instances.
2. Connect to your instance. For more information, see Connect to Your Linux Instance in the Amazon
EC2 User Guide for Linux Instances.
3. Update the installed packages and package cache on your instance.
[ec2-user ~]$ sudo yum update -y
4. Install Docker.
[ec2-user ~]$ sudo yum install -y docker
API Version 2014-11-13
13
Amazon EC2 Container Service Developer Guide
(Optional) Sign up for a Docker Hub Account
5. Start the Docker service.
[ec2-user ~]$ sudo service docker start
Starting cgconfig service: [ OK ]
Starting docker: [ OK ]
6. Add the ec2-user to the docker group so you can execute Docker commands without using sudo.
[ec2-user ~]$ sudo usermod -a -G docker ec2-user
7. Log out and log back in again to pick up the new docker group permissions.
8. Verify that the ec2-user can run Docker commands without sudo.
[ec2-user ~]$ docker info
Containers: 2
Images: 24
Storage Driver: devicemapper
Pool Name: docker-202:1-263460-pool
Pool Blocksize: 65.54 kB
Data file: /var/lib/docker/devicemapper/devicemapper/data
Metadata file: /var/lib/docker/devicemapper/devicemapper/metadata
Data Space Used: 702.3 MB
Data Space Total: 107.4 GB
Metadata Space Used: 1.864 MB
Metadata Space Total: 2.147 GB
Library Version: 1.02.89-RHEL6 (2014-09-01)
Execution Driver: native-0.2
Kernel Version: 3.14.27-25.47.amzn1.x86_64
Operating System: Amazon Linux AMI 2014.09
Note
In some cases, you may need to reboot your instance to provide permissions for the ec2-
user to access the Docker daemon. Try rebooting your instance if you see the following
error:
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
(Optional) Sign up for a Docker Hub Account
Docker uses images that are stored in repositories to launch containers with. The most common Docker
image repository (and the default repository for the Docker daemon) is Docker Hub. Although you don't
need a Docker Hub account to use Amazon ECS or Docker, having a Docker Hub account gives you the
freedom to store your modified Docker images so you can use them in your ECS task definitions.
For more information about Docker Hub, and to sign up for an account, go to https://hub.docker.com.
Docker Hub offers public and private registries. You can create a private registry on Docker Hub and
configure Private Registry Authentication (p. 86) on your ECS container instances to use your private
images in task definitions.
(Optional) Amazon EC2 Container Registry
Another registry option is Amazon EC2 Container Registry (Amazon ECR). Amazon ECR is a managed
AWS Docker registry service. Customers can use the familiar Docker CLI to push, pull, and manage
images. For Amazon ECR product details, featured customer case studies, and FAQs, see the Amazon
API Version 2014-11-13
14
Amazon EC2 Container Service Developer Guide
Create a Docker Image and Upload it to Docker Hub
EC2 Container Registry product detail pages. To finish this walkthrough using Amazon ECR, see Create a
Docker Image in the Amazon EC2 Container Registry User Guide.
Create a Docker Image and Upload it to Docker
Hub
Amazon ECS task definitions use Docker images to launch containers on the container instances in your
clusters. In this section, you create a Docker image of a simple PHP web application, and test it on your
local system or EC2 instance, and then push the image to your Docker Hub registry so you can use it in an
ECS task definition.
To create a Docker image of a PHP web application
1. Install git and use it to clone the simple PHP application from your GitHub repository onto your
system.
a. Install git.
[ec2-user ~]$ sudo yum install -y git
b. Clone the simple PHP application onto your system.
[ec2-user ~]$ git clone https://github.com/awslabs/ecs-demo-php-simple-app
2. Change directories to the ecs-demo-php-simple-app folder.
[ec2-user ~]$ cd ecs-demo-php-simple-app
3. Examine the Dockerfile in this folder. A Dockerfile is a manifest that describes the base image to use
for your Docker image and what you want installed and running on it. For more information about
Dockerfiles, go to the Dockerfile Reference.
[ec2-user ecs-demo-php-simple-app]$ cat Dockerfile
FROM ubuntu:12.04
# Install dependencies
RUN apt-get update -y
RUN apt-get install -y git curl apache2 php5 libapache2-mod-php5 php5-mcrypt php5-mysql
# Install app
RUN rm -rf /var/www/*
ADD src /var/www
# Configure apache
RUN a2enmod rewrite
RUN chown -R www-data:www-data /var/www
ENV APACHE_RUN_USER www-data
ENV APACHE_RUN_GROUP www-data
ENV APACHE_LOG_DIR /var/log/apache2
EXPOSE 80
CMD ["/usr/sbin/apache2", "-D", "FOREGROUND"]
This Dockerfile uses the Ubuntu 12.04 image. The RUN instructions update the package caches,
install some software packages for the web server and PHP support, and then add your PHP
API Version 2014-11-13
15
Amazon EC2 Container Service Developer Guide
Create a Docker Image and Upload it to Docker Hub
application to the web server's document root. The EXPOSE instruction exposes port 80 on the
container, and the CMD instruction starts the web server.
4. Build the Docker image from your Dockerfile. Substitute my-dockerhub-username with your Docker
Hub user name.
Note
Some versions of Docker may require the full path to your Dockerfile in the following
command, instead of the relative path shown below.
[ec2-user ecs-demo-php-simple-app]$ docker build -t my-dockerhub-username/amazon-ecs-
sample .
5. Run docker images to verify that the image was created correctly and that the image name contains
a repository that you can push to (in this example, your Docker Hub user name).
[ec2-user ecs-demo-php-simple-app]$ docker images
REPOSITORY TAG IMAGE ID
CREATED VIRTUAL SIZE
my-dockerhub-username/amazon-ecs-sample latest 43c52559a0a1 12
minutes ago 258.1 MB
ubuntu 12.04 78cef618c77e 3
weeks ago 133.7 MB
6. Run the newly built image. The -p 80:80 option maps the exposed port 80 on the container to port
80 on the host system. For more information about docker run, go to the Docker run reference.
[ec2-user ecs-demo-php-simple-app]$ docker run -p 80:80 my-dockerhub-username/amazon-
ecs-sample
apache2: Could not reliably determine the server's fully qualified domain name, using
172.17.0.2 for ServerName
Note
Output from the Apache web server is displayed in the terminal window. You can ignore the
"Could not reliably determine the server's fully qualified domain name" message.
7. Open a browser and point to the server that is running Docker and hosting your container.
• If you are using an EC2 instance, this is the Public DNS value for the server, which is the same
address you use to connect to the instance with SSH. Make sure that the security group for your
instance allows inbound traffic on port 80.
• If you are running Docker locally, point your browser to http://localhost/.
• If you are using docker-machine on a Windows or Mac computer, find the IP address of the
VirtualBox VM that is hosting Docker with the docker-machine ip command, substituting
machine-name with the name of the docker machine you are using.
$ docker-machine ip machine-name
192.168.59.103
You should see a web page running the simple PHP app.
API Version 2014-11-13
16
Amazon EC2 Container Service Developer Guide
Next Steps
8. Stop the Docker container by typing Ctrl+c.
9. Authenticate your Docker client with your Docker Hub credentials.
[ec2-user ecs-demo-php-simple-app]$ docker login
10. Push the image to Docker Hub.
[ec2-user ecs-demo-php-simple-app]$ docker push my-dockerhub-username/amazon-ecs-sample
Next Steps
After the image push is finished, you can use the my-dockerhub-username/amazon-ecs-sample image in
your Amazon ECS task definitions, which you can use to run tasks with.
To register a task definition with the amazon-ecs-sample image
1. Examine the simple-app-task-def.json file in the ecs-demo-php-simple-app folder.
{
"family": "console-sample-app",
API Version 2014-11-13
17
Amazon EC2 Container Service Developer Guide
Next Steps
"volumes": [
{
"name": "my-vol",
"host": {}
}
],
"containerDefinitions": [
{
"environment": [],
"name": "simple-app",
"image": "amazon/amazon-ecs-sample",
"cpu": 10,
"memory": 500,
"portMappings": [
{
"containerPort": 80,
"hostPort": 80
}
],
"mountPoints": [
{
"sourceVolume": "my-vol",
"containerPath": "/var/www/my-vol"
}
],
"entryPoint": [
"/usr/sbin/apache2",
"-D",
"FOREGROUND"
],
"essential": true
},
{
"name": "busybox",
"image": "busybox",
"cpu": 10,
"memory": 500,
"volumesFrom": [
{
"sourceContainer": "simple-app"
}
],
"entryPoint": [
"sh",
"-c"
],
"command": [
"/bin/sh -c \"while true; do /bin/date > /var/www/my-vol/date; sleep 1;
done\""
],
"essential": false
}
]
}
This task definition JSON file specifies two containers, one of which uses the amazon-ecs-sample
image. By default, this image is pulled from the Amazon Docker Hub repository, but you can change
the amazon repository defined above to your own repository if you want to use the my-dockerhub-
username/amazon-ecs-sample image you pushed earlier.
2. Register a task definition with the simple-app-task-def.json file.
[ec2-user ecs-demo-php-simple-app]$ aws ecs register-task-definition --cli-input-json
file://simple-app-task-def.json
API Version 2014-11-13
18
Amazon EC2 Container Service Developer Guide
Next Steps
The task definition is registered in the console-sample-app family as defined in the JSON file.
To run a task with the console-sample-app task definition
Important
Before you can run tasks in Amazon ECS, you need to launch container instances into your
cluster. For more information about how to set up and launch container instances, see Setting
Up with Amazon ECS (p. 8) and Getting Started with Amazon ECS (p. 20).
• Use the following AWS CLI command to run a task with the console-sample-app task definition.
[ec2-user ecs-demo-php-simple-app]$ aws ecs run-task --task-definition console-sample-
app
API Version 2014-11-13
19
Amazon EC2 Container Service Developer Guide
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.
You can optionally create an Amazon EC2 Container Registry (Amazon ECR) image repository and push
an image to it. For more information on Amazon ECR, see the Amazon EC2 Container Registry User Guide.
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.
Important
Before you begin, be sure that you've completed the steps in Setting Up with Amazon ECS (p. 8)
and that your AWS user has the required permissions specified in the Amazon ECS First Run
Wizard (p. 220) IAM policy example.
Choose your Amazon ECS first run wizard configuration options
1. Open the Amazon ECS console first run wizard at https://console.aws.amazon.com/ecs/home#/
firstRun.
2. Select your Amazon ECS first run options.
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.
API Version 2014-11-13
20
Amazon EC2 Container Service Developer Guide
3. 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 (p. 21).
Configure repository
A repository is where 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.
1. 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.
Note
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.
2. Run the docker login command that was returned in the previous step. This command provides an
authorization token that is valid for 12 hours.
Important
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 -p password option, and then entering the password when prompted.
3. (Optional) If you have a Dockerfile for the image 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.
4. Tag the image for your 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 repository:latest with the image ID or image name of your local image to push.
5. Push the newly tagged image to your ECR repository by pasting the docker push command into a
terminal window.
6. Choose Done.
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.
1. Configure your task definition parameters.
The first run wizard comes preloaded with a task definition, and you can see the simple-app
container defined in the console. You can optionally rename the task definition or review and
edit the resources used by the container (such as CPU units and memory limits) by choosing the
API Version 2014-11-13
21
Amazon EC2 Container Service Developer Guide
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.
Note
If you are using an Amazon ECR image in your task definition, be sure to use the
full registry/repository:tag naming for your Amazon ECR images. For example,
aws_account_id.dkr.ecr.region.amazonaws.com/my-web-app:latest.
For more information on what each of these task definition parameters does, see Task Definition
Parameters (p. 98).
2. Choose Next step to continue.
Configure service
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.
1. In the Service Name field, select a name for your service.
2. In the Desired number of tasks field, enter the number of tasks you would like to launch with your
specified task definition.
Note
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.
3. (Optional) You can choose to use an Application 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. For more details, see Introduction to
Application Load Balancers.
Important
Application Load Balancers do incur cost while they exist in your AWS resources. For more
information on Application Load Balancer pricing, see Application Load Balancer Pricing.
Complete the following steps to use a load balancer with your service.
a. In the Application load balancing section, choose the Container name : container port :
protocol menu, and then choose simple-app:80:tcp. 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 (p. 141).
b. 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.
4. Review your load balancer settings and click Next Step.
Configure cluster
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.
1. In the Cluster name field, choose a name for your cluster.
API Version 2014-11-13
22
Amazon EC2 Container Service Developer Guide
2. 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.
3. 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.
Note
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.
4. 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/.
5. (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.
6. 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.
7. Click Review and Launch to proceed.
Review
1. 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).
2. After the launch is complete, choose View service to view your service in the Amazon ECS console.
API Version 2014-11-13
23
Amazon EC2 Container Service Developer Guide
Scale Down Services
Cleaning Up your Amazon ECS
Resources
When you are finished experimenting with or using a particular Amazon ECS cluster, you should clean up
the resources associated with it to avoid incurring charges for resources that you are not using.
Some Amazon ECS resources, such as tasks, services, clusters, and container instances, are cleaned up
using the Amazon ECS console. Other resources, such as Amazon EC2 instances, Elastic Load Balancing
load balancers, and Auto Scaling groups, must be cleaned up manually in the Amazon EC2 console or by
deleting the AWS CloudFormation stack that created them.
Topics
•Scale Down Services (p. 24)
•Delete Services (p. 25)
•Deregister Container Instances (p. 25)
•Delete a Cluster (p. 25)
•Delete the AWS CloudFormation Stack (p. 26)
Scale Down Services
If your cluster contains any services, you should first scale down the desired count of tasks in these
services to 0 so that Amazon ECS does not try to start new tasks on your container instances while you
are cleaning up. Follow the procedure in Updating a Service (p. 165) and enter 0 in the Number of
tasks field.
Alternatively, you can use the following AWS CLI command to scale down your service. Be sure to
substitute the region name, cluster name, and service name for each service that you are scaling down.
aws ecs update-service --cluster default --service service_name --desired-count 0 --
region us-west-2
API Version 2014-11-13
24
Amazon EC2 Container Service Developer Guide
Delete Services
Delete Services
Before you can delete a cluster, you must delete the services inside that cluster. After your service has
scaled down to 0 tasks, you can delete it. For each service inside your cluster, follow the procedures in
Deleting a Service (p. 166) to delete it.
Alternatively, you can use the following AWS CLI command to delete your services. Be sure to substitute
the region name, cluster name, and service name for each service that you are deleting.
aws ecs delete-service --cluster default --service service_name --region us-west-2
Deregister Container Instances
Before you can delete a cluster, you must deregister the container instances inside that cluster. For each
container instance inside your cluster, follow the procedures in Deregister a Container Instance (p. 65)
to deregister it.
Alternatively, you can use the following AWS CLI command to deregister your container instances. Be
sure to substitute the region name, cluster name, and container instance ID for each container instance
that you are deregistering.
aws ecs deregister-container-instance --cluster default --container-
instance container_instance_id --region us-west-2 --force
Delete a Cluster
After you have removed the active resources from your Amazon ECS cluster, you can delete it. Use the
following procedure to delete your cluster.
To delete a cluster
1. Open the Amazon ECS console at https://console.aws.amazon.com/ecs/.
2. From the navigation bar, select the region that your cluster is in.
3. In the navigation pane, select Clusters.
4. On the Clusters page, click the x in the upper-right-hand corner of the cluster you want to delete.
API Version 2014-11-13
25
Amazon EC2 Container Service Developer Guide
Delete the AWS CloudFormation Stack
5. Choose Yes, Delete to delete the cluster.
Alternatively, you can use the following AWS CLI command to delete your cluster. Be sure to substitute
the region name and cluster name for each cluster that you are deleting.
aws ecs delete-cluster --cluster default --region us-west-2
Delete the AWS CloudFormation Stack
If you created your Amazon ECS resources by following the console first-run wizard, then your resources
are contained in a AWS CloudFormation stack. You can completely clean up all of your remaining AWS
resources that are associated with this stack by deleting it. Deleting the CloudFormation stack terminates
the EC2 instances, removes the Auto Scaling group, deletes any Elastic Load Balancing load balancers,
and removes the Amazon VPC subnets and Internet gateway associated with the cluster.
To delete the AWS CloudFormation stack
1. Open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation/.
2. From the navigation bar, select the region that your cluster was created in.
3. Select the stack that is associated with your Amazon ECS resources. The Stack Name value starts
with EC2ContainerService-default.
4. Choose Delete Stack and then choose Yes, Delete to delete your stack resources.
API Version 2014-11-13
26
Amazon EC2 Container Service Developer Guide
Cluster Concepts
Amazon ECS Clusters
An Amazon EC2 Container Service (Amazon ECS) cluster is a logical grouping of container instances that
you can place tasks on. When you first use the Amazon ECS service, a default cluster is created for you,
but you can create multiple clusters in an account to keep your resources separate.
Topics
•Cluster Concepts (p. 27)
•Creating a Cluster (p. 27)
•Scaling a Cluster (p. 29)
•Deleting a Cluster (p. 30)
Cluster Concepts
• Clusters can contain multiple different container instance types.
• Clusters are region-specific.
• Container instances can only be a part of one cluster at a time.
• You can create custom IAM policies for your clusters to allow or restrict users' access to specific
clusters. For more information, see the Clusters (p. 222) section in Amazon ECS IAM Policy
Examples (p. 220).
Creating a Cluster
You can create a Amazon ECS cluster using the AWS Management Console, as described in this topic.
Before you begin, be sure that you've completed the steps in Setting Up with Amazon ECS (p. 8). After
you've created your cluster, you can register container instances into it and run tasks and services.
Note
This cluster creation wizard provides a simple way to create the resources that are needed by an
ECS cluster, and it lets you customize several common cluster configuration options. However,
this wizard does allow you to customize every resource option (for example, the container
API Version 2014-11-13
27
Amazon EC2 Container Service Developer Guide
Creating a Cluster
instance AMI ID). If your requirements extend beyond what is supported in this wizard, consider
using our reference architecture at https://github.com/awslabs/ecs-refarch-cloudformation.
Please do not attempt to modify the underlying resources directly once they are created by the
wizard.
To create a cluster
1. Open the Amazon ECS console at https://console.aws.amazon.com/ecs/.
2. From the navigation bar, select the region to use.
Note
Amazon ECS is available in the following regions:
Region Name Region
US East (N. Virginia) us-east-1
US East (Ohio) us-east-2
US West (N.
California)
us-west-1
US West (Oregon) us-west-2
EU (Ireland) eu-west-1
EU (London) eu-west-2
EU (Frankfurt) eu-central-1
Asia Pacific (Tokyo) ap-northeast-1
Asia Pacific
(Singapore)
ap-southeast-1
Asia Pacific (Sydney) ap-southeast-2
Canada (Central) ca-central-1
3. In the navigation pane, choose Clusters.
4. On the Clusters page, select Create Cluster.
5. For Cluster name, enter a name for your cluster. Up to 255 letters (uppercase and lowercase),
numbers, hyphens, and underscores are allowed.
6. (Optional) To create an empty cluster with no associated container instances, select Create an
empty cluster and choose Create to create your cluster and finish.
Note
If you create an empty cluster, you need to manually launch container instances into it
before you can run tasks in the cluster. For more information, see Launching an Amazon
ECS Container Instance (p. 42).
7. For EC2 instance type, choose the Amazon EC2 instance type for your container instances. The
instance type that you select determines the resources available for your tasks to run on.
8. For Number of instances, choose the number of Amazon EC2 instances to launch into your cluster.
These instances are launched using the latest Amazon ECS-optimized AMI. For more information, see
Amazon ECS-Optimized AMI (p. 34).
9. For EBS storage (GiB), choose the size of the Amazon EBS volume to use for data storage on your
container instances. By default, the Amazon ECS-optimized AMI launches with an 8 GiB root volume
and a 22 GiB data volume. You can increase the size of the data volume to allow for greater image
and container storage.
API Version 2014-11-13
28
Amazon EC2 Container Service Developer Guide
Scaling a Cluster
10. For Key pair, choose an Amazon EC2 key pair to use with your container instances for SSH access.
If you do not specify a key pair, you cannot connect to your container instances with SSH. For more
information, see Amazon EC2 Key Pairs in the Amazon EC2 User Guide for Linux Instances.
11. In the Networking section, configure the VPC to launch your container instances into. By default,
the cluster creation wizard creates a new VPC with two subnets in different Availability Zones, and
a security group open to the Internet on port 80. This is a basic setup that works well for an HTTP
service. However, you can modify these settings by following the substeps below.
a. For VPC, choose to create a new VPC, or choose an existing VPC.
b. (Optional) If you chose to create a new VPC, for CIDR Block, choose a CIDR block for your VPC.
For more information, see Your VPC and Subnets in the Amazon VPC User Guide.
c. For Subnets, choose the subnets to use for your VPC. If you chose to create a new VPC, you can
keep the default settings or you can modify them to meet your needs. If you chose to use an
existing VPC, select one or more subnets in that VPC to use for your cluster.
d. For Security group, choose the security group to attach to the container instances in your
cluster. If you choose to create a new security group, you can specify a CIDR block to allow
inbound traffic from (the default 0.0.0.0/0 is open to the Internet) and a single port or a range
of contiguous ports to open on the container instance. For more complicated security group
rules, you can choose an existing security group that you have already created.
Note
You can also choose to create a new security group and then modify the rules after the
cluster is created. For more information, see Amazon EC2 Security Groups for Linux
Instances in the Amazon EC2 User Guide for Linux Instances.
12. In the Container instance IAM role section, choose the IAM role to use with your container
instances. If your account has the ecsInstanceRole that is created for you in the console first run
wizard, that is selected by default. If you do not have this role in your account, you can choose to
create the role, or you can choose another IAM role to use with your container instances.
Important
If you do not launch your container instance with the proper IAM permissions, your
Amazon ECS agent will not connect to your cluster. For more information, see Amazon ECS
Container Instance IAM Role (p. 210).
13. Choose Create to create your cluster.
Scaling a Cluster
If your cluster was created with the console first-run experience described in Getting Started with
Amazon ECS (p. 20) after November 24th, 2015, then the Auto Scaling group associated with the AWS
CloudFormation stack created for your cluster can be scaled up or down to add or remove container
instances. You can perform this scaling operation from within the Amazon ECS console.
If your cluster was not created with the console first-run experience described in Getting Started with
Amazon ECS (p. 20) after November 24th, 2015, then you cannot scale your cluster from the Amazon
ECS console. However, you can still modify existing Auto Scaling groups associated with your cluster
in the Auto Scaling console. If you do not have an Auto Scaling group associated with your cluster, you
can create one from an existing container instance. For more information, see Creating an Auto Scaling
Group Using an EC2 Instance in the Auto Scaling User Guide. You can also manually launch or terminate
container instances from the Amazon EC2 console; for more information see Launching an Amazon ECS
Container Instance (p. 42).
To scale a cluster
1. Open the Amazon ECS console at https://console.aws.amazon.com/ecs/.
2. From the navigation bar, choose the region that your cluster exists in.
API Version 2014-11-13
29
Amazon EC2 Container Service Developer Guide
Deleting a Cluster
3. In the navigation pane, choose Clusters.
4. Choose the cluster that you want to scale.
5. On the Cluster : name page, choose the ECS Instances tab.
If a Scale ECS Instances button appears, then you can scale your cluster in the next step. If not,
you must manually adjust your Auto Scaling group to scale up or down your instances, or you can
manually launch or terminate your container instances in the Amazon EC2 console.
6. Choose Scale ECS Instances.
7. In the Desired number of instances field, enter the number of instances you wish to scale your
cluster to and choose Scale.
Note
If you reduce the number of container instances in your cluster, any tasks that are running
on terminated instances are stopped.
Deleting a Cluster
If you are finished using a cluster, you can delete it. When you delete a cluster in the Amazon ECS
console, the associated resources that are deleted with it vary depending on how the cluster was created.
Step 5 (p. 31) of the following procedure changes based on that condition.
If your cluster was created with the console first-run experience described in Getting Started with
Amazon ECS (p. 20) after November 24th, 2015, or the cluster creation wizard described in Creating a
Cluster (p. 27), then the AWS CloudFormation stack that was created for your cluster is also deleted
when you delete your cluster.
If your cluster was created manually (without the cluster creation wizard) or with the console first
run experience prior to November 24th, 2015, then you must deregister (or terminate) any container
instances associated with the cluster before you can delete it. For more information, see Deregister
a Container Instance (p. 65). In this case, after the cluster is deleted, you should delete any
API Version 2014-11-13
30
Amazon EC2 Container Service Developer Guide
Deleting a Cluster
remaining AWS CloudFormation stack resources or Auto Scaling groups associated with the cluster
to avoid incurring any future charges for those resources. For more information, see Delete the AWS
CloudFormation Stack (p. 26).
To delete a cluster
1. Open the Amazon ECS console at https://console.aws.amazon.com/ecs/.
2. From the navigation bar, select the region to use.
Note
Amazon ECS is available in the following regions:
Region Name Region
US East (N. Virginia) us-east-1
US East (Ohio) us-east-2
US West (N.
California)
us-west-1
US West (Oregon) us-west-2
EU (Ireland) eu-west-1
EU (London) eu-west-2
EU (Frankfurt) eu-central-1
Asia Pacific (Tokyo) ap-northeast-1
Asia Pacific
(Singapore)
ap-southeast-1
Asia Pacific (Sydney) ap-southeast-2
Canada (Central) ca-central-1
3. In the navigation pane, choose Clusters.
4. On the Clusters page, choose the cluster you want to delete.
Note
If your cluster has registered container instances, you must deregister or terminate them.
For more information, see Deregister a Container Instance (p. 65).
5. Choose Delete Cluster to delete the cluster. You will see one of two confirmation prompts:
•Deleting the cluster also deletes the CloudFormation stack EC2ContainerService-cluster_name:
Deleting this cluster cleans up the associated resources that were created with the cluster,
including Auto Scaling groups, VPCs or load balancers.
•Deleting the cluster does not affect CloudFormation resources...: Deleting this cluster does
not clean up any resources that are associated with the cluster, including Auto Scaling groups,
VPCs or load balancers. Also, any container instances that are registered with this cluster must
be deregistered or terminated before you can delete the cluster; for more information, see
Deregister a Container Instance (p. 65). You can visit the AWS CloudFormation console at
https://console.aws.amazon.com/cloudformation/ to update or delete any of these resources; for
more information, see Delete the AWS CloudFormation Stack (p. 26).
API Version 2014-11-13
31
Amazon EC2 Container Service Developer Guide
Container Instance Concepts
Amazon ECS Container Instances
An Amazon ECS container instance is an Amazon EC2 instance that is running the Amazon ECS container
agent and has been registered into a cluster. When you run tasks with Amazon ECS, your tasks are placed
on your active container instances.
Topics
•Container Instance Concepts (p. 32)
•Container Instance Lifecycle (p. 33)
•Check the Instance Role for Your Account (p. 34)
•Container Instance AMIs (p. 34)
•Launching an Amazon ECS Container Instance (p. 42)
•Bootstrapping Container Instances with Amazon EC2 User Data (p. 45)
•Connect to Your Container Instance (p. 51)
•Using CloudWatch Logs with Container Instances (p. 52)
•Container Instance Draining (p. 59)
•Managing Container Instances Remotely (p. 60)
•Starting a Task at Container Instance Launch Time (p. 63)
•Deregister a Container Instance (p. 65)
Container Instance Concepts
• Your container instance must be running the Amazon ECS container agent to register into one of
your clusters. If you are using the Amazon ECS-optimized AMI, the agent is already installed. To use
a different operating system, install the agent. For more information, see Amazon ECS Container
Agent (p. 68).
• Because the Amazon ECS container agent makes calls to Amazon ECS on your behalf, you must launch
container instances with an IAM role that authenticates to your account and provides the required
resource permissions. For more information, see Amazon ECS Container Instance IAM Role (p. 210).
• If any of the containers associated with your tasks require external connectivity, you can map their
network ports to ports on the host Amazon ECS container instance so they are reachable from the
Internet. Your container instance security group must allow inbound access to the ports you want to
expose. For more information, see Create a Security Group in the Amazon VPC Getting Started Guide.
API Version 2014-11-13
32
Amazon EC2 Container Service Developer Guide
Container Instance Lifecycle
• We strongly recommend launching your container instances inside a VPC, because Amazon VPC
delivers more control over your network and offers more extensive configuration capabilities. For more
information, see Amazon EC2 and Amazon Virtual Private Cloud in the Amazon EC2 User Guide for
Linux Instances.
• Container instances need external network access to communicate with the Amazon ECS service
endpoint. If your container instances do not have public IP addresses, then they must use network
address translation (NAT) or an HTTP proxy to provide this access. For more information, see NAT
Instances in the Amazon VPC User Guide and HTTP Proxy Configuration (p. 91) in this guide.
• The type of EC2 instance that you choose for your container instances determines the resources
available in your cluster. Amazon EC2 provides different instance types, each with different CPU,
memory, storage, and networking capacity that you can use to run your tasks. For more information,
see Amazon EC2 Instances.
• Because each container instance has unique state information that is stored locally on the container
instance and within Amazon ECS, they should not be deregistered from one cluster and re-registered
into another. To relocate container instance resources, we recommend that you terminate container
instances from one cluster and launch new container instances with the latest Amazon ECS-optimized
AMI in the new cluster. For more information, see Terminate Your Instance in the Amazon EC2 User
Guide for Linux Instances and Launching an Amazon ECS Container Instance (p. 42).
• Because each container instance has unique state information that is stored locally on the container
instance and within Amazon ECS, you cannot stop a container instance and change its instance type.
Instead, we recommend that you terminate the container instance and launch a new container instance
with the desired instance size and the latest Amazon ECS-optimized AMI in your desired cluster. For
more information, see Terminate Your Instance in the Amazon EC2 User Guide for Linux Instances and
Launching an Amazon ECS Container Instance (p. 42) in this guide.
Container Instance Lifecycle
When the Amazon ECS container agent registers an instance into your cluster, the container instance
reports its status as ACTIVE and its agent connection status as TRUE. This container instance can accept
run task requests.
If you stop (not terminate) an Amazon ECS container instance, the status remains ACTIVE, but the
agent connection status transitions to FALSE within a few minutes. Any tasks that were running on the
container instance stop. If you start the container instance again, the container agent reconnects with
the Amazon ECS service, and you are able to run tasks on the instance again.
Important
If you stop and start a container instance, or reboot that instance, some older versions of the
Amazon ECS container agent register the instance again without deregistering the original
container instance ID. In this case, Amazon ECS lists more container instances in your cluster
than you actually have. (If you have duplicate container instance IDs for the same Amazon
EC2 instance ID, you can safely deregister the duplicates that are listed as ACTIVE with an
agent connection status of FALSE.) This issue is fixed in the current version of the Amazon ECS
container agent. To update to the current version, see Updating the Amazon ECS Container
Agent (p. 73).
If you change the status of a container instance to DRAINING, new tasks are not placed on the container
instance. Any service tasks running on the container instance are removed, if possible, so that you can
perform system updates. For more information, see Container Instance Draining (p. 59).
If you deregister or terminate a container instance, the container instance status changes to INACTIVE
immediately, and the container instance is no longer reported when you list your container instances.
However, you can still describe the container instance for one hour following termination. After one hour,
the instance description is no longer available.
API Version 2014-11-13
33
Amazon EC2 Container Service Developer Guide
Check the Instance Role for Your Account
Check the Instance Role for Your Account
The Amazon ECS container agent makes calls to the Amazon ECS APIs on your behalf. Container
instances that run the agent require an IAM policy and role for the service to know that the agent
belongs to you.
In most cases, the Amazon ECS instance role is automatically created for you in the console first-run
experience. You can use the following procedure to check and see if your account already has an Amazon
ECS service role.
To check for the ecsInstanceRole in the IAM console
1. Sign in to the IAM console at https://console.aws.amazon.com/iam/.
2. In the navigation pane, choose Roles.
3. Search the list of roles for ecsInstanceRole. If the role exists, you do not need to create it. If the role
does not exist, follow the procedures in Amazon ECS Container Instance IAM Role (p. 210) to create
the role.
Container Instance AMIs
The basic Amazon EC2 Container Service (Amazon ECS) container instance specification consists of the
following:
Required
• A modern Linux distribution running at least version 3.10 of the Linux kernel.
• The Amazon ECS container agent (preferably the latest version). For more information, see Amazon
ECS Container Agent (p. 68).
• A Docker daemon running at least version 1.5.0, and any Docker runtime dependencies. For more
information, see Check runtime dependencies in the Docker documentation.
Note
For the best experience, we recommend the Docker version that ships with and is tested with
the corresponding Amazon ECS agent version that you are using. For more information, see
Amazon ECS-Optimized AMI Container Agent Versions (p. 72).
Recommended
• An initialization and nanny process to run and monitor the Amazon ECS agent. The Amazon ECS-
optimized AMI uses the ecs-init upstart process. For more information, see the ecs-init project on
GitHub.
The Amazon ECS-optimized AMI is preconfigured with these requirements and recommendations. We
recommend that you use the Amazon ECS-optimized AMI for your container instances unless your
application requires a specific operating system or a Docker version that is not yet available in that AMI.
For more information, see Amazon ECS-Optimized AMI (p. 34).
Amazon ECS-Optimized AMI
The Amazon ECS-optimized AMI is the recommended AMI for you to use to launch your Amazon
ECS container instances. Although you can create your own container instance AMI that meets the
API Version 2014-11-13
34
Amazon EC2 Container Service Developer Guide
Amazon ECS-Optimized AMI
basic specifications outlined in Container Instance AMIs (p. 34), the Amazon ECS-optimized AMI is
preconfigured and tested on Amazon ECS by AWS engineers. It is the simplest AMI for you to get started
and to get your containers running on AWS quickly.
The current Amazon ECS-optimized AMI (amzn-ami-2016.09.g-amazon-ecs-optimized) consists of:
• The latest minimal version of the Amazon Linux AMI
• The latest version of the Amazon ECS container agent (1.14.1)
• The recommended version of Docker for the latest Amazon ECS container agent (1.12.6)
• The latest version of the ecs-init package to run and monitor the Amazon ECS agent (1.14.1-1)
Topics
•How to Launch the Latest Amazon ECS-Optimized AMI (p. 35)
•Storage Configuration (p. 36)
•Subscribing to Amazon ECS–Optimized AMI Update Notifications (p. 40)
How to Launch the Latest Amazon ECS-Optimized AMI
The following are several ways that you can launch the latest Amazon ECS-optimized AMI into your
cluster:
• The Amazon ECS console first-run wizard launches your container instances with the latest Amazon
ECS-optimized AMI. For more information, see Getting Started with Amazon ECS (p. 20).
• You can launch your container instances manually in the Amazon EC2 console by following the
procedures in Launching an Amazon ECS Container Instance (p. 42). You could also choose the EC2
console link in the table below that corresponds to your cluster's region.
• Use an AMI ID from the table below that corresponds to your cluster's region with the AWS CLI, the
AWS SDKs, or an AWS CloudFormation template to launch your instances.
The current Amazon ECS–optimized AMI IDs by region are listed below for reference.
Region AMI Name AMI ID EC2 console link
us-east-1 amzn-ami-2016.09.g-
amazon-ecs-optimized
ami-275ffe31 Launch instance
us-east-2 amzn-ami-2016.09.g-
amazon-ecs-optimized
ami-62745007 Launch instance
us-west-1 amzn-ami-2016.09.g-
amazon-ecs-optimized
ami-689bc208 Launch instance
us-west-2 amzn-ami-2016.09.g-
amazon-ecs-optimized
ami-62d35c02 Launch instance
eu-west-1 amzn-ami-2016.09.g-
amazon-ecs-optimized
ami-95f8d2f3 Launch instance
eu-west-2 amzn-ami-2016.09.g-
amazon-ecs-optimized
ami-bf9481db Launch instance
eu-central-1 amzn-ami-2016.09.g-
amazon-ecs-optimized
ami-085e8a67 Launch instance
API Version 2014-11-13
35
Amazon EC2 Container Service Developer Guide
Amazon ECS-Optimized AMI
Region AMI Name AMI ID EC2 console link
ap-northeast-1 amzn-ami-2016.09.g-
amazon-ecs-optimized
ami-f63f6f91 Launch instance
ap-southeast-1 amzn-ami-2016.09.g-
amazon-ecs-optimized
ami-b4ae1dd7 Launch instance
ap-southeast-2 amzn-ami-2016.09.g-
amazon-ecs-optimized
ami-fbe9eb98 Launch instance
ca-central-1 amzn-ami-2016.09.g-
amazon-ecs-optimized
ami-ee58e58a Launch instance
For previous versions of the Amazon ECS-optimized AMI and its corresponding Docker and Amazon ECS
container agent versions, see Amazon ECS-Optimized AMI Container Agent Versions (p. 72).
Storage Configuration
By default, the Amazon ECS-optimized AMI ships with 30 GiB of total storage. You can modify this value
at launch time to increase or decrease the available storage on your container instance. This storage is
used for the operating system and for Docker images and metadata. The sections below describe the
storage configuration of the Amazon ECS-optimized AMI, based on the AMI version.
Version 2015.09.d and Later
Amazon ECS-optimized AMIs from version 2015.09.d and later launch with an 8-GiB volume for the
operating system that is attached at /dev/xvda and mounted as the root of the file system. There is
an additional 22-GiB volume that is attached at /dev/xvdcz that Docker uses for image and metadata
storage. The volume is configured as a Logical Volume Management (LVM) device and it is accessed
directly by Docker via the devicemapper backend. Because the volume is not mounted, you cannot use
standard storage information commands (such as df -h) to determine the available storage. However,
you can use LVM commands and docker info to find the available storage by following the procedure
below. For more information about LVM, see the LVM HOWTO in The Linux Documentation Project.
The docker-storage-setup utility configures the LVM volume group and logical volume for Docker when
the instance launches. By default, docker-storage-setup creates a volume group called docker, adds /
dev/xvdcz as a physical volume to that group. It then creates a logical volume called docker-pool that
uses 99% of the available storage in the volume group. The remaining 1% of the available storage is
reserved for metadata.
Note
Earlier Amazon ECS-optimized AMI versions (2015.09.d to 2016.03.a) create a logical volume
that uses 40% of the available storage in the volume group. When the logical volume becomes
60% full, the logical volume is increased in size by 20%.
To determine the available storage for Docker
• You can use the LVM commands, vgs and lvs, or the docker info command to view available storage
for Docker.
Note
The LVM command output displays storage values in GiB (2^30 bytes), and docker info
displays storage values in GB (10^9 bytes).
a. You can view the available storage in the volume group with the vgs command. This command
shows the total size of the volume group and the available space in the volume group that can
be used to grow the logical volume. The example below shows a 22-GiB volume with 204 MiB of
free space.
API Version 2014-11-13
36
Amazon EC2 Container Service Developer Guide
Amazon ECS-Optimized AMI
[ec2-user ~]$ sudo vgs
Output:
VG #PV #LV #SN Attr VSize VFree
docker 1 1 0 wz--n- 22.00g 204.00m
b. You can view the available space in the logical volume with the lvs command. The example
below shows a logical volume that is 21.75 GiB in size, and it is 7.63% full. This logical volume
can grow until there is no more free space in the volume group.
[ec2-user@ ~]$ sudo lvs
Output:
LV VG Attr LSize Pool Origin Data% Meta% Move Log Cpy%Sync
Convert
docker-pool docker twi-aot--- 21.75g 7.63 4.96
c. The docker info command also provides information about how much data space it is using,
and how much data space is available. However, its available space value is based on the logical
volume size that it is using.
Note
Because docker info displays storage values as GB (10^9 bytes), instead of GiB (2^30
bytes), the values displayed here look larger for the same amount of storage displayed
with lvs. However, the values are equal (23.35 GB = 21.75 GiB).
[ec2-user ~]$ docker info | grep "Data Space"
Output:
Data Space Used: 1.782 GB
Data Space Total: 23.35 GB
Data Space Available: 21.57 GB
To extend the Docker logical volume
The easiest way to add storage to your container instances is to terminate the existing instances and
launch new ones with larger data storage volumes. However, if you are unable to do this, you can add
storage to the volume group that Docker uses and extend its logical volume by following these steps.
Note
If your container instance storage is filling up too quickly, there are a few actions that you can
take to reduce this effect:
• (Amazon ECS container agent 1.8.0 and later) Reduce the amount of time
that stopped or exited containers remain on your container instances. The
ECS_ENGINE_TASK_CLEANUP_WAIT_DURATION agent configuration variable sets the time duration
to wait from when a task is stopped until the Docker container is removed (by default, this
value is 3 hours). This removes the Docker container data. If this value is set too low, you may
not be able to inspect your stopped containers or view the logs before they are removed. For
more information, see Amazon ECS Container Agent Configuration (p. 79).
• Remove non-running containers and unused images from your container instances. You can
use the following example commands to manually remove stopped containers and unused
API Version 2014-11-13
37
Amazon EC2 Container Service Developer Guide
Amazon ECS-Optimized AMI
images. Deleted containers cannot be inspected later, and deleted images must be pulled
again before starting new containers from them.
To remove non-running containers, execute the following command on your container
instance:
$ docker rm $(docker ps -aq)
To remove unused images, execute the following command on your container instance:
$ docker rmi $(docker images -q)
• Remove unused data blocks within containers. You can use the following command to run
fstrim on any running container and discard any data blocks that are unused by the container
file system.
$ sudo sh -c "docker ps -q | xargs docker inspect --format='{{ .State.Pid }}' |
xargs -IZ fstrim /proc/Z/root/"
1. Create a new Amazon EBS volume in the same Availability Zone as your container instance. For more
information, see Creating an Amazon EBS Volume in the Amazon EC2 User Guide for Linux Instances.
2. Attach the volume to your container instance. The default location for the Docker data volume is /
dev/xvdcz. For consistency, attach additional volumes in reverse alphabetical order from that device
name (for example, /dev/xvdcy). For more information, see Attaching an Amazon EBS Volume to an
Instance in the Amazon EC2 User Guide for Linux Instances.
3. Connect to your container instance using SSH. For more information, see Connect to Your Container
Instance (p. 51).
4. Check the size of your docker-pool logical volume. The example below shows a logical volume of
409.19 GiB.
[ec2-user ~]$ sudo lvs
Output:
LV VG Attr LSize Pool Origin Data% Meta% Move Log Cpy%Sync
Convert
docker-pool docker twi-aot--- 409.19g 0.16 0.08
5. Check the current available space in your volume group. The example below shows 612.75 GiB in the
VFree column.
[ec2-user ~]$ sudo vgs
Output:
VG #PV #LV #SN Attr VSize VFree
docker 1 1 0 wz--n- 1024.00g 612.75g
6. Add the new volume to the docker volume group, substituting the device name to which you
attached the new volume. In this example, a 1-TiB volume was previously added and attached to /
dev/xvdcy.
[ec2-user ~]$ sudo vgextend docker /dev/xvdcy
API Version 2014-11-13
38
Amazon EC2 Container Service Developer Guide
Amazon ECS-Optimized AMI
Physical volume "/dev/sdcy" successfully created
Volume group "docker" successfully extended
7. Verify that your volume group size has increased with the vgs command. The VFree column should
show the increased storage size. The example below now has 1.6 TiB in the VFree column, which is
1 TiB larger than it was previously. Your VFree column should be the sum of the original VFree value
and the size of the volume you attached.
[ec2-user ~]$ sudo vgs
Output:
VG #PV #LV #SN Attr VSize VFree
docker 2 1 0 wz--n- 2.00t 1.60t
8. Extend the docker-pool logical volume with the size of the volume you added earlier. The command
below adds 1024 GiB to the logical volume, which is entered as 1024G.
[ec2-user ~]$ sudo lvextend -L+1024G /dev/docker/docker-pool
Output:
Size of logical volume docker/docker-pool_tdata changed from 409.19 GiB (104752
extents) to 1.40 TiB (366896 extents).
Logical volume docker-pool successfully resized
9. Verify that your logical volume has increased in size.
[ec2-user ~]$ sudo lvs
Output:
LV VG Attr LSize Pool Origin Data% Meta% Move Log Cpy%Sync
Convert
docker-pool docker twi-aot--- 1.40t 0.04 0.12
10. (Optional) Verify that docker info also recognizes the added storage space.
Note
Because docker info displays storage values as GB (10^9 bytes), instead of GiB (2^30 bytes),
the values displayed here look larger for the same amount of storage displayed with lvs.
However, the values are equal (1.539 TB =1.40 TiB).
[ec2-user ~]$ docker info | grep "Data Space"
Output:
Data Space Used: 109.6 MB
Data Space Total: 1.539 TB
Data Space Available: 1.539 TB
Version 2015.09.c and Earlier
Amazon ECS-optimized AMIs from version 2015.09.c and earlier launch with a single 30-GiB volume that
is attached at /dev/xvda and mounted as the root of the file system. This volume shares the operating
API Version 2014-11-13
39
Amazon EC2 Container Service Developer Guide
Amazon ECS-Optimized AMI
system and all Docker images and metadata. You can determine the available storage on your container
instance with standard storage information commands (such as df -h).
There is no practical way to add storage (that Docker can use) to instances launched from these AMIs
without stopping them. If you find that your container instances need more storage than the default 30
GiB, you should terminate each instance. Then, launch another in its place with the latest Amazon ECS-
optimized AMI and a large enough data storage volume.
Subscribing to Amazon ECS–Optimized AMI Update
Notifications
The Amazon ECS-optimized AMI receives regular updates for agent changes, Docker version updates,
and Linux kernel security updates. You can subscribe to the AMI update Amazon SNS topic to receive
notifications when a new Amazon ECS–optimized AMI is available. Notifications are available in all
formats that Amazon SNS supports.
Note
Your user account must have sns::subscribe IAM permissions to subscribe to an SNS topic.
You can subscribe an Amazon SQS queue to this notification topic, but you must use a topic ARN that is
in the same region. For more information, see Tutorial: Subscribing an Amazon SQS Queue to an Amazon
SNS Topic in the Amazon Simple Queue Service Developer Guide.
You can also use an AWS Lambda function to trigger events when notifications are received. For more
information, see Invoking Lambda functions using Amazon SNS notifications in the Amazon Simple
Notification Service Developer Guide.
The Amazon SNS topic ARNs for each region are shown below.
AWS Region Amazon SNS Topic ARN
us-east-1 arn:aws:sns:us-east-1:177427601217:ecs-
optimized-amazon-ami-update
us-east-2 arn:aws:sns:us-east-2:177427601217:ecs-
optimized-amazon-ami-update
us-west-1 arn:aws:sns:us-west-1:177427601217:ecs-
optimized-amazon-ami-update
us-west-2 arn:aws:sns:us-west-2:177427601217:ecs-
optimized-amazon-ami-update
eu-west-1 arn:aws:sns:eu-west-1:177427601217:ecs-
optimized-amazon-ami-update
eu-west-2 arn:aws:sns:eu-west-2:177427601217:ecs-
optimized-amazon-ami-update
eu-central-1 arn:aws:sns:eu-central-1:177427601217:ecs-
optimized-amazon-ami-update
ap-northeast-1 arn:aws:sns:ap-
northeast-1:177427601217:ecs-optimized-
amazon-ami-update
ap-southeast-1 arn:aws:sns:ap-
southeast-1:177427601217:ecs-optimized-
amazon-ami-update
API Version 2014-11-13
40
Amazon EC2 Container Service Developer Guide
Amazon ECS-Optimized AMI
AWS Region Amazon SNS Topic ARN
ap-southeast-2 arn:aws:sns:ap-
southeast-2:177427601217:ecs-optimized-
amazon-ami-update
ca-central-1 arn:aws:sns:ca-central-1:177427601217:ecs-
optimized-amazon-ami-update
To subscribe to AMI update notification emails in the AWS Management Console
1. Open the Amazon SNS console at https://console.aws.amazon.com/sns/v2/home.
2. In the region list, choose the same region as the topic ARN to which to subscribe. This example uses
the us-west-2 region.
3. Choose Create subscription.
4. In the Create Subscription dialog box, for Topic ARN, paste the Amazon ECS-optimized AMI update
topic ARN: arn:aws:sns:us-west-2:177427601217:ecs-optimized-amazon-ami-update.
5. For Protocol, choose Email. For Endpoint, type an email address you can use to receive the
notification.
6. Choose Create subscription.
7. In your email application, open the message from AWS Notifications and open the link to confirm
your subscription.
Your web browser displays a confirmation response from Amazon SNS.
To subscribe to AMI update notification emails with the AWS CLI
1. Run the following command with the AWS CLI:
aws sns --region us-west-2 subscribe --topic-arn arn:aws:sns:us-
west-2:177427601217:ecs-optimized-amazon-ami-update --protocol email --notification-
endpoint your_email@your_domain.com
2. In your email application, open the message from AWS Notifications and open the link to confirm
your subscription.
Your web browser displays a confirmation response from Amazon SNS.
Amazon SNS Message Format
An example AMI update notification message is shown below:
{
"ECSAgent": {
"ReleaseVersion": "1.14.1"
},
"ECSAmis": [
{
"ReleaseVersion": "2016.09.g",
"AgentVersion": "1.14.1",
"ReleaseNotes": "This AMI includes the latest ECS agent 2016.09.g",
"OsType": "linux",
"OperatingSystemName": "Amazon Linux",
"Regions": {
"ap-northeast-1": {
API Version 2014-11-13
41
Amazon EC2 Container Service Developer Guide
Launching a Container Instance
"Name": "amzn-ami-2016.09.g-amazon-ecs-optimized",
"ImageId": "ami-f63f6f91"
},
"ap-southeast-1": {
"Name": "amzn-ami-2016.09.g-amazon-ecs-optimized",
"ImageId": "ami-b4ae1dd7"
},
"ap-southeast-2": {
"Name": "amzn-ami-2016.09.g-amazon-ecs-optimized",
"ImageId": "ami-fbe9eb98"
},
"ca-central-1": {
"Name": "amzn-ami-2016.09.g-amazon-ecs-optimized",
"ImageId": "ami-ee58e58a"
},
"eu-central-1": {
"Name": "amzn-ami-2016.09.g-amazon-ecs-optimized",
"ImageId": "ami-085e8a67"
},
"eu-west-1": {
"Name": "amzn-ami-2016.09.g-amazon-ecs-optimized",
"ImageId": "ami-95f8d2f3"
},
"eu-west-2": {
"Name": "amzn-ami-2016.09.g-amazon-ecs-optimized",
"ImageId": "ami-bf9481db"
},
"us-east-1": {
"Name": "amzn-ami-2016.09.g-amazon-ecs-optimized",
"ImageId": "ami-275ffe31"
},
"us-east-2": {
"Name": "amzn-ami-2016.09.g-amazon-ecs-optimized",
"ImageId": "ami-62745007"
},
"us-west-1": {
"Name": "amzn-ami-2016.09.g-amazon-ecs-optimized",
"ImageId": "ami-689bc208"
},
"us-west-2": {
"Name": "amzn-ami-2016.09.g-amazon-ecs-optimized",
"ImageId": "ami-62d35c02"
}
}
}
]
}
Launching an Amazon ECS Container Instance
You can launch an Amazon ECS container instance using the AWS Management Console, as described
in this topic. Before you begin, be sure that you've completed the steps in Setting Up with Amazon
ECS (p. 8). After you've launched your instance, you can use it to run tasks.
To launch a container instance
1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.
2. From the navigation bar, select the region to use.
Note
Amazon ECS is available in the following regions:
API Version 2014-11-13
42
Amazon EC2 Container Service Developer Guide
Launching a Container Instance
Region Name Region
US East (N. Virginia) us-east-1
US East (Ohio) us-east-2
US West (N.
California)
us-west-1
US West (Oregon) us-west-2
EU (Ireland) eu-west-1
EU (London) eu-west-2
EU (Frankfurt) eu-central-1
Asia Pacific (Tokyo) ap-northeast-1
Asia Pacific
(Singapore)
ap-southeast-1
Asia Pacific (Sydney) ap-southeast-2
Canada (Central) ca-central-1
3. From the console dashboard, choose Launch Instance.
4. On the Choose an Amazon Machine Image (AMI) page, choose Community AMIs.
5. Choose an AMI for your container instance. You can choose the Amazon ECS-optimized AMI,
or another operating system, such as CoreOS or Ubuntu. If you do not choose the Amazon
ECS-optimized AMI, you must follow the procedures in Installing the Amazon ECS Container
Agent (p. 68).
Note
For Amazon ECS-specific CoreOS installation instructions, see https://coreos.com/docs/
running-coreos/cloud-providers/ecs/.
To use the Amazon ECS-optimized AMI, type amazon-ecs-optimized in the Search community
AMIs field and press the Enter key. Choose Select next to the amzn-ami-2016.09.g-amazon-ecs-
optimized AMI. The current Amazon ECS–optimized AMI IDs by region are listed below for reference.
Region AMI ID
us-east-1 ami-275ffe31
us-east-2 ami-62745007
us-west-1 ami-689bc208
us-west-2 ami-62d35c02
eu-west-1 ami-95f8d2f3
eu-west-2 ami-bf9481db
eu-central-1 ami-085e8a67
ap-northeast-1 ami-f63f6f91
API Version 2014-11-13
43
Amazon EC2 Container Service Developer Guide
Launching a Container Instance
Region AMI ID
ap-southeast-1 ami-b4ae1dd7
ap-southeast-2 ami-fbe9eb98
ca-central-1 ami-ee58e58a
6. On the Choose an Instance Type page, you can select the hardware configuration of your instance.
The t2.micro instance type is selected by default. The instance type that you select determines the
resources available for your tasks to run on.
7. Choose Next: Configure Instance Details.
8. On the Configure Instance Details page, set the Auto-assign Public IP field depending on whether
you want your instance to be accessible from the public Internet. If your instance should be
accessible from the Internet, verify that the Auto-assign Public IP field is set to Enable. If your
instance should not be accessible from the Internet, set this field to Disable.
Note
Container instances need external network access to communicate with the Amazon ECS
service endpoint. If your container instances do not have public IP addresses, then they
must use network address translation (NAT) or an HTTP proxy to provide this access.
For more information, see NAT Instances in the Amazon VPC User Guide and HTTP Proxy
Configuration (p. 91) in this guide.
9. On the Configure Instance Details page, select the ecsInstanceRole IAM role value that you
created for your container instances in Setting Up with Amazon ECS (p. 8).
Important
If you do not launch your container instance with the proper IAM permissions, your Amazon
ECS agent cannot connect to your cluster. For more information, see Amazon ECS Container
Instance IAM Role (p. 210).
10. (Optional) Configure your Amazon ECS container instance with user data, such as the agent
environment variables from Amazon ECS Container Agent Configuration (p. 79). Amazon EC2 user
data scripts are executed only one time, when the instance is first launched.
By default, your container instance launches into your default cluster. To launch into a non-default
cluster, choose the Advanced Details list. Then, paste the following script into the User data field,
replacing your_cluster_name with the name of your cluster.
#!/bin/bash
echo ECS_CLUSTER=your_cluster_name >> /etc/ecs/ecs.config
Or, if you have an ecs.config file in Amazon S3 and have enabled Amazon S3 read-only access to
your container instance role, choose the Advanced Details list. Then, paste the following script into
the User data field, replacing your_bucket_name with the name of your bucket to install the AWS CLI
and write your configuration file at launch time.
Note
For more information about this configuration, see Storing Container Instance
Configuration in Amazon S3 (p. 84).
#!/bin/bash
yum install -y aws-cli
aws s3 cp s3://your_bucket_name/ecs.config /etc/ecs/ecs.config
For more information, see Bootstrapping Container Instances with Amazon EC2 User Data (p. 45).
11. Choose Next: Add Storage.
12. On the Add Storage page, configure the storage for your container instance.
API Version 2014-11-13
44
Amazon EC2 Container Service Developer Guide
Bootstrap Container Instances
If you are using an Amazon ECS-optimized AMI before the 2015.09.d version, your instance has a
single volume that is shared by the operating system and Docker.
If you are using the 2015.09.d or later Amazon ECS-optimized AMI, your instance has two volumes
configured. The Root volume is for the operating system's use, and the second Amazon EBS volume
(attached to /dev/xvdcz) is for Docker's use.
You can optionally increase or decrease the volume sizes for your instance to meet your application
needs.
13. Choose Review and Launch.
14. On the Review Instance Launch page, under Security Groups, you see that the wizard created and
selected a security group for you. Instead, select the security group that you created in Setting Up
with Amazon ECS (p. 8) using the following steps:
a. Choose Edit security groups.
b. On the Configure Security Group page, select the Select an existing security group option.
c. Select the security group you created for your container instance from the list of existing
security groups, and choose Review and Launch.
15. On the Review Instance Launch page, choose Launch.
16. In the Select an existing key pair or create a new key pair dialog box, choose Choose an existing
key pair, then select the key pair that you created when getting set up.
When you are ready, select the acknowledgment field, and then choose Launch Instances.
17. A confirmation page lets you know that your instance is launching. Choose View Instances to close
the confirmation page and return to the console.
18. On the Instances screen, you can view the status of your instance. It takes a short time for an
instance to launch. When you launch an instance, its initial state is pending. After the instance starts,
its state changes to running, and it receives a public DNS name. If the Public DNS column is hidden,
choose Show/Hide, Public DNS.
Bootstrapping Container Instances with Amazon
EC2 User Data
When you launch an Amazon ECS container instance, you have the option of passing user data to
the instance. The data can be used to perform common automated configuration tasks and even run
scripts when the instance boots. For Amazon ECS, the most common use cases for user data are to pass
configuration information to the Docker daemon and the Amazon ECS container agent.
You can pass multiple types of user data to Amazon EC2, including cloud boothooks, shell scripts, and
cloud-init directives. For more information about these and other format types, see the Cloud-Init
documentation.
You can pass this user data into the Amazon EC2 launch wizard in Step 10 (p. 44) of Launching an
Amazon ECS Container Instance (p. 42).
Topics
•Amazon ECS Container Agent (p. 46)
•Docker Daemon (p. 46)
•cloud-init-per Utility (p. 46)
•MIME Multi Part Archive (p. 47)
•Example Container Instance User Data Configuration Scripts (p. 48)
API Version 2014-11-13
45
Amazon EC2 Container Service Developer Guide
Amazon ECS Container Agent
Amazon ECS Container Agent
The Amazon ECS-optimized AMI looks for agent configuration data in the /etc/ecs/ecs.config file
when the container agent starts. You can specify this configuration data at launch with Amazon EC2 user
data. For a complete list of available Amazon ECS container agent configuration variables, see Amazon
ECS Container Agent Configuration (p. 79).
To set only a single agent configuration variable, such as the cluster name, use echo to copy the variable
to the configuration file:
#!/bin/bash
echo "ECS_CLUSTER=MyCluster" >> /etc/ecs/ecs.config
If you have multiple variables to write to /etc/ecs/ecs.config, use the following heredoc format. This
format writes everything between the lines beginning with cat and EOF to the configuration file.
#!/bin/bash
cat <<'EOF' >> /etc/ecs/ecs.config
ECS_CLUSTER=MyCluster
ECS_ENGINE_AUTH_TYPE=docker
ECS_ENGINE_AUTH_DATA={"https://index.docker.io/v1/":
{"username":"my_name","password":"my_password","email":"email@example.com"}}
ECS_LOGLEVEL=debug
EOF
Docker Daemon
You can specify Docker daemon configuration information with Amazon EC2 user data, but this
configuration data must be written before the Docker daemon starts. The cloud-boothook user data
format executes earlier in the boot process than a user data shell script. For a complete list of Docker
daemon configuration options, see the Docker daemon documentation.
By default, cloud-boothook user data is run at every instance boot, so you must create a mechanism
to prevent the boothook from running multiple times. The cloud-init-per utility is provided to control
boothook frequency in this manner. For more information, see cloud-init-per Utility (p. 46).
In the example below, the --storage-opt dm.basesize=20G option is appended to any existing options
in the Docker daemon configuration file, /etc/sysconfig/docker.
#cloud-boothook
cloud-init-per once docker_options echo 'OPTIONS="${OPTIONS} --storage-opt
dm.basesize=20G"' >> /etc/sysconfig/docker
To write multiple lines to a file, use the following heredoc format to accomplish the same goal:
#cloud-boothook
cloud-init-per instance docker_options cat <<'EOF' >> /etc/sysconfig/docker
OPTIONS="${OPTIONS} --storage-opt dm.basesize=20G"
HTTP_PROXY=http://proxy.example.com:80/
EOF
cloud-init-per Utility
The cloud-init-per utility is provided by the cloud-init package to help you create boothook commands
for instances that run at a specified frequency.
API Version 2014-11-13
46
Amazon EC2 Container Service Developer Guide
MIME Multi Part Archive
The cloud-init-per utility syntax is as follows:
cloud-init-per frequency name cmd [ arg1 [ arg2 [ ... ] ]
frequency
How often the boothook should run.
• Specify once to never run again, even with a new instance ID.
• Specify instance to run on the first boot for each new instance launch. For example, if you create
an AMI from the instance after the boothook has run, it still runs again on subsequent instances
launched from that AMI.
• Specify always to run at every boot.
name
The name to include in the semaphore file path that is written when the boothook runs. The
semaphore file is written to /var/lib/cloud/instances/instance_id/sem/bootper.name.instance.
cmd
The command and arguments that the boothook should execute.
In the example below, the command echo 'OPTIONS="${OPTIONS} --storage-opt dm.basesize=20G"'
>> /etc/sysconfig/docker is executed only once. A semaphore file is written that contains its name.
#cloud-boothook
cloud-init-per once docker_options echo 'OPTIONS="${OPTIONS} --storage-opt
dm.basesize=20G"' >> /etc/sysconfig/docker
The semaphore file records the exit code of the command and a UNIX timestamp for when it was
executed.
[ec2-user ~]$ cat /var/lib/cloud/instances/i-0c7f87d7611b2165e/sem/
bootper.docker_options.instance
Output:
0 1488410363
MIME Multi Part Archive
You can combine multiple user data blocks together into a single user data block called a MIME multi-
part file. For example, you might want to combine a cloud boothook that configures the Docker daemon
with a user data shell script that writes configuration information for the Amazon ECS container agent.
A MIME multi-part file consists of the following components:
• The content type and part boundary declaration: Content-Type: multipart/mixed;
boundary="==BOUNDARY=="
• The MIME version declaration: MIME-Version: 1.0
• One or more user data blocks, which contain the following components:
• The opening boundary, which signals the beginning of a user data block: --==BOUNDARY==
API Version 2014-11-13
47
Amazon EC2 Container Service Developer Guide
Example User Data Scripts
• The content type declaration for the block (for the list of content types, see the Cloud-Init
documentation): Content-Type: text/cloud-boothook; charset="us-ascii"
• The content of the user data, for example, a list of shell commands or cloud-init directives
• The closing boundary, which signals the end of the MIME multi-part file: --==BOUNDARY==--
Example MIME multi-part file
This example MIME multi-part file configures the Docker base device size to 20 GiB and configures the
Amazon ECS container agent to register the instance into the cluster named my-ecs-cluster.
Content-Type: multipart/mixed; boundary="==BOUNDARY=="
MIME-Version: 1.0
--==BOUNDARY==
Content-Type: text/cloud-boothook; charset="us-ascii"
# Set Docker daemon options
cloud-init-per once docker_options echo 'OPTIONS="${OPTIONS} --storage-opt
dm.basesize=20G"' >> /etc/sysconfig/docker
--==BOUNDARY==
Content-Type: text/x-shellscript; charset="us-ascii"
#!/bin/bash
# Set any ECS agent configuration options
echo "ECS_CLUSTER=my-ecs-cluster" >> /etc/ecs/ecs.config
--==BOUNDARY==--
Example Container Instance User Data Configuration
Scripts
The following example user data scripts configure an Amazon ECS container instance at launch.
Ubuntu Container Instance with systemd
This example user data script configures an Ubuntu 16.04 instance to:
• Install Docker
• Create the required iptables rules for IAM roles for tasks
• Create the required directories for the Amazon ECS container agent
• Write the Amazon ECS container agent configuration file
• Write the systemd unit file to monitor the agent
• Enable and start the systemd unit
You can use this script for your own container instances, provided that they are launched from an Ubuntu
16.04 AMI. Be sure to replace the ECS_CLUSTER=default line in the configuration file to specify your own
cluster name, if you are not using the default cluster. For more information about launching container
instances, see Launching an Amazon ECS Container Instance (p. 42).
#!/bin/bash
# Install Docker
apt-get update -y && apt-get install -y docker.io
API Version 2014-11-13
48
Amazon EC2 Container Service Developer Guide
Example User Data Scripts
# Set iptables rules
echo 'net.ipv4.conf.all.route_localnet = 1' >> /etc/sysctl.conf
sysctl -p /etc/sysctl.conf
iptables -t nat -A PREROUTING -p tcp -d 169.254.170.2 --dport 80 -j DNAT --to-destination
127.0.0.1:51679
iptables -t nat -A OUTPUT -d 169.254.170.2 -p tcp -m tcp --dport 80 -j REDIRECT --to-ports
51679
# Write iptables rules to persist after reboot
iptables-save > /etc/iptables/rules.v4
# Create directories for ECS agent
mkdir -p /var/log/ecs /var/lib/ecs/data /etc/ecs
# Write ECS config file
cat << EOF > /etc/ecs/ecs.config
ECS_DATADIR=/data
ECS_ENABLE_TASK_IAM_ROLE=true
ECS_ENABLE_TASK_IAM_ROLE_NETWORK_HOST=true
ECS_LOGFILE=/log/ecs-agent.log
ECS_AVAILABLE_LOGGING_DRIVERS=["json-file","awslogs"]
ECS_LOGLEVEL=info
ECS_CLUSTER=default
EOF
# Write systemd unit file
cat << EOF > /etc/systemd/system/docker-container@ecs-agent.service
[Unit]
Description=Docker Container %I
Requires=docker.service
After=docker.service
[Service]
Restart=always
ExecStart=/usr/bin/docker run --name %i \
--restart=on-failure:10 \
--volume=/var/run:/var/run \
--volume=/var/log/ecs/:/log \
--volume=/var/lib/ecs/data:/data \
--volume=/etc/ecs:/etc/ecs \
--net=host \
--env-file=/etc/ecs/ecs.config \
amazon/amazon-ecs-agent:latest
ExecStop=/usr/bin/docker rm -f %i
[Install]
WantedBy=default.target
EOF
systemctl enable docker-container@ecs-agent.service
systemctl start docker-container@ecs-agent.service
CentOS Container Instance with systemd and SELinux
This example user data script configures a CentOS 7 instance with SELinux enabled to:
• Install Docker
• Create the required iptables rules for IAM roles for tasks
• Create the required directories for the Amazon ECS container agent
• Write the Amazon ECS container agent configuration file
• Write the systemd unit file to monitor the agent
API Version 2014-11-13
49
Amazon EC2 Container Service Developer Guide
Example User Data Scripts
• Enable and start the systemd unit
Note
The docker run command in the systemd unit file below contains the required modifications for
SELinux, including the --privileged flag, and the :Z suffixes to the volume mounts.
You can use this script for your own container instances (provided that they are launched from an
CentOS 7 AMI), but be sure to replace the ECS_CLUSTER=default line in the configuration file to specify
your own cluster name (if you are not using the default cluster). For more information about launching
container instances, see Launching an Amazon ECS Container Instance (p. 42).
#!/bin/bash
# Install Docker
yum install -y docker
# Set iptables rules
echo 'net.ipv4.conf.all.route_localnet = 1' >> /etc/sysctl.conf
sysctl -p /etc/sysctl.conf
iptables -t nat -A PREROUTING -p tcp -d 169.254.170.2 --dport 80 -j DNAT --to-destination
127.0.0.1:51679
iptables -t nat -A OUTPUT -d 169.254.170.2 -p tcp -m tcp --dport 80 -j REDIRECT --to-ports
51679
# Write iptables rules to persist after reboot
iptables-save > /etc/sysconfig/iptables
# Create directories for ECS agent
mkdir -p /var/log/ecs /var/lib/ecs/data /etc/ecs
# Write ECS config file
cat << EOF > /etc/ecs/ecs.config
ECS_DATADIR=/data
ECS_ENABLE_TASK_IAM_ROLE=true
ECS_ENABLE_TASK_IAM_ROLE_NETWORK_HOST=true
ECS_LOGFILE=/log/ecs-agent.log
ECS_AVAILABLE_LOGGING_DRIVERS=["json-file","awslogs"]
ECS_LOGLEVEL=info
ECS_CLUSTER=default
EOF
# Write systemd unit file
cat << EOF > /etc/systemd/system/docker-container@ecs-agent.service
[Unit]
Description=Docker Container %I
Requires=docker.service
After=docker.service
[Service]
Restart=always
ExecStart=/usr/bin/docker run --name %i \
--privileged \
--restart=on-failure:10 \
--volume=/var/run:/var/run \
--volume=/var/log/ecs/:/log:Z \
--volume=/var/lib/ecs/data:/data:Z \
--volume=/etc/ecs:/etc/ecs \
--net=host \
--env-file=/etc/ecs/ecs.config \
amazon/amazon-ecs-agent:latest
ExecStop=/usr/bin/docker rm -f %i
[Install]
WantedBy=default.target
API Version 2014-11-13
50
Amazon EC2 Container Service Developer Guide
Connect to Your Container Instance
EOF
systemctl enable docker-container@ecs-agent.service
systemctl start docker-container@ecs-agent.service
Connect to Your Container Instance
To perform basic administrative tasks on your instance, such as updating or installing software or
accessing diagnostic logs, connect to the instance using SSH. To connect to your instance using SSH, your
container instances must meet the following prerequisites:
• Your container instances need external network access to connect using SSH. If your container
instances are running in a private VPC, they need an SSH bastion instance to provide this access. For
more information, see the Securely connect to Linux instances running in a private Amazon VPC blog
post.
• Your container instances must have been launched with a valid Amazon EC2 key pair. Amazon ECS
container instances have no password, and you use a key pair to log in using SSH. If you did not specify
a key pair when you launched your instance, there is no way to connect to the instance.
• SSH uses port 22 for communication. Port 22 must be open in your container instance security group
for you to connect to your instance using SSH.
Note
The Amazon ECS console first-run experience creates a security group for your container
instances without inbound access on port 22. If your container instances were launched from
the console first-run experience, add inbound access to port 22 on the security group used for
those instances. For more information, see Authorizing Network Access to Your Instances in
the Amazon EC2 User Guide for Linux Instances.
To connect to your container instance
1. Find the public IP or DNS address for your container instance.
a. Open the Amazon ECS console at https://console.aws.amazon.com/ecs/.
b. Select the cluster that hosts your container instance.
c. On the Cluster page, choose ECS Instances.
d. On the Container Instance column, select the container instance to connect to.
e. On the Container Instance page, record the Public IP or Public DNS for your instance.
2. Find the default username for your container instance AMI. The user name for instances launched
with the Amazon ECS-optimized AMI is ec2-user. For Ubuntu AMIs, the default user name is ubuntu.
For CoreOS, the default user name is core.
3. If you are using a macOS or Linux computer, connect to your instance with the following command,
substituting the path to your private key and the public address for your instance:
$ ssh -i /path/to/my-key-pair.pem ec2-user@ec2-198-51-100-1.compute-1.amazonaws.com
If you are using a Windows computer, see Connecting to Your Linux Instance from Windows Using
PuTTY in the Amazon EC2 User Guide for Linux Instances.
Important
If you experience any issues connecting to your instance, see Troubleshooting Connecting to
Your Instance in the Amazon EC2 User Guide for Linux Instances.
API Version 2014-11-13
51
Amazon EC2 Container Service Developer Guide
CloudWatch Logs
Using CloudWatch Logs with Container Instances
You can configure your container instances to send log information to CloudWatch Logs. This enables
you to view different logs from your container instances in one convenient location. This topic helps you
get started using CloudWatch Logs on your container instances that were launched with the Amazon
ECS-optimized AMI.
To send container logs from your tasks to CloudWatch Logs, see Using the awslogs Log Driver (p. 117).
For more information on CloudWatch Logs, see Monitoring Log Files in the Amazon CloudWatch User
Guide.
Topics
•CloudWatch Logs IAM Policy (p. 52)
•Installing the CloudWatch Logs Agent (p. 53)
•Configuring and Starting the CloudWatch Logs Agent (p. 53)
•Viewing CloudWatch Logs (p. 56)
•Configuring CloudWatch Logs at Launch with User Data (p. 57)
CloudWatch Logs IAM Policy
Before your container instances can send log data to CloudWatch Logs, you must create an IAM policy to
allow your container instances to use the CloudWatch Logs APIs, and then you must attach that policy to
the ecsInstanceRole.
To create the ECS-CloudWatchLogs IAM policy
1. Open the IAM console at https://console.aws.amazon.com/iam/.
2. In the navigation pane, choose Policies.
3. Choose Create Policy.
4. On the Create Policy page, choose Create Your Own Policy.
5. On the Review Policy page, enter the following information and choose Create Policy.
a. In the Policy Name field, enter ECS-CloudWatchLogs.
b. In the Policy Document field, paste the following policy.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents",
"logs:DescribeLogStreams"
],
"Resource": [
"arn:aws:logs:*:*:*"
]
}
]
}
API Version 2014-11-13
52
Amazon EC2 Container Service Developer Guide
Installing the CloudWatch Logs Agent
To attach the ECS-CloudWatchLogs policy to your ecsInstanceRole
1. Open the IAM console at https://console.aws.amazon.com/iam/.
2. In the navigation pane, choose Roles.
3. Choose ecsInstanceRole. If the role does not exist, follow the procedures in Amazon ECS Container
Instance IAM Role (p. 210) to create the role.
4. Choose the Permissions tab.
5. In the Managed Policies section, choose Attach Policy.
6. In the Filter box, type ECS-CloudWatchLogs to narrow the available policies to attach.
7. Check the box to the left of the ECS-CloudWatchLogs policy and choose Attach Policy.
Installing the CloudWatch Logs Agent
After you have added the ECS-CloudWatchLogs policy to your ecsInstanceRole, you can install the
CloudWatch Logs agent on your container instances.
Note
This procedure was written for the Amazon ECS-optimized AMI, and may not work on other
operating systems. For information on installing the agent on other operating systems, see
Getting Started with CloudWatch Logs in the Amazon CloudWatch User Guide.
To install the CloudWatch Logs agent
• Run the following command to install the CloudWatch Logs agent.
[ec2-user ~]$ sudo yum install -y awslogs
After you have installed the agent, proceed to the next section to configure the agent.
Configuring and Starting the CloudWatch Logs Agent
The CloudWatch Logs agent configuration file (/etc/awslogs/awslogs.conf) describes the log files
to send to CloudWatch Logs. The agent configuration file's [general] section defines common
configurations that apply to all log streams, and you can add individual log stream sections for each file
on your container instances that you want to monitor. For more information, see CloudWatch Logs Agent
Reference in the Amazon CloudWatch User Guide.
The example configuration file below is configured for the Amazon ECS-optimized AMI, and it provides
log streams for several common log files:
/var/log/dmesg
The message buffer of the Linux kernel.
/var/log/messages
Global system messages.
/var/log/docker
Docker daemon log messages.
/var/log/ecs/ecs-init.log
Log messages from the ecs-init upstart job.
/var/log/ecs/ecs-agent.log
Log messages from the Amazon ECS container agent.
API Version 2014-11-13
53
Amazon EC2 Container Service Developer Guide
Configuring and Starting the CloudWatch Logs Agent
/var/log/ecs/audit.log
Log messages from the IAM roles for tasks credential provider.
You can use the example file below for your Amazon ECS container instances, but you must substitute
the {cluster} and {container_instance_id} entries with the cluster name and container instance ID
for each container instance so that the log streams are grouped by cluster name and separate for each
individual container instance. The procedure that follows the example configuration file has steps to
replace the cluster name and container instance ID placeholders.
[general]
state_file = /var/lib/awslogs/agent-state
[/var/log/dmesg]
file = /var/log/dmesg
log_group_name = /var/log/dmesg
log_stream_name = {cluster}/{container_instance_id}
[/var/log/messages]
file = /var/log/messages
log_group_name = /var/log/messages
log_stream_name = {cluster}/{container_instance_id}
datetime_format = %b %d %H:%M:%S
[/var/log/docker]
file = /var/log/docker
log_group_name = /var/log/docker
log_stream_name = {cluster}/{container_instance_id}
datetime_format = %Y-%m-%dT%H:%M:%S.%f
[/var/log/ecs/ecs-init.log]
file = /var/log/ecs/ecs-init.log.*
log_group_name = /var/log/ecs/ecs-init.log
log_stream_name = {cluster}/{container_instance_id}
datetime_format = %Y-%m-%dT%H:%M:%SZ
[/var/log/ecs/ecs-agent.log]
file = /var/log/ecs/ecs-agent.log.*
log_group_name = /var/log/ecs/ecs-agent.log
log_stream_name = {cluster}/{container_instance_id}
datetime_format = %Y-%m-%dT%H:%M:%SZ
[/var/log/ecs/audit.log]
file = /var/log/ecs/audit.log.*
log_group_name = /var/log/ecs/audit.log
log_stream_name = {cluster}/{container_instance_id}
datetime_format = %Y-%m-%dT%H:%M:%SZ
To configure the CloudWatch Logs agent
1. Back up the existing CloudWatch Logs agent configuration file.
[ec2-user ~]$ sudo mv /etc/awslogs/awslogs.conf /etc/awslogs/awslogs.conf.bak
2. Create a blank configuration file.
[ec2-user ~]$ sudo touch /etc/awslogs/awslogs.conf
3. Open the /etc/awslogs/awslogs.conf file with a text editor, and copy the example file above into it.
4. Install the jq JSON query utility.
API Version 2014-11-13
54
Amazon EC2 Container Service Developer Guide
Configuring and Starting the CloudWatch Logs Agent
[ec2-user ~]$ sudo yum install -y jq
5. Query the Amazon ECS introspection API to find the cluster name and set it to an environment
variable.
[ec2-user ~]$ cluster=$(curl -s http://localhost:51678/v1/metadata | jq -r '.
| .Cluster')
6. Replace the {cluster} placeholders in the file with the value of the environment variable you set in
the previous step.
[ec2-user ~]$ sudo sed -i -e "s/{cluster}/$cluster/g" /etc/awslogs/awslogs.conf
7. Query the Amazon ECS introspection API to find the container instance ID and set it to an
environment variable.
[ec2-user ~]$ container_instance_id=$(curl -s http://localhost:51678/v1/metadata | jq -
r '. | .ContainerInstanceArn' | awk -F/ '{print $2}' )
8. Replace the {container_instance_id} placeholders in the file with the value of the environment
variable you set in the previous step.
[ec2-user ~]$ sudo sed -i -e "s/{container_instance_id}/$container_instance_id/g" /etc/
awslogs/awslogs.conf
To configure the CloudWatch Logs agent region
By default, the CloudWatch Logs agent sends data to the us-east-1 region. If you would like to send
your data to a different region, such as the region that your cluster is located in, you can set the region in
the /etc/awslogs/awscli.conf file.
1. Open the /etc/awslogs/awscli.conf file with a text editor.
2. In the [default] section, replace us-east-1 with the region where you want to view log data.
3. Save the file and exit your text editor.
To start the CloudWatch Logs agent
1. Start the CloudWatch Logs agent with the following command.
[ec2-user ~]$ sudo service awslogs start
Output:
Starting awslogs: [ OK ]
2. Use the chkconfig command to ensure that the CloudWatch Logs agent starts at every system boot.
[ec2-user ~]$ sudo chkconfig awslogs on
API Version 2014-11-13
55
Amazon EC2 Container Service Developer Guide
Viewing CloudWatch Logs
Viewing CloudWatch Logs
After you have given your container instance role the proper permissions to send logs to CloudWatch
Logs, and you have configured and started the agent, your container instance should be sending its log
data to CloudWatch Logs. You can view and search these logs in the AWS Management Console.
Note
New instance launches may take a few minutes to send data to CloudWatch Logs.
To view your CloudWatch Logs data
1. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.
2. Choose Logs in the left navigation.
3. You should see the log groups you configured in Configuring and Starting the CloudWatch Logs
Agent (p. 53).
4. Choose a log group that you would like to view.
5. Choose a log stream to view. The streams are identified by the cluster name and container instance
ID that sent the logs.
API Version 2014-11-13
56
Amazon EC2 Container Service Developer Guide
Configuring CloudWatch Logs at Launch with User Data
Configuring CloudWatch Logs at Launch with User
Data
When you launch an Amazon ECS container instance in Amazon EC2, you have the option of passing
user data to the instance that can be used to perform common automated configuration tasks and even
run scripts after the instance starts. You can pass several types of user data to instances, including shell
scripts, cloud-init directives, and Upstart jobs. You can also pass this data into the launch wizard as
plain text, as a file (this is useful for launching instances via the command line tools), or as base64-
encoded text (for API calls).
The example user data block below performs the following tasks:
• Installs the awslogs package, which contains the CloudWatch Logs agent
• Installs the jq JSON query utility
• Writes the configuration file for the CloudWatch Logs agent and configures the region to send data to
(the region that the container instance is located)
• Gets the cluster name and container instance ID after the Amazon ECS container agent starts and then
writes those values to the CloudWatch Logs agent configuration file log streams
• Starts the CloudWatch Logs agent
• Configures the CloudWatch Logs agent to start at every system boot
Content-Type: multipart/mixed; boundary="==BOUNDARY=="
MIME-Version: 1.0
--==BOUNDARY==
Content-Type: text/x-shellscript; charset="us-ascii"
#!/bin/bash
# Install awslogs and the jq JSON parser
yum install -y awslogs jq
# Inject the CloudWatch Logs configuration file contents
cat > /etc/awslogs/awslogs.conf <<- EOF
[general]
state_file = /var/lib/awslogs/agent-state
[/var/log/dmesg]
file = /var/log/dmesg
log_group_name = /var/log/dmesg
log_stream_name = {cluster}/{container_instance_id}
[/var/log/messages]
file = /var/log/messages
log_group_name = /var/log/messages
log_stream_name = {cluster}/{container_instance_id}
datetime_format = %b %d %H:%M:%S
[/var/log/docker]
file = /var/log/docker
log_group_name = /var/log/docker
log_stream_name = {cluster}/{container_instance_id}
datetime_format = %Y-%m-%dT%H:%M:%S.%f
[/var/log/ecs/ecs-init.log]
file = /var/log/ecs/ecs-init.log.*
log_group_name = /var/log/ecs/ecs-init.log
log_stream_name = {cluster}/{container_instance_id}
datetime_format = %Y-%m-%dT%H:%M:%SZ
API Version 2014-11-13
57
Amazon EC2 Container Service Developer Guide
Configuring CloudWatch Logs at Launch with User Data
[/var/log/ecs/ecs-agent.log]
file = /var/log/ecs/ecs-agent.log.*
log_group_name = /var/log/ecs/ecs-agent.log
log_stream_name = {cluster}/{container_instance_id}
datetime_format = %Y-%m-%dT%H:%M:%SZ
[/var/log/ecs/audit.log]
file = /var/log/ecs/audit.log.*
log_group_name = /var/log/ecs/audit.log
log_stream_name = {cluster}/{container_instance_id}
datetime_format = %Y-%m-%dT%H:%M:%SZ
EOF
--==BOUNDARY==
Content-Type: text/x-shellscript; charset="us-ascii"
#!/bin/bash
# Set the region to send CloudWatch Logs data to (the region where the container instance
is located)
region=$(curl 169.254.169.254/latest/meta-data/placement/availability-zone | sed s'/.$//')
sed -i -e "s/region = us-east-1/region = $region/g" /etc/awslogs/awscli.conf
--==BOUNDARY==
Content-Type: text/upstart-job; charset="us-ascii"
#upstart-job
description "Configure and start CloudWatch Logs agent on Amazon ECS container instance"
author "Amazon Web Services"
start on started ecs
script
exec 2>>/var/log/ecs/cloudwatch-logs-start.log
set -x
until curl -s http://localhost:51678/v1/metadata
do
sleep 1
done
# Grab the cluster and container instance ARN from instance metadata
cluster=$(curl -s http://localhost:51678/v1/metadata | jq -r '. | .Cluster')
container_instance_id=$(curl -s http://localhost:51678/v1/metadata | jq -r '.
| .ContainerInstanceArn' | awk -F/ '{print $2}' )
# Replace the cluster name and container instance ID placeholders with the actual values
sed -i -e "s/{cluster}/$cluster/g" /etc/awslogs/awslogs.conf
sed -i -e "s/{container_instance_id}/$container_instance_id/g" /etc/awslogs/awslogs.conf
service awslogs start
chkconfig awslogs on
end script
--==BOUNDARY==--
If you have created the ECS-CloudWatchLogs policy and attached it to your ecsInstanceRole as described
in CloudWatch Logs IAM Policy (p. 52), then you can add the above user data block to any container
instances that you launch manually, or you can add it to an Auto Scaling launch configuration, and
your container instances that are launched with this user data will begin sending their log data to
CloudWatch Logs as soon as they launch. For more information, see Launching an Amazon ECS Container
Instance (p. 42).
API Version 2014-11-13
58
Amazon EC2 Container Service Developer Guide
Container Instance Draining
Container Instance Draining
There are times when you might need to remove an instance from a cluster; for example, to perform
system updates, update the Docker daemon, or scale down the cluster size. Container instance draining
enables you to remove a container instance from a cluster without impacting tasks in your cluster.
When you set a container instance to DRAINING, Amazon ECS prevents new tasks from being scheduled
for placement on the container instance. If the resources are available, replacement service tasks are
started on other container instances in the cluster. Service tasks on the container instance that are in the
PENDING state are stopped immediately.
Service tasks on the container instance that are in the RUNNING state are stopped and replaced according
to the service's deployment configuration parameters, minimumHealthyPercent and maximumPercent.
• If minimumHealthyPercent is below 100%, the scheduler can ignore desiredCount temporarily during
task replacement. For example, desiredCount is four tasks, a minimum of 50% allows the scheduler to
stop two existing tasks before starting two new tasks. If the minimum is 100%, the service scheduler
can't remove existing tasks until the replacement tasks are considered healthy. If tasks for services that
do not use a load balancer are in the RUNNING state, they are considered healthy. Tasks for services that
use a load balancer are considered healthy if they are in the RUNNING state and the container instance
they are hosted on is reported as healthy by the load balancer.
• The maximumPercent parameter represents an upper limit on the number of running tasks during task
replacement, which enables you to define the replacement batch size. For example, if desiredCount
of four tasks, a maximum of 200% starts four new tasks before stopping the four tasks to be drained
(provided that the cluster resources required to do this are available). If the maximum is 100%, then
replacement tasks can't start until the draining tasks have stopped.
For more information, see Service Definition Parameters (p. 139).
Any PENDING or RUNNING tasks that do not belong to a service are unaffected; you must wait for them to
finish or stop them manually.
A container instance has completed draining when there are no more RUNNING tasks (although the state
remains as DRAINING). You can verify this using the ListTasks operation with the containerInstance
parameter.
When you change the status of a container instance from DRAINING to ACTIVE, the Amazon ECS scheduler
can schedule tasks on the instance again.
Draining Instances
You can use the UpdateContainerInstancesState API action or the update-container-instances-state
command to change the status of a container instance to DRAINING.
The following procedure demonstrates how to set your instance to DRAINING using the AWS Management
Console.
To set your instance to DRAINING using the console
1. Open the Amazon ECS console at https://console.aws.amazon.com/ecs/.
2. In the navigation pane, choose Clusters and select the cluster.
3. Choose ECS Instances and select the check box for the container instances.
4. Choose Actions, Drain instances.
5. After the instances are processed, choose Done.
API Version 2014-11-13
59
Amazon EC2 Container Service Developer Guide
Managing Container Instances Remotely
Managing Container Instances Remotely
You can use the Amazon EC2 Run Command feature to securely and remotely manage the configuration
of your Amazon ECS container instances. Run Command provides a simple way of performing common
administrative tasks without having to log on locally to the instance. You can manage configuration
changes across your clusters by simultaneously executing commands on multiple container instances.
Run Command reports the status and results of each command.
Here are some examples of the types of tasks you can perform with Run Command:
• Install or uninstall packages
• Perform security updates
• Clean up Docker images
• Stop or start services
• View system resources
• View log files
• Perform file operations
This topic covers basic installation of Run Command on the Amazon ECS-optimized AMI and a few simple
use cases, but it is by no means exhaustive. For more information about Run Command, see Manage
Amazon EC2 Instances Remotely in the Amazon EC2 User Guide for Linux Instances.
Topics
•Run Command IAM Policy (p. 60)
•Installing the SSM Agent on the Amazon ECS-optimized AMI (p. 61)
•Using Run Command (p. 61)
Run Command IAM Policy
Before you can send commands to your container instances with Run Command, you must attach an IAM
policy that allows access to the Amazon EC2 Systems Manager (SSM) APIs to the ecsInstanceRole. The
procedure below describes how to attach the AmazonEC2RoleforSSM managed policy to your container
instance role so that instances launched with this role can use Run Command.
To attach the AmazonEC2RoleforSSM policy to your ecsInstanceRole
1. Open the IAM console at https://console.aws.amazon.com/iam/.
2. In the navigation pane, choose Roles.
3. Choose ecsInstanceRole. If the role does not exist, follow the procedures in Amazon ECS Container
Instance IAM Role (p. 210) to create the role.
4. Choose the Permissions tab.
5. In the Managed Policies section, choose Attach Policy.
6. For Filter, type AmazonEC2RoleforSSM to narrow the available policies to attach.
7. Select the check box for AmazonEC2RoleforSSM policy and choose Attach Policy.
API Version 2014-11-13
60
Amazon EC2 Container Service Developer Guide
Installing the SSM Agent on the
Amazon ECS-optimized AMI
Installing the SSM Agent on the Amazon ECS-
optimized AMI
After you have attached the AmazonEC2RoleforSSM policy to your ecsInstanceRole, you can install the
SSM agent on your container instances. The SSM agent processes Run Command requests and configures
the instances that are specified in the request. Use the following procedures to install the SSM agent on
your Amazon ECS-optimized AMI container instances.
To manually install the SSM agent on existing Amazon ECS-optimized AMI container
instances
1. Connect to your container instance. (p. 51)
2. Install the SSM agent RPM. The SSM agent is available in all regions that Amazon ECS is available
in, and each region has its own region-specific download URL; the example command below works
for all regions that Amazon ECS supports, but you can avoid cross-region data transfer costs for the
RPM download by substituting the region of your container instance.
[ec2-user ~]$ sudo yum install -y https://amazon-ssm-us-east-1.s3.amazonaws.com/latest/
linux_amd64/amazon-ssm-agent.rpm
To install the SSM agent on new instance launches with Amazon EC2 user data
• Launch one or more container instances by following the procedure in Launching an Amazon ECS
Container Instance (p. 42), but in Step 10 (p. 44), copy and paste the user data script below
into the User data field. You can also add the commands from this user data script to another
existing script that you may have to perform other tasks, such as setting the cluster name for the
instance to register into.
Note
The user data script below installs the jq JSON parser and uses that to determine the region
of the container instance. Then it downloads and installs the SSM agent.
#!/bin/bash
# Install JQ JSON parser
yum install -y jq
# Get the current region from the instance metadata
region=$(curl -s http://169.254.169.254/latest/dynamic/instance-identity/document | jq
-r .region)
# Install the SSM agent RPM
yum install -y https://amazon-ssm-$region.s3.amazonaws.com/latest/linux_amd64/amazon-
ssm-agent.rpm
Using Run Command
After you have attached the AmazonEC2RoleforSSM policy to your ecsInstanceRole, and installed the
SSM agent on your container instances, you can start using Run Command to send commands to your
container instances. The following topic in the Amazon EC2 User Guide for Linux Instances explains how
to run commands and shell scripts on your instances and view the resulting output:
•Running Shell Scripts with Run Command
API Version 2014-11-13
61
Amazon EC2 Container Service Developer Guide
Using Run Command
For more information about Run Command, see Manage Amazon EC2 Instances Remotely in the Amazon
EC2 User Guide for Linux Instances.
Example: To update container instance software with Run Command
One of the most common use cases for Run Command on Amazon ECS container instances is to update
the instance software on your entire fleet of container instances at once, simultaneously.
1. Attach the AmazonEC2RoleforSSM policy to your ecsInstanceRole. (p. 60)
2. Install the SSM agent on your container instances. For more information, see Installing the SSM
Agent on the Amazon ECS-optimized AMI (p. 61).
3. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.
4. In the left navigation, choose Commands.
5. Choose Run a command.
6. For Command document, choose AWS-RunShellScript.
7. In the Target instances section, choose Select instances and check the container instances to send
the update command to.
8. In the Commands section, enter the command or commands to send to your container instances. In
this example, the command below updates the instance software, but you can send any command
that you want.
$ yum update -y
9. Choose Run to send the command to the specified instances.
10. (Optional) Choose View result to see the results of your command.
11. (Optional) Choose a command from the list of recent commands to view the command output.
12. (Optional) Choose the Output tab, and then choose View Output. The image below shows a snippet
of the container instance output for the yum update command.
API Version 2014-11-13
62
Amazon EC2 Container Service Developer Guide
Starting a Task at Container Instance Launch Time
Note
Unless you configure a command to save the output to an Amazon S3 bucket, then the
command output is truncated at 2500 characters.
Starting a Task at Container Instance Launch Time
Depending on your application architecture design, you may need to run a specific container on every
container instance to deal with operations or security concerns such as monitoring, security, metrics,
service discovery, or logging.
To do this, you can configure your container instances to call the docker run command with the user
data script at launch, or in some init system such as Upstart or systemd. While this method works, it has
some disadvantages because Amazon ECS has no knowledge of the container and cannot monitor the
CPU, memory, ports, or any other resources used. To ensure that Amazon ECS can properly account for
all task resources, create a task definition for the container to run on your container instances. Then, use
Amazon ECS to place the task at launch time with Amazon EC2 user data.
The Amazon EC2 user data script in the following procedure uses the Amazon ECS introspection API to
identify the container instance. Then, it uses the AWS CLI and the start-task command to run a specified
task on itself during startup.
To start a task at container instance launch time
1. If you have not done so already, create a task definition with the container you want to run on your
container instance at launch by following the procedures in Creating a Task Definition (p. 95).
2. Modify your ecsInstanceRole IAM role to add permissions for the StartTask API operation. For
more information, see Amazon ECS Container Instance IAM Role (p. 210).
a. Open the IAM console at https://console.aws.amazon.com/iam/.
b. In the navigation pane, choose Roles.
c. Choose the ecsInstanceRole. If the role does not exist, use the procedure in Amazon ECS
Container Instance IAM Role (p. 210) to create the role and return to this procedure. If the role
does exist, select the role to view the attached policies.
d. In the Inline Policies section, choose Create Role Policy.
e. On the Set Permissions page, choose Custom Policy, Select.
f. For Policy Name, enter StartTask.
g. For Policy Document, copy and paste the following policy and choose Apply Policy.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
API Version 2014-11-13
63
Amazon EC2 Container Service Developer Guide
Starting a Task at Container Instance Launch Time
"Action": [
"ecs:StartTask"
],
"Resource": "*"
}
]
}
3. Launch one or more container instances by following the procedure in Launching an Amazon ECS
Container Instance (p. 42), but in Step 10 (p. 44). Then, copy and paste the MIME multi-part
user data script below into the User data field. Substitute your_cluster_name with the cluster
for the container instance to register into and my_task_def with the task definition to run on the
instance at launch.
Note
The MIME mult-ipart content below uses a shell script to set configuration values and install
packages. It also uses an Upstart job to start the task after the ecs service is running and
the introspection API is available.
Content-Type: multipart/mixed; boundary="==BOUNDARY=="
MIME-Version: 1.0
--==BOUNDARY==
Content-Type: text/text/x-shellscript; charset="us-ascii"
#!/bin/bash
# Specify the cluster that the container instance should register into
cluster=your_cluster_name
# Write the cluster configuration variable to the ecs.config file
# (add any other configuration variables here also)
echo ECS_CLUSTER=$cluster >> /etc/ecs/ecs.config
# Install the AWS CLI and the jq JSON parser
yum install -y aws-cli jq
--==BOUNDARY==
Content-Type: text/text/upstart-job; charset="us-ascii"
#upstart-job
description "Amazon EC2 Container Service (start task on instance boot)"
author "Amazon Web Services"
start on started ecs
script
exec 2>>/var/log/ecs/ecs-start-task.log
set -x
until curl -s http://localhost:51678/v1/metadata
do
sleep 1
done
# Grab the container instance ARN and AWS region from instance metadata
instance_arn=$(curl -s http://localhost:51678/v1/metadata | jq -r '.
| .ContainerInstanceArn' | awk -F/ '{print $NF}' )
cluster=$(curl -s http://localhost:51678/v1/metadata | jq -r '. | .Cluster' | awk -F/
'{print $NF}' )
region=$(curl -s http://localhost:51678/v1/metadata | jq -r '.
| .ContainerInstanceArn' | awk -F: '{print $4}')
# Specify the task definition to run at launch
task_definition=my_task_def
# Run the AWS CLI start-task command to start your task on this container instance
API Version 2014-11-13
64
Amazon EC2 Container Service Developer Guide
Deregister Container Instance
aws ecs start-task --cluster $cluster --task-definition $task_definition --container-
instances $instance_arn --started-by $instance_arn --region $region
end script
--==BOUNDARY==--
4. Verify that your container instances launch into the correct cluster and that your tasks have started.
a. Open the Amazon ECS console at https://console.aws.amazon.com/ecs/.
b. From the navigation bar, choose the region that your cluster is in.
c. In the navigation pane, choose Clusters and select the cluster that hosts your container
instances.
d. On the Cluster page, choose Tasks.
Each container instance you launched should have your task running on it, and the container
instance ARN should be in the Started By column.
If you do not see your tasks, you can log in to your container instances with SSH and check the /
var/log/ecs/ecs-start-task.log file for debugging information.
Deregister a Container Instance
When you are finished with a container instance, you can deregister it from your cluster.
Following deregistration, the container instance is no longer able to accept new tasks. If you have tasks
running on the container instance when you deregister it, these tasks remain running until you terminate
the instance or the tasks stop through some other means. However, these tasks are orphaned (no longer
monitored or accounted for by Amazon ECS). If an orphaned task on your container instance is part of an
Amazon ECS service, then the service scheduler starts another copy of that task, on a different container
instance, if possible. Any containers in orphaned service tasks that are registered with a Classic Load
API Version 2014-11-13
65
Amazon EC2 Container Service Developer Guide
Deregister Container Instance
Balancer or an Application Load Balancer target group are deregistered. They begin connection draining
according to the settings on the load balancer or target group.
If you intend to use the container instance for some other purpose after deregistration, you should stop
all of the tasks running on the container instance before deregistration. This stops any orphaned tasks
from consuming resources.
Important
Because each container instance has unique state information, they should not be deregistered
from one cluster and re-registered into another. To relocate container instance resources, we
recommend that you terminate container instances from one cluster and launch new container
instances with the latest Amazon ECS-optimized AMI in the new cluster. For more information,
see Terminate Your Instance in the Amazon EC2 User Guide for Linux Instances and Launching an
Amazon ECS Container Instance (p. 42).
Deregistering a container instance removes the instance from a cluster, but it does not terminate the
EC2 instance. If you are finished using the instance, be sure to terminate it in the Amazon EC2 console to
stop billing. For more information, see Terminate Your Instance in the Amazon EC2 User Guide for Linux
Instances.
Note
If you terminate a running container instance with a connected Amazon ECS container agent,
the agent automatically deregisters the instance from your cluster. Stopped container instances
or instances with disconnected agents are not automatically deregistered when terminated.
To deregister a container instance
1. Open the Amazon ECS console at https://console.aws.amazon.com/ecs/.
2. From the navigation bar, choose the region that your container instance is registered in.
3. In the navigation pane, choose Clusters and select the cluster that hosts your container instance.
4. On the Cluster : name page, choose ECS Instances.
5. Choose the container instance ID that to deregister.
6. On the Container Instance : id page, choose Deregister.
7. Review the deregistration message, and choose Yes, Deregister.
8. If you are finished with the container instance, terminate the underlying Amazon EC2 instance. For
more information, see Terminate Your Instance in the Amazon EC2 User Guide for Linux Instances.
API Version 2014-11-13
66
Amazon EC2 Container Service Developer Guide
Deregister Container Instance
Note
If your instance is maintained by an Auto Scaling group or AWS CloudFormation stack,
terminate the instance by updating the Auto Scaling group or AWS CloudFormation stack.
Otherwise, the Auto Scaling group re-creates the instance after you terminate it.
API Version 2014-11-13
67
Amazon EC2 Container Service Developer Guide
Installing the Amazon ECS Container Agent
Amazon ECS Container Agent
The Amazon ECS container agent allows container instances to connect to your cluster. The Amazon
ECS container agent is included in the Amazon ECS-optimized AMI, but you can also install it on any EC2
instance that supports the Amazon ECS specification. The Amazon ECS container agent is only supported
on EC2 instances.
Note
The source code for the Amazon ECS container agent is available on GitHub. We encourage you
to submit pull requests for changes that you would like to have included. However, Amazon Web
Services does not currently provide support for running modified copies of this software.
Topics
•Installing the Amazon ECS Container Agent (p. 68)
•Amazon ECS Container Agent Versions (p. 71)
•Updating the Amazon ECS Container Agent (p. 73)
•Amazon ECS Container Agent Configuration (p. 79)
•