ECS

Monitor ECS task network traffic with the Alma Packet Sensor sidecar.

Deploy Alma on Amazon ECS to monitor runtime network traffic with zero app code changes.

Alma runs the Packet Sensor as a sidecar container in your ECS tasks.

It captures traffic and forwards it to an Alma Receiver in your VPC.

You get visibility into 95%+ of common application protocols out of the box.

If you’re new to Alma, start with Alma Overview.

Alma Packet Sensor on ECS overview

How it works

When installed, this setup adds:

• Alma Packet Sensor (sidecar) attached to your existing ECS task definitions.

• Alma Receiver (EC2 instance) deployed to receive and process captured packets.

For best performance, deploy the receiver in the same VPC as your tasks.

Use the same subnet when possible.

Prerequisites

• Access to your ECS cluster and task definitions.

• Basic familiarity with ECS task definition structure.

• AWS CLI configured for the target account.

• Terraform v1.3+.

Install (Terraform)

1

1) Identify your VPC and subnet IDs

The Alma Receiver EC2 instance must be deployed in the same VPC as your ECS tasks.

Option A: AWS Console

1. Open the Amazon ECS console.

2. Select your cluster.

3. Select your service.

4. Open the Networking tab.

5. Under Network configuration, note the VPC value.

6. If VPC is not shown, open a Subnet link.

7. The Subnet details page shows the VPC ID at the top.

Option B: AWS CLI

Get a subnet ID from the service:

# List services in a cluster
aws ecs list-services --cluster YOUR_CLUSTER_NAME

# Get one subnet ID from the service
aws ecs describe-services \
  --cluster YOUR_CLUSTER_NAME \
  --services YOUR_SERVICE_NAME \
  --query 'services[0].networkConfiguration.awsvpcConfiguration.subnets[0]' \
  --output text

Get the corresponding VPC ID:

SUBNET_ID=$(
  aws ecs describe-services \
    --cluster YOUR_CLUSTER_NAME \
    --services YOUR_SERVICE_NAME \
    --query 'services[0].networkConfiguration.awsvpcConfiguration.subnets[0]' \
    --output text
)

aws ec2 describe-subnets \
  --subnet-ids "$SUBNET_ID" \
  --query 'Subnets[0].VpcId' \
  --output text

If you provide only a VPC ID, Terraform will auto-select the first available subnet in that VPC.

2

2) Configure Terraform variables

Create or update terraform.tfvars:

# Required: VPC ID (subnet is optional)
alma_receiver_vpc_id    = "vpc-0a1b2c3d4e5f6g7h8" # replace with your VPC ID

# Optional: if empty, a subnet is auto-selected
alma_receiver_subnet_id = ""

# Deploy an Alma Receiver EC2 instance (set false if you already run one)
deploy_alma_receiver = true

After terraform apply, fetch the receiver private IP:

terraform output alma_receiver_private_ip

3

3) Attach the Packet Sensor sidecar to your ECS task definition

You have two options.

Option A: Use the automation script

Use this when your Terraform builds containers via jsonencode.

The script appends the Alma sidecar container to your existing task definition.

It also creates a backup of main.tf.

Option B: Add the sidecar manually

Append the sidecar to container_definitions.

Example:

resource "aws_ecs_task_definition" "your_task" {
  family = "your-app"
  # ... other configuration

  container_definitions = jsonencode([
    {
      name  = "your-app"
      image = "your-image:latest"
      # ... your app container config
    },
    {
      name      = "alma-packet-sensor"
      image     = "public.ecr.aws/r1b5k6e6/alma-packet-sensor:0.0.1"
      essential = false
      environment = [
        {
          name  = "CAPTURE_BPF_FILTER"
          value = "tcp"
        },
        {
          name  = "SERVER_ADDRESS"
          value = var.deploy_alma_receiver && var.alma_receiver_vpc_id != "" ?
            aws_instance.alma_receiver[0].private_ip :
            var.alma_server_address
        }
      ]
    }
  ])
}

Alternative: use an existing receiver

Use this when you already have a receiver running.

Prefer a stable address (private DNS or a static private IP). Avoid hardcoding an ephemeral IP.

{
  name      = "alma-packet-sensor"
  image     = "public.ecr.aws/r1b5k6e6/alma-packet-sensor:0.0.1"
  essential = false
  environment = [
    { name = "CAPTURE_BPF_FILTER", value = "tcp" },
    { name = "SERVER_ADDRESS", value = "10.10.2.124" }
  ]
}

Validate

1. Deploy a new task revision with the sidecar attached.

2. Confirm the service stabilises and tasks are running.

3. Confirm the receiver instance is reachable from the task subnet.