Routing Traffic with Traefik Docker Labels

Solving the Dynamic Routing Problem

In a containerized environment, manually updating a load balancer configuration every time a service scales or a new version deploys is a bottleneck. Traefik solves this by using Service Discovery, where the proxy listens to the Docker socket and automatically configures routes based on labels attached to the containers themselves.

The primary takeaway is that routing logic is decentralized: the infrastructure team defines the Traefik entry point, but the application developer defines the routing rules (Host, Path, Headers) directly in the docker-compose.yml file.

How Label-Based Routing Works

Traefik uses a specific naming convention for labels to identify routers and services. A router is the entity that decides if an incoming request matches a specific rule; if it does, the router forwards the request to the associated service (the container's internal port).

Worked Configuration Example

The following example demonstrates a common scenario: routing traffic to a specific API service based on both the domain name and a path prefix. This configuration assumes you are using Traefik v2.x or v3.x.

services:
  api-service:
    image: my-api:latest
    labels:
      # 1. Enable Traefik for this container
      - "traefik.enable=true"
      # 2. Define the router name and the matching rule
      # Matches requests to api.example.com that start with /v1
      - "traefik.http.routers.api-router.rule=Host(`api.example.com`) && PathPrefix(`/v1`)"
      # 3. Define the entrypoint (e.g., web for port 80)
      - "traefik.http.routers.api-router.entrypoints=web"
      # 4. Specify the internal port the container listens on
      - "traefik.http.services.api-service.loadbalancer.server.port=8080"

Breakdown of the Logic

• traefik.enable=true: By default, Traefik may be configured to ignore containers unless this label is present.
• The Rule: The Host() and PathPrefix() functions are evaluated as a boolean. If both are true, the request is routed. Note the use of backticks (`) inside the labels; these are required by Traefik's rule syntax to denote strings.
• The Port: If a container exposes multiple ports, Traefik cannot guess which one to use. The loadbalancer.server.port label explicitly maps the router to the correct internal port.

Limitations and Common Pitfalls

Regex and Escaping

While Traefik supports regular expressions via the PathRegexp() or HostRegexp() functions, they do not support the full Go regex library in every context. Complex regex patterns often require double-escaping backslashes because the labels are first parsed by Docker/YAML and then by Traefik. If a rule fails to match, simplify the regex to a PathPrefix to isolate the issue.

Case Sensitivity

Host matching is case-insensitive per RFC standards, but PathPrefix and Path matches are case-sensitive. A request to /V1/users will not match a rule defined as PathPrefix(`/v1`).

Middleware Ordering

A frequent mistake is attempting to apply middleware (like rate-limiting or authentication) before the router is fully defined. In Traefik, middleware must be explicitly attached to the router using the traefik.http.routers.<name>.middlewares label. If a middleware is referenced but not created, Traefik may ignore the entire router, resulting in a 404 Not Found.

Verification and Diagnostics

To verify that your labels are being processed correctly, follow these steps:

1. Check Container Status: Run docker ps to ensure the target container is running and the Traefik container is active.
2. Test the Route: Use curl to simulate a request with the expected host header:

   curl -H "Host: api.example.com" http://localhost/v1/test

3. Inspect Logs: If the request fails, check the Traefik logs for configuration errors:

   docker logs <traefik-container-id>

   Look for messages indicating "Configuration error" or "Router not found."

Rollback Procedure

Because these changes are defined in the docker-compose.yml file, rolling back requires reverting the label changes in the file and re-deploying the service:

docker-compose up -d

This triggers a container recreation with the previous label set, which Traefik will detect and apply in real-time.