This page provides an example of an AWS Elastic Container Service (ECS) task definition configured with a sidecar container pattern. This pattern is commonly used to run auxiliary containers alongside your main application container, such as proxies, log collectors, or monitoring agents.

Understanding the Sidecar Pattern in ECS

The sidecar pattern involves deploying two or more containers within the same ECS task. These containers share the same network namespace and can communicate with each other using localhost. In this example, we define a proxy container that acts as a sidecar to the main app container.

ECS Task Definition Structure

The task definition below outlines the configuration for an ECS task. It includes essential parameters like the task role, execution role, and compatibility requirements. The core of the definition lies in the containerDefinitions array, where each container's image, resources, environment variables, and secrets are specified.

Proxy Container Configuration

The proxy container is configured to serve traffic on port 80 and forward requests to the application container at http://app:5000. It also demonstrates how to inject secrets, such as APP_SECRET, from AWS Systems Manager (SSM) Parameter Store.

Application Container Configuration

The app container is the primary application. It is configured with its own memory reservation and also retrieves database credentials (DB_DATABASE, DB_HOST, DB_PASSWORD, DB_USERNAME) from SSM Parameter Store, showcasing secure secret management.

This setup is ideal for scenarios where you need to add cross-cutting concerns like request routing, authentication, or centralized logging without modifying the core application code.

For more information on ECS task definitions, refer to the AWS ECS Developer Guide.

{
  "family": "app-with-sidecar-container",
  "taskRoleArn": "arn:aws:iam::000000000000:role/aws-dev-ecs-task-role",
  "executionRoleArn": "arn:aws:iam::000000000000:role/aws-dev-ecs-exec-role",
  "requiresCompatibilities": [
    "EC2"
  ],
  "containerDefinitions": [
    {
      "name": "proxy",
      "image": "proxy-image:latest",
      "portMappings": [
        {
          "hostPort": 0,
          "protocol": "tcp",
          "containerPort": 80
        }
      ],
      "environment": [
        {
          "name": "APP_URL",
          "value": "http://app:5000"
        }
      ],
      "secrets": [
        {
          "valueFrom": "arn:aws:ssm:eu-west-1:000000000000:parameter/app-with-sidecar-container/dev/APP_SECRET",
          "name": "APP_SECRET"
        }
      ],
      "memoryReservation": 256,
      "stopTimeout": 30,
      "startTimeout": 30,
      "essential": true,
      "links": [
        "app"
      ]
    },
    {
      "name": "app",
      "image": "app-image:latest",
      "memoryReservation": 128,
      "essential": true,
      "secrets": [
        {
          "valueFrom": "arn:aws:ssm:eu-west-1:000000000000:parameter/app-with-sidecar-container/dev/DB_DATABASE",
          "name": "DB_DATABASE"
        },
        {
          "valueFrom": "arn:aws:ssm:eu-west-1:000000000000:parameter/app-with-sidecar-container/dev/DB_HOST",
          "name": "DB_HOST"
        },
        {
          "valueFrom": "arn:aws:ssm:eu-west-1:000000000000:parameter/app-with-sidecar-container/dev/DB_PASSWORD",
          "name": "DB_PASSWORD"
        },
        {
          "valueFrom": "arn:aws:ssm:eu-west-1:000000000000:parameter/app-with-sidecar-container/dev/DB_USERNAME",
          "name": "DB_USERNAME"
        }
      ]
    }
  ]
}