Traefik & AWS ECS

A Story of Labels & Elastic Containers

Attach labels to your ECS containers and let Traefik do the rest!

Configuration Examples

Configuring ECS provider

Enabling the ECS provider:

File (YAML)

providers:
  ecs: {}

File (TOML)

[providers.ecs]

CLI

--providers.ecs=true

Policy

Traefik needs the following policy to read ECS information:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "TraefikECSReadAccess",
            "Effect": "Allow",
            "Action": [
                "ecs:ListClusters",
                "ecs:DescribeClusters",
                "ecs:ListTasks",
                "ecs:DescribeTasks",
                "ecs:DescribeContainerInstances",
                "ecs:DescribeTaskDefinition",
                "ec2:DescribeInstances"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}

Provider Configuration

autoDiscoverClusters

Optional, Default=false

Search for services in cluster list.

• If set to true service discovery is disabled on configured clusters, but enabled for all other clusters.
• If set to false service discovery is enabled on configured clusters only.

File (YAML)

providers:
  ecs:
    autoDiscoverClusters: true
    # ...

File (TOML)

[providers.ecs]
  autoDiscoverClusters = true
  # ...

CLI

--providers.ecs.autoDiscoverClusters=true
# ...

clusters

Optional, Default=[“default”]

Search for services in cluster list.

File (YAML)

providers:
  ecs:
    clusters:
      - default
    # ...

File (TOML)

[providers.ecs]
  clusters = ["default"]
  # ...

CLI

--providers.ecs.clusters=default
# ...

exposedByDefault

Optional, Default=true

Expose ECS services by default in Traefik.

If set to false, services that do not have a traefik.enable=true label are ignored from the resulting routing configuration.

File (YAML)

providers:
  ecs:
    exposedByDefault: false
    # ...

File (TOML)

[providers.ecs]
  exposedByDefault = false
  # ...

CLI

--providers.ecs.exposedByDefault=false
# ...

defaultRule

Optional, Default=Host(`{{ normalize .Name }}`)

The defaultRule option defines what routing rule to apply to a container if no rule is defined by a label.

It must be a valid Go template, and can use sprig template functions. The container service name can be accessed with the Name identifier, and the template has access to all the labels defined on this container.

File (YAML)

providers:
  ecs:
    defaultRule: "Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
    # ...

File (TOML)

[providers.ecs]
  defaultRule = "Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
  # ...

CLI

--providers.ecs.defaultRule=Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)
# ...

refreshSeconds

Optional, Default=15

Polling interval (in seconds).

File (YAML)

providers:
  ecs:
    refreshSeconds: 15
    # ...

File (TOML)

[providers.ecs]
  refreshSeconds = 15
  # ...

CLI

--providers.ecs.refreshSeconds=15
# ...

Credentials

Optional

If region is not provided, it is resolved from the EC2 metadata endpoint for EC2 tasks. In a FARGATE context it is resolved from the AWS_REGION environment variable.

If accessKeyID and secretAccessKey are not provided, credentials are resolved in the following order:

• Using the environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN.
• Using shared credentials, determined by AWS_PROFILE and AWS_SHARED_CREDENTIALS_FILE, defaults to default and ~/.aws/credentials.
• Using EC2 instance role or ECS task role

File (YAML)

providers:
  ecs:
    region: us-east-1
    accessKeyID: "abc"
    secretAccessKey: "123"
    # ...

File (TOML)

[providers.ecs]
  region = "us-east-1"
  accessKeyID = "abc"
  secretAccessKey = "123"

CLI

--providers.ecs.region="us-east-1"
--providers.ecs.accessKeyID="abc"
--providers.ecs.secretAccessKey="123"
# ...