Amazon ECS provider

Discovers ECS tasks and emits Traefik configuration.

Source

pkg/provider/ecs/:

• ecs.go — provider definition and AWS API loop.
• config.go — task-tag / container-definition → dynamic configuration.
• awsclient.go — wraps aws-sdk-go-v2/service/ecs and service/ec2.
• ecs_test.go — fixture-driven mapping tests.

Configuration

providers:
  ecs:
    region: eu-west-1
    accessKeyID: ...
    secretAccessKey: ...
    autoDiscoverClusters: true
    healthyTasksOnly: true
    exposedByDefault: false
    refreshSeconds: 15
    constraints: 'Tag(`environment`, `production`)'

Authentication follows the AWS SDK chain — environment variables, IAM instance role, IRSA, or explicit static credentials. The recommended pattern is to give the Traefik task an IAM role with the minimum permissions described below and rely on the SDK to find them.

Required IAM permissions (read-only):

ecs:ListClusters
ecs:DescribeClusters
ecs:ListTasks
ecs:DescribeTasks
ecs:ListContainerInstances
ecs:DescribeContainerInstances
ecs:DescribeTaskDefinition
ec2:DescribeInstances

Behavior

graph LR
    Conf --> Init
    Init -->|list/describe| ECS[ECS API]
    Init -->|describe instances| EC2[EC2 API]
    ECS --> Build[config.go]
    EC2 --> Build
    Build --> Emit[dynamic.Message]

The provider polls every refreshSeconds (default 15). For each cluster it lists tasks, fetches their task definitions, and resolves container-instance addresses (Bridge / EC2 / Fargate / ENI).

Labels

Service labels live on the task definition's container definition:

{
  "name": "web",
  "dockerLabels": {
    "traefik.enable": "true",
    "traefik.http.routers.web.rule": "Host(`web.example.com`)",
    "traefik.http.services.web.loadbalancer.server.port": "8080"
  }
}

Same convention as the Docker provider. The provider chooses the right IP/port for the task's networking mode:

• Bridge / Host — uses the EC2 instance's IP plus the host port mapping.
• awsvpc / Fargate — uses the ENI's IP plus the container port.

Health-state filtering

healthyTasksOnly: true (default) drops tasks that ECS reports as unhealthy. With it false, Traefik will route to tasks while their health checks are still resolving.

Cluster auto-discovery

autoDiscoverClusters: true (default) lists every cluster in the region. With it false, the clusters field is consulted as the explicit list.

Tests

• pkg/provider/ecs/ecs_test.go and config_test.go — table-driven mapping.
• (Integration tests are limited because ECS requires a real AWS account; see comments in the test files for how to opt in.)

Practical notes

• For Fargate-only clusters, the EC2 DescribeInstances permission is unnecessary but simpler to grant than to omit conditionally.
• VPC peering / cross-account scenarios require Traefik to be in a network position that can reach the ENIs the provider returns.