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.

Architecture Overview

In a standard ECS deployment, the AWS Application Load Balancer (ALB) routes incoming traffic directly to the application container running within an ECS Task:

client → AWS ALB → application / ECS task

While this architecture is simple and efficient, it lacks advanced capabilities for traffic inspection, protocol transformation, observability, and enforcement of security policies.

An Envoy proxy sidecar is introduced into the ECS task to address these limitations. With this setup, the Envoy proxy acts as a transparent intermediary between the ALB and the application container. The new traffic flow becomes:

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

In this architecture:

• The ALB forwards traffic to the Envoy proxy, which is now the registered target in the ALB’s target group.

• The Envoy proxy handles incoming requests, applies necessary transformations or inspections, and forwards them to the local application container.

• The sidecar supports HTTP/1.1, HTTP/2, gRPC, and TLS communication, enabling robust protocol support and secure traffic handling.

• It also enables detailed observability and reporting by capturing headers, body, and trailer data, which can be sent to a telemetry platform for monitoring and analysis.

This architecture allows for minimal changes to application code while unlocking enhanced traffic control, debugging, and monitoring capabilities through Envoy’s rich feature set.

---

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:

Variable	Example Value	Purpose
TA_APP_PORT	443	Port your application listens on
TA_ENVOY_LISTENER_PORT	8443	Port Envoy listens on for incoming traffic
TA_APP_HOST	localhost	Hostname or IP address of the application
TA_REPORTING_HOST	<TPA_DOMAIN>	Hostname or IP of the Traceable Platform Agent
TA_REPORTING_PORT	5443	Port used to report data to TPA
TA_OBSERVABILITY_MODE	true	Enables traffic observability to TPA
TA_SERVICE_NAME	ext_proc	Logical name used for traffic categorization

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.

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

Variable	Default	Description
TA_ENVOY_ADMIN_PORT	9001	Envoy admin interface for debugging
TA_ENVOY_LISTENER_PORT	443	Port on which the Envoy proxy listens
TA_SERVICE_TIMEOUT	0.2s	Timeout for ext_proc filter request
TA_ENVIRONMENT	—	Overrides TPA environment (optional)
TA_SERVICE_NAME	ext_proc	Agent service name
TA_FAILURE_MODE_ALLOW	true	Allows fallback if connection fails. Allowed values: true, false
TA_MESSAGE_TIMEOUT	0.2s	Timeout per message in sync mode
TA_HTTP_REQUEST_HEADER_PROCESSING_MODE	SEND	Controls if request headers are sent. Allowed values: SEND, SKIP
TA_HTTP_REQUEST_BODY_PROCESSING_MODE	STREAMED	Request body streaming options. Allowed values: STREAMED, BUFFERED, BUFFERED_PARTIAL, NONE
TA_HTTP_REQUEST_TRAILER_PROCESSING_MODE	SKIP	Controls if request trailers are sent. Allowed values: SEND, SKIP
TA_HTTP_RESPONSE_HEADER_PROCESSING_MODE	SEND	Controls if response headers are sent. Allowed values: SEND, SKIP
TA_HTTP_RESPONSE_BODY_PROCESSING_MODE	STREAMED	Controls if response body is streamed. Allowed values: STREAMED, BUFFERED, BUFFERED_PARTIAL, NONE
TA_HTTP_RESPONSE_TRAILER_PROCESSING_MODE	SKIP	Controls if response trailers are sent. Allowed values: SEND, SKIP
TA_ALLOW_MODE_OVERRIDE	false	Allows TME to override filter modes. Allowed values: true, false
TA_OBSERVABILITY_MODE	true	Enables real-time streaming to TPA. Allowed values: true, false
TA_UPSTREAM_CLUSTER_CONNECT_TIMEOUT	2s	Timeout for upstream connections
TA_APP_HOST	127.0.0.1	Backend application host
TA_APP_PORT	8443	Backend application port
TA_UPSTREAM_USE_TLS	true	Enables TLS to upstream
TA_USE_DOWNSTREAM_PROTOCOL_CONFIG	false	Preserves client protocol for upstream
TA_ALPN_PROTOCOLS	h2,http/1.1	Supported protocols (can be customized)
TA_REPORTING_HOST	127.0.0.1	TPA endpoint
TA_REPORTING_PORT	5443	Port used to report to TPA
TA_TPA_CLUSTER_CONNECT_TIMEOUT	2s	TPA connection timeout
TA_ENVOY_DEBUG_LEVEL	info	Logging verbosity for Envoy
TA_TPA_CERT_TRUST_CHAIN_VERIFICATION	VERIFY_TRUST_CHAIN	Certificate verification for TPA. Allowed values: VERIFY_TRUST_CHAIN, ACCEPT_UNTRUSTED
TA_TPA_TRUSTED_CA	—	Trusted CA for TPA (base64-encoded secret)
TA_UPSTREAM_CERT_TRUST_CHAIN_VERIFICATION	VERIFY_TRUST_CHAIN	Certificate verification for upstream. Allowed values: VERIFY_TRUST_CHAIN, ACCEPT_UNTRUSTED
TA_UPSTREAM_TRUSTED_CA	—	Trusted CA for upstream (base64-encoded secret)

---

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.