How do I create and use custom AMIs in Amazon ECS?

Last updated: 2022-04-15

To create a custom AMI for use with Amazon ECS, do the following:

1. Create an AMI.
2. Install Docker for your operating system.
3. Install the ecs-init package.
4. Enable the ECS service and confirm that the ECS container agent is active.
   
5. Clean up the image for future use.
6. Create a new Amazon Elastic Compute Cloud (Amazon EC2) image.
7. Launch an Amazon ECS Linux container instance and add the required UserData when running the instance to configure the ecs.config file.

There are three options for creating an AMI:

• To create a customized AMI based on the Amazon Linux ECS optimized AMI, use the ECS-optimized AMI Build Recipes with Hashicorp Packer to create the image.
• Use the EC2 Image Builder service to help you build and manage the maintenance of your images.
• Launch an Amazon Elastic Compute Cloud (Amazon EC2) instance, and then configure the instance to include the components required for ECS. To create an AMI with ECS requirements built in, and on the AMI that you want your ECS AMI to be based on, see How do I launch an EC2 instance from a custom Amazon Machine Image (AMI)? After the instance is running, see Connect to your Linux instance using an SSH client.

To install Docker for your operating system and system architecture, see Install Docker Engine.

1.    Download the Amazon ecs-int package for CentOS, SUSE Enterprise Server, or RHEL by running one of the following commands:

Note: Replace region with the AWS Region where you have launched the instance in.

For x86_64 CentOS 7 / 8, SUSE Enterprise Server 15, or RHEL 7:

$ curl -o amazon-ecs-init.rpm https://s3.<region>.amazonaws.com/amazon-ecs-agent-<region>/amazon-ecs-init-latest.x86_64.rpm

For aarch64 CentOS 7 / 8 or RHEL 7:

$ curl -o amazon-ecs-init.rpm https://s3.<region>.amazonaws.com/amazon-ecs-agent-<region>/amazon-ecs-init-latest.aarch64.rpm

2.    Install the rpm package that you downloaded for your instance by running one of the following commands:

For rpm packages for CentOS 7 / 8, and RHEL 7:

$ sudo yum install -y ./amazon-ecs-init.rpm

For rpm packages for SUSE Enterprise Server 15:

$ sudo zypper install -y --allow-unsigned-rpm ./amazon-ecs-init.rpm

1.    To enable the ECS service, run the following command:

$ sudo systemctl enable --now ecs

2.    Confirm that the ECS service is enabled and the ECS container agent is active by running the following command:

$ sudo systemctl status ecs

$ sudo docker ps

The outputs look similar to the following:

ecs.service - Amazon Elastic Container Service - container agent
     Loaded: loaded (/lib/systemd/system/ecs.service; enabled; vendor preset: enabled)
     Active: active (running) since Tue 2022-02-22 08:39:02 UTC; 11min ago

CONTAINER ID   IMAGE                            COMMAND    CREATED         STATUS                   PORTS     NAMES
108cfb8a10d2   amazon/amazon-ecs-agent:latest   "/agent"   9 minutes ago   Up 9 minutes (healthy)             ecs-agent

1.    To clean up the image for future use, stop the ecs-init package and Docker processes by running the following commands:

$ sudo systemctl stop ecs
$ sudo systemctl stop docker

2.    Remove all the log files from the current instance to prevent preserving them when saving the image. Use the example script in Security best practices for EC2 Image Builder to clean up the various files from the instance.

3.    To clean up the ECS specific data, run the following commands:

$ sudo rm -rf /var/log/ecs/*
$ sudo rm /var/lib/ecs/data/agent.db

Use your configured image from the previous step to create a new image by running the following command:

$ aws ec2 create-image --description "My ECS Image" --instance-id 
i-012345678910 --name Custom-ECS-Image --reboot

The output looks similar to the following:

{
    "ImageId": "ami-01234567890101"
}

To launch an instance, see Launching an Amazon ECS Linux container instance.

Then, using your new AMI, be sure the UserData contains the command to write to the ecs.config file by running the following command: Note: Replace your_cluster_name with the name of your cluster.

#!/bin/bash
echo ECS_CLUSTER=your_cluster_name >> /etc/ecs/ecs.config