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

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

  3. From the console dashboard, choose Launch Instance.

  4. On the Choose an Amazon Machine Image (AMI) page, complete the following steps:

    1. Choose Community AMIs.

    2. Choose an AMI for your container instance. You can choose the Amazon ECS-optimized Amazon Linux 2 AMI, or another operating system, such as CoreOS or Ubuntu. If you do not choose an Amazon ECS-optimized AMI, you must follow the procedures in Installing the Amazon ECS Container Agent.

      Note

      For more information about Amazon ECS-specific CoreOS installation instructions, see Running CoreOS Container Linux with AWS EC2 Container Service.

      To use the Amazon ECS-optimized Amazon Linux 2 AMI, type amzn2-ami-ecs-hvm-2.0 in the Search community AMIs field and press the Enter key. Choose Select next to the amzn2-ami-ecs-hvm-2.0.20190510-x86_64-ebs AMI.

      The following table lists the current Amazon ECS-optimized Amazon Linux 2 AMI IDs by Region.

      Region AMI ID
      us-east-2 ami-012ca23958772cf72
      us-east-1 ami-00cf4737e238866a3
      us-west-1 ami-06d87f0156b1d4407
      us-west-2 ami-0a9f5be2a016dccad
      ap-east-1 ami-067f4f7124e746edd
      ap-northeast-1 ami-0e52aad6ac7733a6a
      ap-northeast-2 ami-08834c8c57e502d6d
      ap-south-1 ami-04322e867758d97a8
      ap-southeast-1 ami-0047bfdb16f1f6781
      ap-southeast-2 ami-09475847322e5566f
      ca-central-1 ami-0498c464ec4d2ba83
      eu-west-1 ami-0c5abd45f676aab4f
      eu-west-1 ami-0c5abd45f676aab4f
      eu-west-2 ami-0204aa6a92a54561e
      eu-west-3 ami-07273195833e4f20c
      eu-central-1 ami-096a38c97b80cd8ec
      eu-north-1 ami-0dddc4daca44e6e99
      sa-east-1 ami-00d851648873aaabc
      us-gov-east-1 ami-06473be43b0f77600
      us-gov-west-1 ami-607c0001

      Note

      The current Amazon ECS-optimized Amazon Linux 2 AMI ID can be retrieved using the AWS CLI with the following command:

      aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2/recommended
  5. 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.

    Choose Next: Configure Instance Details when you are done.

  6. On the Configure Instance Details page, complete the following steps:

    1. Set the Number of instances field depending on how many container instances you want to add to your cluster.

    2. (Optional) To use Spot Instances, for Purchasing option, select the check box next to Request Spot Instances. You also need to set the other fields related to Spot Instances. For more information, see Spot Instance Requests.

      Note

      If you are using Spot Instances and see a Not available message, you may need to choose a different instance type.

    3. For Network, choose the VPC into which to launch your container instance.

    4. For Subnet, choose a subnet to use, or keep the default option to choose the default subnet in any Availability Zone.

    5. 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 not, set this field to Disable.

      Note

      Container instances need external network access to communicate with the Amazon ECS service endpoint, so if your container instances do not have public IP addresses, then they must use network address translation (NAT) to provide this access. For more information, see NAT Gateways in the Amazon VPC User Guide and HTTP Proxy Configuration in this guide. For more information, see Tutorial: Creating a VPC with Public and Private Subnets for Your Clusters.

    6. Select the ecsInstanceRole IAM role value that you created for your container instances in Setting Up with Amazon ECS.

      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.

    7. (Optional) Configure your Amazon ECS container instance with user data, such as the agent environment variables from Amazon ECS Container Agent Configuration. Amazon EC2 user data scripts are executed only one time, when the instance is first launched. The following are common examples of what user data is used for:

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

        #!/bin/bash yum install -y aws-cli aws s3 cp s3://your_bucket_name/ecs.config /etc/ecs/ecs.config
      • Specify tags for your container instance using the ECS_CONTAINER_INSTANCE_TAGS configuration parameter. This creates tags that are associated with Amazon ECS only, they cannot be listed using the Amazon EC2 API.

        Important

        If you launch your container instances using an Amazon EC2 Auto Scaling group, then you should use the ECS_CONTAINER_INSTANCE_TAGS agent configuration parameter to add tags. This is due to the way in which tags are added to Amazon EC2 instances that are launched using Auto Scaling groups.

        #!/bin/bash cat <<'EOF' >> /etc/ecs/ecs.config ECS_CLUSTER=your_cluster_name ECS_CONTAINER_INSTANCE_TAGS={"tag_key": "tag_value"} EOF
      • Specify tags for your container instance and then use the ECS_CONTAINER_INSTANCE_PROPAGATE_TAGS_FROM configuration parameter to propagate them from Amazon EC2 to Amazon ECS

        The following is an example of a user data script that would propagate the tags associated with a container instance, as well as register the container instance with a cluster named your_cluster_name:

        #!/bin/bash cat <<'EOF' >> /etc/ecs/ecs.config ECS_CLUSTER=your_cluster_name ECS_CONTAINER_INSTANCE_PROPAGATE_TAGS_FROM=ec2_instance EOF

      For more information, see Bootstrapping Container Instances with Amazon EC2 User Data.

    8. Choose Next: Add Storage.

  7. On the Add Storage page, configure the storage for your container instance.

    If you are using the Amazon ECS-optimized Amazon Linux 2 AMI, your instance has a single 30 GiB volume configured, which is shared between the operating system and Docker.

    If you are using the 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.

    When done configuring your volumes, choose Next: Add Tags.

  8. On the Add Tags page, specify tags by providing key and value combinations for the container instance. Choose Add another tag to add more than one tag to your container instance. For more information resource tags, see Resources and Tags.

    Choose Next: Configure Security Group when you are done.

  9. On the Configure Security Group page, use a security group to define firewall rules for your container instance. These rules specify which incoming network traffic is delivered to your container instance. All other traffic is ignored. Select or create a security group as follows, and then choose Review and Launch.

  10. 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 using the following steps:

    1. Choose Edit security groups.

    2. On the Configure Security Group page, select the Select an existing security group option.

    3. Select the security group you created for your container instance from the list of existing security groups, and choose Review and Launch.

  11. On the Review Instance Launch page, choose Launch.

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

  13. A confirmation page lets you know that your instance is launching. Choose View Instances to close the confirmation page and return to the console.

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