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

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).


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.

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, 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.

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

  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):


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:


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.


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. 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 and Amazon ECS Service Scheduler IAM Role 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

  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.


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


    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 Be sure to install the entire suite.

  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)


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.

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.