You are currently viewing How To Create An ECS Container Instance With ECS-optimized AMI Using AWS CLI

How To Create An ECS Container Instance With ECS-optimized AMI Using AWS CLI

  • Post author:
  • Post category:AWS / ECS

How To Create An ECS Container Instance With ECS-optimized AMI Using AWS CLI

Hello Everyone

Welcome to CloudAffaire and this is Debjeet.

In the last AWS blog post, we have discussed ECS Task Definition and its parameters.

In this blog post, we will discuss Container Instances in ECS. We will also create an ECS Container Instance with ECS-optimized AMI using AWS CLI.

What is an ECS Container Instance?

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 using the EC2 launch type, your tasks are placed on your active container instances.

ECS Container Instance Requirement:

  • ECS Container instance must be running the Amazon ECS container agent to register into one of your clusters. If you are using an Amazon ECS-optimized AMI, the agent is already installed. To use a different operating system, install the agent.
  • 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.
  • 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.
  • AWS strongly recommend launching your container instances inside a VPC, because Amazon VPC delivers more control over your network and offers more extensive configuration capabilities.
  • Container instances need access to communicate with the Amazon ECS service endpoint. This can be through an interface VPC endpoint or through your container instances having public IP addresses.
  • The type of Amazon EC2 instance that you choose for your container instances determines the resources available in your cluster.
  • You should not deregister an instance from one cluster and re-register it 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 Amazon Linux 2 AMI in the new cluster.
  • 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 Amazon Linux 2 AMI in your desired cluster.

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

ECS-optimized AMIs:

An ECS Container instance require a modern Linux distribution running at least version 3.10 of the Linux kernel, The Amazon ECS container agent (preferably the latest version) and A Docker daemon running at least version 1.9.0, and any Docker runtime dependencies. The Amazon ECS-optimized AMIs are preconfigured with these requirements and recommendations.

The AMI ID, image name, operating system, container agent version, and runtime version for the different Amazon ECS-optimized AMIs can be programmatically retrieved by querying the Systems Manager Parameter Store API.

ECS Container Instance Draining:

There are times when you might need to remove a container 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. Service tasks on the draining container instance that are in the PENDING state are stopped immediately. If there are container instances in the cluster that are available, replacement service tasks are started on them.

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 AMIs, but you can also install it on any Amazon EC2 instance that supports the Amazon ECS specification. The Amazon ECS container agent is only supported on Amazon EC2 instances.

Note: Tasks using the Fargate launch type are deployed onto infrastructure managed by AWS, so this topic does not apply.

How To Create An ECS Container Instance With ECS-optimized AMI Using AWS CLI:

Step 1: Create a custom VPC for your ECS Container Instance.

Step 2: Create a custom IAM role for your ECS Container Instance.

Step 3: Create your ECS Cluster and Task Definition for ECS Container Instance.

Step 4: Create an ECS Container Instance using ECS-optimized AMIs.

Step 5: Get details of your ECS Container Instance and check your docker application.

Step 6: Cleanup.

Hope you have enjoyed this article, In the next blog post, we will discuss ECS Container Agent.

All the public cloud providers are changing the console user interface rapidly and due to this some of the screenshots used in our previous AWS blogs are no longer relevant. Hence, we have decided that from now onwards most of the demo will be done programmatically. Let us know your feedback on this in the comment section.

To get more details on AWS ECS, please refer below AWS documentation


This Post Has One Comment

  1. Avatar

    Thank you for very useful and interesting post. I’ve created script based on your example with very minor modifications. When I run that script I am getting the following error when calling the RunInstances. Any idea why I am getting this error?
    The “aws iam list-instance-profiles” shows that instance profile exists and valid, see below.

    An error occurred (InvalidParameterValue) when calling the RunInstances operation: Value (arn:aws:iam::619592225065:instance-profile/test9876_RoleInstanceProfile) for parameter iamInstanceProfile.arn is invalid. Invalid IAM Instance Profile ARN

    $ aws iam list-instance-profiles
    “InstanceProfiles”: [
    “Path”: “/”,
    “InstanceProfileName”: “test9876_RoleInstanceProfile”,
    “InstanceProfileId”: “AIPAZAQUTCEUZ7YOZV47P”,
    “Arn”: “arn:aws:iam::619592225065:instance-profile/test9876_RoleInstanceProfile”,
    “CreateDate”: “2021-01-22T04:33:08Z”,
    “Roles”: [
    “Path”: “/”,
    “RoleName”: “test9876_Role”,
    “Arn”: “arn:aws:iam::619592225065:role/test9876_Role”,
    “CreateDate”: “2021-01-22T04:33:05Z”,
    “AssumeRolePolicyDocument”: {
    “Version”: “2008-10-17”,
    “Statement”: [
    “Effect”: “Allow”,
    “Principal”: {
    “Service”: [
    “Action”: “sts:AssumeRole”

Comments are closed.