Overview

    Let’s zoom in on Traefik’s architecture and talk about the components that enable the routes to be created.

    First, when you start Traefik, you define entrypoints (in their most basic forms, they are port numbers). Then, connected to these entrypoints, analyze the incoming requests to see if they match a set of rules. If they do, the router might transform the request using pieces of before forwarding them to your services.

    • Providers discover the services that live on your infrastructure (their IP, health, …)
    • listen for incoming traffic (ports, …)
    • Routers analyse the requests (host, path, headers, SSL, …)
    • forward the request to your services (load balancing, …)
    • Middlewares may update the request or make decisions based on the request (authentication, rate limiting, headers, …)

    Below is an example of a full configuration file for the file provider that forwards http://example.com/whoami/ requests to a service reachable on http://private/whoami-service/. In the process, Traefik will make sure that the user is authenticated (using the ).

    Static configuration:

    File (YAML)

    File (TOML)

    1. [entryPoints]
    2.   [entryPoints.web]
    3.     # Listen on port 8081 for incoming requests
    4.     address = ":8081"
    6. [providers]
    7.   # Enable the file provider to define routers / middlewares / services in file
    8.   [providers.file]
    9.     directory = "/path/to/dynamic/conf"

    CLI

    1. # Listen on port 8081 for incoming requests
    2. --entryPoints.web.address=:8081
    4. # Enable the file provider to define routers / middlewares / services in file
    5. --providers.file.directory=/path/to/dynamic/conf

    Dynamic configuration:

    YAML

    1. # http routing section
    2. http:
    3.   routers:
    4.     # Define a connection between requests and services
    5.     to-whoami:
    6.       rule: "Host(`example.com`) && PathPrefix(`/whoami/`)"
    7.        # If the rule matches, applies the middleware
    8.       middlewares:
    9.       - test-user
    10.       # If the rule matches, forward to the whoami service (declared below)
    11.       service: whoami
    13.   middlewares:
    14.     # Define an authentication mechanism
    15.     test-user:
    16.       basicAuth:
    17.         users:
    18.         - test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/
    20.   services:
    21.     # Define how to reach an existing service on our infrastructure
    22.     whoami:
    23.       loadBalancer:
    24.         servers:
    25.         - url: http://private/whoami-service

    TOML

    1. # http routing section
    2. [http]
    3.   [http.routers]
    4.      # Define a connection between requests and services
    5.      [http.routers.to-whoami]
    6.       rule = "Host(`example.com`) && PathPrefix(`/whoami/`)"
    7.       # If the rule matches, applies the middleware
    8.       middlewares = ["test-user"]
    9.       service = "whoami"
    11.   [http.middlewares]
    12.     # Define an authentication mechanism
    13.     [http.middlewares.test-user.basicAuth]
    14.       users = ["test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"]
    17.     # Define how to reach an existing service on our infrastructure
    18.     [http.services.whoami.loadBalancer]
    19.       [[http.services.whoami.loadBalancer.servers]]
    20.         url = "http://private/whoami-service"

    In this example, we use the file provider. Even if it is one of the least magical way of configuring Traefik, it explicitly describes every available notion.

    HTTP / TCP

    In this example, we’ve defined routing rules for http requests only. Traefik also supports TCP requests. To add and TCP services, declare them in a TCP section like in the following.

    Adding a TCP route for TLS requests on whoami-tcp.example.com

    Static Configuration

    File (YAML)

    1. entryPoints:
    2.   web:
    3.     # Listen on port 8081 for incoming requests
    4.     address: :8081
    5. providers:
    6.   # Enable the file provider to define routers / middlewares / services in file
    7.   file:
    8.     directory: /path/to/dynamic/conf

    File (TOML)

    1. [entryPoints]
    2.   [entryPoints.web]
    3.     # Listen on port 8081 for incoming requests
    4.     address = ":8081"
    6. [providers]
    7.   # Enable the file provider to define routers / middlewares / services in file
    8.   [providers.file]
    9.     directory = "/path/to/dynamic/conf"
    1. # Listen on port 8081 for incoming requests
    2. --entryPoints.web.address=:8081
    4. # Enable the file provider to define routers / middlewares / services in file
    5. --providers.file.directory=/path/to/dynamic/conf

    Dynamic Configuration

    YAML

    1. # http routing section
    2. http:
    4.   routers:
    5.     # Define a connection between requests and services
    6.     to-whoami:
    7.       rule: Host(`example.com`) && PathPrefix(`/whoami/`)
    8.       # If the rule matches, applies the middleware
    9.       middlewares:
    10.       - test-user
    11.       # If the rule matches, forward to the whoami service (declared below)
    12.       service: whoami
    14.   middlewares:
    15.     # Define an authentication mechanism
    16.     test-user:
    17.       basicAuth:
    18.         users:
    19.         - test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/
    21.   services:
    22.     # Define how to reach an existing service on our infrastructure
    23.     whoami:
    24.       loadBalancer:
    25.         servers:
    26.         - url: http://private/whoami-service
    27. tcp:
    29.     to-whoami-tcp:
    30.       service: whoami-tcp
    31.       rule: HostSNI(`whoami-tcp.example.com`)
    32.       tls: {}
    34.   services:
    35.     whoami-tcp:
    36.       loadBalancer:
    38.         - address: xx.xx.xx.xx:xx

    TOML

    Most of what happens to the connection between the clients and Traefik, and then between Traefik and the backend servers, is configured through the entrypoints and the .

    In addition, a few parameters are dedicated to configuring globally what happens with the connections between Traefik and the backends. This is done through the serversTransport section of the configuration, which features these options:

    Optional, Default=false

    insecureSkipVerify disables SSL certificate verification.

    File (YAML)

    1. ## Static configuration
    2. serversTransport:
    3.   insecureSkipVerify: true

    File (TOML)

    1. ## Static configuration
    2. [serversTransport]
    3.   insecureSkipVerify = true

    CLI

    1. ## Static configuration
    2. --serversTransport.insecureSkipVerify=true

    Optional

    rootCAs is the list of certificates (as file paths, or data bytes) that will be set as Root Certificate Authorities when using a self-signed TLS certificate.

    File (YAML)

    1. ## Static configuration
    2. serversTransport:
    3.   rootCAs:
    4.     - foo.crt
    5.     - bar.crt

    File (TOML)

    1. ## Static configuration
    2. [serversTransport]
    3.   rootCAs = ["foo.crt", "bar.crt"]

    CLI

    1. ## Static configuration
    2. --serversTransport.rootCAs=foo.crt,bar.crt

    Optional, Default=2

    If non-zero, maxIdleConnsPerHost controls the maximum idle (keep-alive) connections to keep per-host.

    File (YAML)

    1. ## Static configuration
    2. serversTransport:
    3.   maxIdleConnsPerHost: 7
    1. ## Static configuration
    2. [serversTransport]
    3.   maxIdleConnsPerHost = 7

    CLI

    forwardingTimeouts is about a number of timeouts relevant to when forwarding requests to the backend servers.

    forwardingTimeouts.dialTimeout

    Optional, Default=30s

    dialTimeout is the maximum duration allowed for a connection to a backend server to be established. Zero means no timeout.

    File (YAML)

    1. ## Static configuration
    2. serversTransport:
    3.   forwardingTimeouts:
    4.     dialTimeout: 1s

    File (TOML)

    1. ## Static configuration
    2. [serversTransport.forwardingTimeouts]
    3.   dialTimeout = "1s"

    CLI

    1. ## Static configuration
    2. --serversTransport.forwardingTimeouts.dialTimeout=1s

    forwardingTimeouts.responseHeaderTimeout

    Optional, Default=0s

    responseHeaderTimeout, if non-zero, specifies the amount of time to wait for a server’s response headers after fully writing the request (including its body, if any). This time does not include the time to read the response body. Zero means no timeout.

    File (YAML)

    1. ## Static configuration
    2. serversTransport:
    3.   forwardingTimeouts:
    4.     responseHeaderTimeout: 1s

    File (TOML)

    1. ## Static configuration
    2. [serversTransport.forwardingTimeouts]
    3.   responseHeaderTimeout = "1s"

    CLI

    1. ## Static configuration
    2. --serversTransport.forwardingTimeouts.responseHeaderTimeout=1s

    forwardingTimeouts.idleConnTimeout

    Optional, Default=90s

    idleConnTimeout, is the maximum amount of time an idle (keep-alive) connection will remain idle before closing itself. Zero means no limit.

    File (YAML)

    1. ## Static configuration
    2. serversTransport:
    3.   forwardingTimeouts:
    4.     idleConnTimeout: 1s

    File (TOML)

    1. ## Static configuration
    3.   idleConnTimeout = "1s"

    CLI

    Using Traefik for Business Applications?

    Traefik Enterprise enables centralized access management, distributed Let’s Encrypt, and other advanced capabilities. Learn more in this 15-minute technical walkthrough.