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

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.

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 http://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.

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 a group for administrators

  1. Sign in to the Identity and Access Management (IAM) console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Groups, and then choose Create New Group.

  3. For Group Name, type a name for your group, such as Administrators, and then choose Next Step.

  4. In the list of policies, select the check box next to the AdministratorAccess policy. You can use the Filter menu and the Search box to filter the list of policies.

  5. Choose Next Step, and then choose Create Group.

Your new group is listed under Group Name.

To create an IAM user for yourself, add the user to the administrators group, and create a password for the user

  1. In the navigation pane, choose Users, and then choose Create New Users.

  2. In box 1, type a user name.

  3. Clear the check box next to Generate an access key for each user.

  4. Choose Create.

  5. In the list of users, choose the name (not the check box) of the user you just created. You can use the Search box to search for the user name.

  6. Choose the Groups tab and then choose Add User to Groups.

  7. Select the check box next to the administrators group. Then choose Add to Groups.

  8. Choose the Security Credentials tab. Under Sign-In Credentials, choose Manage Password.

  9. Select Assign a custom password. Then type a password in the Password and Confirm Password boxes. When you are finished, choose Apply.

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:

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

    Region NameRegion
    US East (N. Virginia)us-east-1
    US West (N. California)us-west-1
    US West (Oregon)us-west-2
    EU (Ireland)eu-west-1
    EU (Frankfurt)eu-central-1
    Asia Pacific (Tokyo)ap-northeast-1
    Asia Pacific (Singapore)ap-southeast-1
    Asia Pacific (Sydney)ap-southeast-2
  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.

  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.

You can also choose to use Amazon ECS through the AWS 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.