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

Short description

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. (Optional) Install AWS Systems Manager Agent (SSM Agent) for ECS.
5. Turn on the ECS service, and then confirm that the ECS container agent is active.
6. Clean up the image for future use.
7. Create a new Amazon Elastic Compute Cloud (Amazon EC2) image.
8. Launch an Amazon ECS Linux container instance, and then add the required UserData when running the instance to configure the ecs.config file.

Resolution

Create an AMI

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 EC2 Image Builder to help you build and manage the maintenance of your images.
• Launch an Amazon EC2 instance, and then configure the instance to include the components required for ECS. To create an AMI with built-in ECS requirements 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.

Install Docker

To install Docker for your operating system and system architecture, see the Install Docker Engine instructions on the Docker website.

Install the ecs-int package

1.    Run the following command to download the Amazon ecs-int package for CentOS, SUSE Enterprise Server, or RHEL:

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

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.    Run one of the following commands to install the rpm package that you downloaded for your instance:

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

(Optional) Install SSM Agent for ECS

To use the Amazon ECS Exec for debugging feature, you must install SSM Agent for Amazon ECS.

1.    Run the following command to download and extract the SSM Agent binaries:

$ mkdir -p ssm-binaries && cd ssm-binaries

2.    Run one of the following commands for CentOS, SUSE Enterprise Server, or RHEL:

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

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

$ curl -o amazon-ssm-agent.tar.gz https://amazon-ssm-<region>.s3.<region>.amazonaws.com/latest/linux_amd64/amazon-ssm-agent-binaries.tar.gz

For aarch64 CentOS 7 / 8 or RHEL 7:

$ curl -o amazon-ssm-agent.tar.gz https://amazon-ssm-<region>.s3.<region>.amazonaws.com/latest/linux_arm64/amazon-ssm-agent-binaries.tar.gz

3.    Run the following command to extract the agent files:

$ tar -xzvf amazon-ssm-agent.tar.gz

4.    Get the SSM Agent version, and then create a directory under /var/lib/ecs/deps/execute-command/bin/. Name the directory with the SSM Agent version. The following is an example command for getting the SSM Agent version:

$ ./amazon-ssm-agent -version  
  
SSM Agent version: 3.2.286.0  
  
$ export SSM_VERSION=3.2.286.0  
  
$ sudo mkdir -p /var/lib/ecs/deps/execute-command/bin/$SSM_VERSION

5.    Run the following commands to copy the SSM Agent binary files to the directory:

$ sudo cp amazon-ssm-agent /var/lib/ecs/deps/execute-command/bin/$SSM_VERSION/amazon-ssm-agent  
  
$ sudo cp ssm-agent-worker /var/lib/ecs/deps/execute-command/bin/$SSM_VERSION/ssm-agent-worker  
  
$ sudo cp ssm-session-worker /var/lib/ecs/deps/execute-command/bin/$SSM_VERSION/ssm-session-worker

6.    Run the following command to copy the TLS certificates for the SSM Agent:

$ sudo mkdir -p /var/lib/ecs/deps/execute-command/certs  
  
$ sudo cp /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem /var/lib/ecs/deps/execute-command/certs/tls-ca-bundle.pem  
  
$ sudo chmod 400 /var/lib/ecs/deps/execute-command/certs/tls-ca-bundle.pem

Turn on the ECS service and confirm that the ECS container agent is active

1.    To turn on the ECS service, run the following command:

$ sudo systemctl enable --now ecs

2.    Run the following command to confirm that the ECS service is turned on and the ECS container agent is active:

$ 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

Clean up the image

1.    To clean up the image for future use, run the following command to stop the ecs-init package and Docker processes:

$ 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

Create a new Amazon EC2 image

Run the following command to use your configured image from the previous step to create a new image:

$ 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"
}

Launch an Instance

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

With your new AMI, run the following command to confirm that the UserData contains the command to write to the ecs.config file:

Note: Replace your_cluster_name with the name of your cluster.

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