Envoy Proxy Sidecar for ECS Applications

This guide explains adding an Envoy proxy sidecar to ECS-based applications to help monitor and control traffic. The Envoy sidecar sits between the AWS Application Load Balancer (ALB) and your application container, enabling features like TLS encryption, protocol support (HTTP/1.1, HTTP/2, gRPC), and deep request inspection without changing your application code.

client → AWS ALB → application / ECS task

client → AWS ALB → Envoy proxy sidecar → application / ECS task

Before You Begin

Before you proceed with the instrumentation steps, ensure the following prerequisites are met:

• You have access to the Envoy proxy container image, and permissions to pull it from the appropriate container registry. Contact Traceable support if you need help accessing the image.

• You are familiar with ECS task definitions and how to edit them.

• You have access to modify the AWS Application Load Balancer (ALB) and its target groups.

• The application deployed in ECS is reachable on a defined port.

• You know whether your application’s port is configurable or not.

• You have the Traceable Platform Agent (TPA) installed and accessible, and you know its hostname or IP address.

• You have permission to create or modify secrets in AWS Secrets Manager if you plan to use TLS verification with trusted CAs.

Minimum Required Configuration

To get started quickly, the following minimum set of environment variables must be configured in your ECS task definition to enable basic routing and observability. For a complete list of supported variables and advanced options, see the Configuration Reference section below:

Note

You can expand this configuration later by enabling TLS, header/body capture, and custom trust chains as needed.

Instrumentation Steps

Step 1 — Configure Listener Ports

A listening port is the network port on which an application or service waits to receive incoming traffic. It acts as the entry point for communication between clients and the server.

Depending on whether the application’s listening port is configurable:

• Configurable Application Port: The application allows its listening port to be modified through configuration.

  • Change the application’s port and specify it using the TA_APP_PORT environment variable in the Envoy sidecar.

  • Set TA_ENVOY_LISTENER_PORT as the ALB target group port. This ensures that incoming traffic from the ALB is directed to the Envoy proxy sidecar instead of the application container.

Note

An ALB target group is a logical grouping of resources (such as ECS tasks or EC2 instances) that an AWS Application Load Balancer (ALB) routes traffic to. Each target group is associated with specific ports and health check settings.

• No ALB port changes are needed.

• Non-Configurable Application Port: The application has a fixed listening port that cannot be changed.

  • Modify or create the ALB target group to point to TA_ENVOY_LISTENER_PORT.

  • Set TA_APP_PORT to the application’s existing port in the Envoy sidecar configuration.

Step 2 — Update ECS Task Definition

In the containerDefinitions section of your ECS task definition, add the Envoy sidecar configuration as shown below. You can get the sidecar image from Docker Hub at: traceableai/ecs-envoy-proxy:1.0.0:

{
  "name": "envoy-proxy",
  "image": "<registry>/ecs-envoy-proxy:<tag>",
  "cpu": 0,
  "portMappings": [
    {
      "containerPort": 8443,
      "hostPort": 8443,
      "protocol": "tcp"
    }
  ],
  "essential": true,
  "environment": [
    { "name": "TA_TPA_CLUSTER_CONNECT_TIMEOUT", "value": "2s" },
    { "name": "TA_HTTP_RESPONSE_TRAILER_PROCESSING_MODE", "value": "SKIP" },
    { "name": "TA_SERVICE_NAME", "value": "ext_proc" },
    { "name": "TA_REPORTING_PORT", "value": "5443" },
    { "name": "TA_HTTP_RESPONSE_HEADER_PROCESSING_MODE", "value": "SEND" },
    { "name": "TA_APP_PORT", "value": "443" },
    { "name": "TA_HTTP_REQUEST_HEADER_PROCESSING_MODE", "value": "SEND" },
    { "name": "TA_REPORTING_HOST", "value": "<TPA_DOMAIN/TPA_IP>" },
    { "name": "TA_ENVOY_DEBUG_LEVEL", "value": "info" },
    { "name": "TA_ENVOY_ADMIN_PORT", "value": "9001" },
    { "name": "TA_APP_HOST", "value": "localhost" },
    { "name": "TA_MESSAGE_TIMEOUT", "value": "0.2s" },
    { "name": "TA_ALLOW_MODE_OVERRIDE", "value": "false" },
    { "name": "TA_OBSERVABILITY_MODE", "value": "true" },
    { "name": "TA_FAILURE_MODE_ALLOW", "value": "true" },
    { "name": "TA_UPSTREAM_CLUSTER_CONNECT_TIMEOUT", "value": "2s" },
    { "name": "TA_HTTP_RESPONSE_BODY_PROCESSING_MODE", "value": "STREAMED" },
    { "name": "TA_ENVOY_LISTENER_PORT", "value": "8443" },
    { "name": "TA_SERVICE_TIMEOUT", "value": "0.2s" },
    { "name": "TA_HTTP_REQUEST_TRAILER_PROCESSING_MODE", "value": "SKIP" },
    { "name": "TA_HTTP_REQUEST_BODY_PROCESSING_MODE", "value": "STREAMED" }
  ],
  "logConfiguration": {
    "logDriver": "awslogs",
    "options": {
      "awslogs-group": "/ecs/httpbin-tls",
      "awslogs-create-group": "true",
      "max-buffer-size": "25m",
      "awslogs-region": "us-east-1",
      "awslogs-stream-prefix": "ecs-envoy"
    }
  }
}

Step 3 — Configure Additional Environment Variables

Refer to the Configuration Reference section below to understand and customize the available options. To view the complete list of supported environment variables, go to the Configuration Reference section.

Step 4 — Deploy the ECS Service

Use the modified task definition to create or update your ECS service. When the service is deployed, ECS will launch both the application container and the Envoy proxy container as part of the same task. The Envoy sidecar will automatically intercept and forward incoming traffic to the application, enabling observability and control without requiring any changes to the application code.

Configuration Reference

Configuring Trusted CAs via AWS Secrets Manager

This step is optional and only needed if you want to enforce TLS certificate verification for secure communication. By default, the Envoy proxy does not validate certificates. To improve security—especially in production environments—you can configure trusted Certificate Authorities (CAs) for both upstream services and the Traceable Platform Agent (TPA) using AWS Secrets Manager.

To enable SSL peer certificate verification:

1. Generate the CA certificates.

2. Navigate to AWS Secrets Manager.

3. Create a new secret and encode the certificates as base64.

4. Store the encoded value under a defined secret key.

5. Reference the key from your ECS task definition using TA_UPSTREAM_TRUSTED_CA and TA_TPA_TRUSTED_CA.

Performance Considerations

• Each Envoy proxy sidecar is optimized for up to 200 requests per second.

• If load exceeds this limit, spans may be dropped.

• For high-throughput workloads on a single container, set TA_OBSERVABILITY_MODE=false to reduce overhead.

• It is recommended to horizontally scale Envoy containers rather than increasing load on a single instance.