Back to all patterns

Table of Contents

About

Development Tool

cloudformation

Type

pattern
Report an issue with this pattern

Amazon ECS task definition with a custom entrypoint command

How to run a custom command inside of a container image. How to override the default entrypoint, and pass custom parameters to the entrypoint.

Nathan Peck
Nathan Peck
Senior Developer Advocate at AWS

The following snippets show how to create a task definition which runs a custom command when the container image starts up. This can be especially useful when overriding the existing entrypoint command in a generic image, such as when running a background batch job.

Example: Custom Alpine image to run ping

The following task defintions launch a standard Alpine Linux container and the task definition tells ECS to run the ping command inside the container:

File: task-definition.yml Language: yml 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

AWSTemplateFormatVersion: '2010-09-09'
Description: An example task definition which has a custom entrypoint
             and command that overrides the default container image entrypoint

Resources:
  PingTaskDefinition:
    Type: AWS::ECS::TaskDefinition
    Properties:
      Family: alpine-ping
      Cpu: 256
      Memory: 128
      ContainerDefinitions:
        - Name: alpine-ping
          Image: public.ecr.aws/docker/library/alpine:latest
          Essential: true
          EntryPoint:
            - ping

          # Note that separate command line arguments must be
          # expressed as items in an array, otherwise they will
          # all by stuffed into the first argument passed to the
          # entrypoint
          Command:
            - "-c"
            - '4'
            - amazon.com

Deploy the CloudFormation template above by using the AWS CloudFormation web console. Alternatively you can deploy from the command line with:

aws cloudformation deploy \
   --stack-name sample-task-definition \
   --template-file task-definition.yml
File: task-definition.json Language: json 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

{
  "containerDefinitions": [
    {
      "memory": 32,
      "essential": true,
      "entryPoint": [
        "ping"
      ],
      "name": "alpine-ping",
      "readonlyRootFilesystem": true,
      "image": "public.ecr.aws/docker/library/alpine:latest",
      "command": [
        "-c",
        "4",
        "amazon.com"
      ],
      "cpu": 16
    }
  ],
  "family": "alpine-ping"
}

In the ECS console, click “Create new task definition with JSON” and paste the JSON into the task definition editor.

Alternatively you can download the JSON file and pass it as a parameter to the AWS CLI:

aws ecs register-task-definition \
  --cli-input-json file://task-definition.json

Example: Custom load test container

With this snippet you can create a custom load test container that utilizes hey , and then pass commands to it to configure how many requests to send, and which URL to send them too.

First define a custom image that has the desired entrypoint already set, but no commands:

FROM public.ecr.aws/amazonlinux/amazonlinux:latest
RUN curl https://hey-release.s3.us-east-2.amazonaws.com/hey_linux_amd64 -o /usr/bin/hey && chmod +x /usr/bin/hey
ENTRYPOINT [ "/usr/bin/hey" ]

Next create a task definition that keeps the existing entrypoint from the image, but sets a custom command to run against that entrypoint:

File: load-test-task-definition.yml Language: yml 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

AWSTemplateFormatVersion: '2010-09-09'
Description: An example task definition which has a custom entrypoint
             and command that overrides the default container image entrypoint

Resources:
  HeyLoadTestTaskDefinition:
    Type: AWS::ECS::TaskDefinition
    Properties:
      Family: hey-load-test
      Cpu: 256
      Memory: 128
      ContainerDefinitions:
        - Name: hey

          # Example URI of the image from the Dockerfile above
          Image: 012345678910.dkr.ecr.us-west-2.amazonaws.com/test-suite/hey:latest
          Essential: true

          # Keep the existing entrypoint but just pass a custom command
          Command:
            # Send 100 concurrent requests at a time
            - '-c'
            - '100'
            # Send 100,000 total requests
            - '-n'
            - '100000'
            # URI to send to
            - http://your-uri-here

The resulting task definition can now be launched with ECS RunTask API to start a containerized instance of hey with the given load test parameters.

See Also