Migration Guide: From v1 to v2

How to Migrate from Traefik v1 to Traefik v2.

The version 2 of Traefik introduces a number of breaking changes, which require one to update their configuration when they migrate from v1 to v2. The goal of this page is to recapitulate all of these changes, and in particular to give examples, feature by feature, of how the configuration looked like in v1, and how it now looks like in v2.

Migration Helper

We created a tool to help during the migration: traefik-migration-tool

This tool allows to:

  • convert Ingress to Traefik IngressRoute resources.
  • convert acme.json file from v1 to v2 format.
  • migrate the static configuration contained in the file traefik.toml to a Traefik v2 file.

Frontends and Backends Are Dead…

… Long Live Routers, Middlewares, and Services

During the transition from v1 to v2, a number of internal pieces and components of Traefik were rewritten and reorganized. As such, the combination of core notions such as frontends and backends has been replaced with the combination of routers, services, and middlewares.

Typically, a router replaces a frontend, and a service assumes the role of a backend, with each router referring to a service. However, even though a backend was in charge of applying any desired modification on the fly to the incoming request, the router defers that responsibility to another component. Instead, a dedicated middleware is now defined for each kind of such modification. Then any router can refer to an instance of the wanted middleware.

One frontend with basic auth and one backend, become one router, one service, and one basic auth middleware.

v1

Docker

  1. labels:
  2.   - "traefik.frontend.rule=Host:test.localhost;PathPrefix:/test"
  3.   - "traefik.frontend.auth.basic.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/,test2:$$apr1$$d9hr9HBB$$4HxwgUir3HP4EsggP/QNo0"

K8s Ingress

  1. apiVersion: networking.k8s.io/v1beta1
  2. kind: Ingress
  3. metadata:
  4.   name: traefik
  5.   namespace: kube-system
  6.   annotations:
  7.     kubernetes.io/ingress.class: traefik
  8.     traefik.ingress.kubernetes.io/rule-type: PathPrefix
  9. spec:
  10.   rules:
  11.   - host: test.localhost
  12.     http:
  13.       paths:
  14.       - path: /test
  15.         backend:
  16.           serviceName: server0
  17.           servicePort: 80
  18.       - path: /test
  19.         backend:
  20.           serviceName: server1
  21.           servicePort: 80

File (TOML)

  1. [frontends]
  2.   [frontends.frontend1]
  3.     entryPoints = ["http"]
  4.     backend = "backend1"
  6.     [frontends.frontend1.routes]
  7.       [frontends.frontend1.routes.route0]
  8.         rule = "Host:test.localhost"
  9.       [frontends.frontend1.routes.route0]
  10.         rule = "PathPrefix:/test"
  12.     [frontends.frontend1.auth]
  13.       [frontends.frontend1.auth.basic]
  14.         users = [
  15.           "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
  16.           "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0",
  17.         ]
  19. [backends]
  20.   [backends.backend1]
  21.     [backends.backend1.servers.server0]
  22.       url = "http://10.10.10.1:80"
  23.     [backends.backend1.servers.server1]
  24.       url = "http://10.10.10.2:80"
  26.     [backends.backend1.loadBalancer]
  27.       method = "wrr"

v2

Docker

  1. labels:
  2.   - "traefik.http.routers.router0.rule=Host(`test.localhost`) && PathPrefix(`/test`)"
  3.   - "traefik.http.routers.router0.middlewares=auth"
  4.   - "traefik.http.middlewares.auth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/,test2:$$apr1$$d9hr9HBB$$4HxwgUir3HP4EsggP/QNo0"

K8s IngressRoute

  1. # The definitions below require the definitions for the Middleware and IngressRoute kinds.
  2. # https://doc.traefik.io/traefik/v2.3/reference/dynamic-configuration/kubernetes-crd/#definitions
  3. apiVersion: traefik.containo.us/v1alpha1
  4. kind: Middleware
  5. metadata:
  6.   name: basicauth
  7.   namespace: foo
  9. spec:
  10.   basicAuth:
  11.     users:
  12.       - test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/
  13.       - test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0
  15. ---
  16. apiVersion: traefik.containo.us/v1alpha1
  17. kind: IngressRoute
  18. metadata:
  19.   name: ingressroutebar
  21. spec:
  22.   entryPoints:
  23.     - http
  24.   routes:
  25.   - match: Host(`test.localhost`) && PathPrefix(`/test`)
  26.     kind: Rule
  27.     services:
  28.     - name: server0
  29.       port: 80
  30.     - name: server1
  31.       port: 80
  32.     middlewares:
  33.     - name: basicauth
  34.       namespace: foo

File (TOML)

  1. [http.routers]
  2.   [http.routers.router0]
  3.     rule = "Host(`test.localhost`) && PathPrefix(`/test`)"
  4.     middlewares = ["auth"]
  5.     service = "my-service"
  7. [http.services]
  8.   [[http.services.my-service.loadBalancer.servers]]
  9.     url = "http://10.10.10.1:80"
  10.   [[http.services.my-service.loadBalancer.servers]]
  11.     url = "http://10.10.10.2:80"
  13. [http.middlewares]
  14.   [http.middlewares.auth.basicAuth]
  15.     users = [
  16.       "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
  17.       "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0",
  18.     ]

File (YAML)

  1. http:
  2.   routers:
  3.     router0:
  4.       rule: "Host(`test.localhost`) && PathPrefix(`/test`)"
  5.       service: my-service
  6.       middlewares:
  7.         - auth
  9.   services:
  10.     my-service:
  11.       loadBalancer:
  12.         servers:
  13.           - url: http://10.10.10.1:80
  14.           - url: http://10.10.10.2:80
  16.   middlewares:
  17.     auth:
  18.       basicAuth:
  19.         users:
  20.           - "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
  21.           - "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"

TLS Configuration is Now Dynamic, per Router.

TLS parameters used to be specified in the static configuration, as an entryPoint field. With Traefik v2, a new dynamic TLS section at the root contains all the desired TLS configurations. Then, a router’s TLS field can refer to one of the TLS configurations defined at the root, hence defining the TLS configuration for that router.

TLS on websecure entryPoint becomes TLS option on Router-1

v1

File (TOML)

  1. # static configuration
  2. [entryPoints]
  3.   [entryPoints.websecure]
  4.     address = ":443"
  6.     [entryPoints.websecure.tls]
  7.       minVersion = "VersionTLS12"
  8.       cipherSuites = [
  9.         "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
  10.         "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
  11.         "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256",
  12.         "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256",
  13.         "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
  14.         "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
  15.       ]
  16.       [[entryPoints.websecure.tls.certificates]]
  17.         certFile = "path/to/my.cert"
  18.         keyFile = "path/to/my.key"

CLI

  1. --entryPoints='Name:websecure Address::443 TLS:path/to/my.cert,path/to/my.key TLS.MinVersion:VersionTLS12 TLS.CipherSuites:TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256'

v2

File (TOML)

  1. # dynamic configuration
  2. [http.routers]
  3.   [http.routers.Router-1]
  4.     rule = "Host(`example.com`)"
  5.     service = "service-id"
  6.     # will terminate the TLS request
  7.     [http.routers.Router-1.tls]
  8.       options = "myTLSOptions"
  10. [[tls.certificates]]
  11.   certFile = "/path/to/domain.cert"
  12.   keyFile = "/path/to/domain.key"
  14. [tls.options]
  15.   [tls.options.myTLSOptions]
  16.     minVersion = "VersionTLS12"
  17.     cipherSuites = [
  18.       "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
  19.       "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
  20.       "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256",
  21.       "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256",
  22.       "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
  23.       "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
  24.     ]

File (YAML)

  1. http:
  2.   routers:
  3.     Router-1:
  4.       rule: "Host(`example.com`)"
  5.       service: service-id
  6.       # will terminate the TLS request
  7.       tls:
  8.         options: myTLSOptions
  10. tls:
  11.   certificates:
  12.     - certFile: /path/to/domain.cert
  13.       keyFile: /path/to/domain.key
  14.   options:
  15.     myTLSOptions:
  16.       minVersion: VersionTLS12
  17.       cipherSuites:
  18.         - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  19.         - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
  20.         - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
  21.         - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  22.         - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

K8s IngressRoute

  1. # The definitions below require the definitions for the TLSOption and IngressRoute kinds.
  2. # https://doc.traefik.io/traefik/v2.3/reference/dynamic-configuration/kubernetes-crd/#definitions
  3. apiVersion: traefik.containo.us/v1alpha1
  4. kind: TLSOption
  5. metadata:
  6.   name: mytlsoption
  7.   namespace: default
  9. spec:
  10.   minVersion: VersionTLS12
  11.   cipherSuites:
  12.     - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  13.     - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
  14.     - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
  15.     - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  16.     - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  18. ---
  19. apiVersion: traefik.containo.us/v1alpha1
  20. kind: IngressRoute
  21. metadata:
  22.   name: ingressroutebar
  24. spec:
  25.   entryPoints:
  26.     - web
  27.   routes:
  28.     - match: Host(`example.com`)
  29.       kind: Rule
  30.       services:
  31.         - name: whoami
  32.           port: 80
  33.   tls:
  34.     options:
  35.       name: mytlsoption
  36.       namespace: default

Docker

  1. labels:
  2.   # myTLSOptions must be defined by another provider, in this instance in the File Provider.
  3.   # see the cross provider section
  4.   - "traefik.http.routers.router0.tls.options=myTLSOptions@file"

HTTP to HTTPS Redirection is Now Configured on Routers

Previously on Traefik v1, the redirection was applied on an entry point or on a frontend. With Traefik v2 it is applied on an entry point or a Router.

To apply a redirection:

Global HTTP to HTTPS redirection

v1

File (TOML)

  1. # static configuration
  2. defaultEntryPoints = ["web", "websecure"]
  4. [entryPoints]
  5.   [entryPoints.web]
  6.     address = ":80"
  7.     [entryPoints.web.redirect]
  8.       entryPoint = "websecure"
  10.   [entryPoints.websecure]
  11.     address = ":443"
  12.     [entryPoints.websecure.tls]

CLI

  1. --entrypoints=Name:web Address::80 Redirect.EntryPoint:websecure
  2. --entryPoints='Name:websecure Address::443 TLS'

v2

CLI

  1. ## static configuration
  3. --entrypoints.web.address=:80
  4. --entrypoints.web.http.redirections.entrypoint.to=websecure
  5. --entrypoints.web.http.redirections.entrypoint.scheme=https
  6. --entrypoints.websecure.address=:443
  7. --providers.docker=true

File (TOML)

  1. # traefik.toml
  2. ## static configuration
  4. [entryPoints.web]
  5.   address = ":80"
  6.   [entryPoints.web.http.redirections.entryPoint]
  7.     to = "websecure"
  8.     scheme = "https"
  10. [entryPoints.websecure]
  11.   address = ":443"

File (YAML)

  1. # traefik.yaml
  2. ## static configuration
  4. entryPoints:
  5.   web:
  6.     address: 80
  7.     http:
  8.       redirections:
  9.         entrypoint:
  10.           to: websecure
  11.           scheme: https
  13.   websecure:
  14.     address: 443

HTTP to HTTPS redirection per domain

v1

File (TOML)

  1. [entryPoints]
  2.   [entryPoints.web]
  3.     address = ":80"
  5.   [entryPoints.websecure]
  6.     address = ":443"
  7.     [entryPoints.websecure.tls]
  9. [file]
  11. [frontends]
  12.   [frontends.frontend1]
  13.     entryPoints = ["web", "websecure"]
  14.     [frontends.frontend1.routes]
  15.       [frontends.frontend1.routes.route0]
  16.         rule = "Host:example.net"
  17.     [frontends.frontend1.redirect]
  18.       entryPoint = "websecure"

v2

Docker

  1. labels:
  2.   traefik.http.routers.app.rule: Host(`example.net`)
  3.   traefik.http.routers.app.entrypoints: web
  4.   traefik.http.routers.app.middlewares: https_redirect
  6.   traefik.http.routers.appsecured.rule: Host(`example.net`)
  7.   traefik.http.routers.appsecured.entrypoints: websecure
  8.   traefik.http.routers.appsecured.tls: true
  10.   traefik.http.middlewares.https_redirect.redirectscheme.scheme: https
  11.   traefik.http.middlewares.https_redirect.redirectscheme.permanent: true

K8s IngressRoute

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: IngressRoute
  3. metadata:
  4.   name: http-redirect-ingressRoute
  6. spec:
  7.   entryPoints:
  8.     - web
  9.   routes:
  10.     - match: Host(`example.net`)
  11.       kind: Rule
  12.       services:
  13.         - name: whoami
  14.           port: 80
  15.       middlewares:
  16.         - name: https-redirect
  18. ---
  19. apiVersion: traefik.containo.us/v1alpha1
  20. kind: IngressRoute
  21. metadata:
  22.   name: https-ingressRoute
  24. spec:
  25.   entryPoints:
  26.     - websecure
  27.   routes:
  28.     - match: Host(`foo`)
  29.       kind: Rule
  30.       services:
  31.         - name: whoami
  32.           port: 80
  33.   tls: {}
  35. ---
  36. apiVersion: traefik.containo.us/v1alpha1
  37. kind: Middleware
  38. metadata:
  39.   name: https-redirect
  40. spec:
  41.   redirectScheme:
  42.     scheme: https
  43.     permanent: true

File (TOML)

  1. ## dynamic configuration
  2. # dynamic-conf.toml
  4. [http.routers]
  5.   [http.routers.router0]
  6.     rule = "Host(`example.net`)"
  7.     service = "my-service"
  8.     entrypoints = ["web"]
  9.     middlewares = ["https_redirect"]
  11. [http.routers.router1]
  12.     rule = "Host(`example.net`)"
  13.     service = "my-service"
  14.     entrypoints = ["websecure"]
  15.     [http.routers.router1.tls]
  17. [http.middlewares]
  18.   [http.middlewares.https_redirect.redirectScheme]
  19.     scheme = "https"
  20.     permanent = true

File (YAML)

  1. ## dynamic configuration
  2. # dynamic-conf.yml
  4. http:
  5.   routers:
  6.     router0:
  7.       rule: "Host(`example.net`)"
  8.       entryPoints:
  9.         - web
  10.       middlewares:
  11.         - https_redirect
  12.       service: my-service
  14.     router1:
  15.       rule: "Host(`example.net`)"
  16.       entryPoints:
  17.         - websecure
  18.       service: my-service
  19.       tls: {}
  21.   middlewares:
  22.     https-redirect:
  23.       redirectScheme:
  24.         scheme: https
  25.         permanent: true

Strip and Rewrite Path Prefixes

With the new core notions of v2 (introduced earlier in the section “Frontends and Backends Are Dead… Long Live Routers, Middlewares, and Services”), transforming the URL path prefix of incoming requests is configured with middlewares, after the routing step with router rule PathPrefix.

Use Case: Incoming requests to http://example.org/admin are forwarded to the webapplication “admin”, with the path /admin stripped, e.g. to http://<IP>:<port>/. In this case, you must:

  • First, configure a router named admin with a rule matching at least the path prefix with the PathPrefix keyword,
  • Then, define a middleware of type stripprefix, which removes the prefix /admin, associated to the router admin.

Strip Path Prefix When Forwarding to Backend

v1

Docker

  1. labels:
  2.   - "traefik.frontend.rule=Host:example.org;PathPrefixStrip:/admin"

Kubernetes Ingress

  1. apiVersion: networking.k8s.io/v1beta1
  2. kind: Ingress
  3. metadata:
  4.   name: traefik
  5.   annotations:
  6.     kubernetes.io/ingress.class: traefik
  7.     traefik.ingress.kubernetes.io/rule-type: PathPrefixStrip
  8. spec:
  9.   rules:
  10.   - host: example.org
  11.     http:
  12.       paths:
  13.       - path: /admin
  14.         backend:
  15.           serviceName: admin-svc
  16.           servicePort: admin

File (TOML)

  1. [frontends.admin]
  2.   [frontends.admin.routes.admin_1]
  3.   rule = "Host:example.org;PathPrefixStrip:/admin"

v2

Docker

  1. labels:
  2.   - "traefik.http.routers.admin.rule=Host(`example.org`) && PathPrefix(`/admin`)"
  3.   - "traefik.http.routers.admin.middlewares=admin-stripprefix"
  4.   - "traefik.http.middlewares.admin-stripprefix.stripprefix.prefixes=/admin"

Kubernetes IngressRoute

  1. ---
  2. apiVersion: traefik.containo.us/v1alpha1
  3. kind: IngressRoute
  4. metadata:
  5.   name: http-redirect-ingressRoute
  6.   namespace: admin-web
  7. spec:
  8.   entryPoints:
  9.     - web
  10.   routes:
  11.     - match: Host(`example.org`) && PathPrefix(`/admin`)
  12.       kind: Rule
  13.       services:
  14.         - name: admin-svc
  15.           port: admin
  16.       middlewares:
  17.         - name: admin-stripprefix
  18. ---
  19. apiVersion: traefik.containo.us/v1alpha1
  20. kind: Middleware
  21. metadata:
  22.   name: admin-stripprefix
  23. spec:
  24.   stripPrefix:
  25.     prefixes:
  26.       - /admin

File (TOML)

  1. ## Dynamic configuration
  2. # dynamic-conf.toml
  4. [http.routers.router1]
  5.     rule = "Host(`example.org`) && PathPrefix(`/admin`)"
  6.     service = "admin-svc"
  7.     entrypoints = ["web"]
  8.     middlewares = ["admin-stripprefix"]
  10. [http.middlewares]
  11.   [http.middlewares.admin-stripprefix.stripPrefix]
  12.   prefixes = ["/admin"]
  14. # ...

File (YAML)

  1. ## Dynamic Configuration
  2. # dynamic-conf.yml
  4. # As YAML Configuration File
  5. http:
  6.   routers:
  7.     admin:
  8.       service: admin-svc
  9.       middlewares:
  10.         - "admin-stripprefix"
  11.       rule: "Host(`example.org`) && PathPrefix(`/admin`)"
  13.   middlewares:
  14.     admin-stripprefix:
  15.       stripPrefix:
  16.         prefixes: 
  17.         - "/admin"
  19. # ...

What About Other Path Transformations?

Instead of removing the path prefix with the stripprefix middleware, you can also:

ACME (LetsEncrypt)

ACME is now a certificate resolver (under a certificatesResolvers section) but remains in the static configuration.

ACME from provider to a specific Certificate Resolver

v1

File (TOML)

  1. # static configuration
  2. defaultEntryPoints = ["websecure","web"]
  4. [entryPoints.web]
  5. address = ":80"
  6.   [entryPoints.web.redirect]
  7.   entryPoint = "webs"
  8. [entryPoints.websecure]
  9.   address = ":443"
  10.   [entryPoints.websecure.tls]
  12. [acme]
  13.   email = "your-email-here@example.com"
  14.   storage = "acme.json"
  15.   entryPoint = "websecure"
  16.   onHostRule = true
  17.   [acme.tlsChallenge]

CLI

  1. --defaultentrypoints=websecure,web
  2. --entryPoints=Name:web Address::80 Redirect.EntryPoint:websecure
  3. --entryPoints=Name:websecure Address::443 TLS
  4. --acme.email=your-email-here@example.com
  5. --acme.storage=acme.json
  6. --acme.entryPoint=websecure
  7. --acme.onHostRule=true
  8. --acme.tlschallenge=true

v2

File (TOML)

  1. # static configuration
  2. [entryPoints]
  3.   [entryPoints.web]
  4.     address = ":80"
  6.   [entryPoints.websecure]
  7.     address = ":443"
  8.   [entryPoints.websecure.http.tls]
  9.     certResolver = "myresolver"
  11. [certificatesResolvers.myresolver.acme]
  12.   email = "your-email@example.com"
  13.   storage = "acme.json"
  14.   [certificatesResolvers.myresolver.acme.tlsChallenge]

File (YAML)

  1. entryPoints:
  2.   web:
  3.     address: ":80"
  5.   websecure:
  6.     address: ":443"
  7.     http:
  8.       tls:
  9.         certResolver: myresolver
  11. certificatesResolvers:
  12.   myresolver:
  13.     acme:
  14.       email: your-email@example.com
  15.       storage: acme.json
  16.       tlsChallenge: {}

CLI

  1. --entrypoints.web.address=:80
  2. --entrypoints.websecure.address=:443
  3. --certificatesresolvers.myresolver.acme.email=your-email@example.com
  4. --certificatesresolvers.myresolver.acme.storage=acme.json
  5. --certificatesresolvers.myresolver.acme.tlschallenge=true

Traefik Logs

In the v2, all the log configuration remains in the static part but are unified under a log section. There is no more log configuration at the root level.

Simple log configuration

v1

File (TOML)

  1. # static configuration
  2. logLevel = "DEBUG"
  4. [traefikLog]
  5.   filePath = "/path/to/traefik.log"
  6.   format   = "json"

CLI

  1. --logLevel=DEBUG
  2. --traefikLog.filePath=/path/to/traefik.log
  3. --traefikLog.format=json

v2

File (TOML)

  1. # static configuration
  2. [log]
  3.   level = "DEBUG"
  4.   filePath = "/path/to/log-file.log"
  5.   format = "json"

File (YAML)

  1. # static configuration
  2. log:
  3.   level: DEBUG
  4.   filePath: /path/to/log-file.log
  5.   format: json

CLI

  1. --log.level=DEBUG
  2. --log.filePath=/path/to/traefik.log
  3. --log.format=json

Access Logs

Access Logs are configured in the same way as before.

But all request headers are now filtered out by default in Traefik v2. So during migration, you might want to consider enabling some needed fields (see access log configuration).

Tracing

Traefik v2 retains OpenTracing support. The backend root option from the v1 is gone, you just have to set your tracing configuration.

Simple Jaeger tracing configuration

v1

File (TOML)

  1. # static configuration
  2. [tracing]
  3.   backend = "jaeger"
  4.   servicename = "tracing"
  5.   [tracing.jaeger]
  6.     samplingParam = 1.0
  7.     samplingServerURL = "http://12.0.0.1:5778/sampling"
  8.     samplingType = "const"
  9.     localAgentHostPort = "12.0.0.1:6831"

CLI

  1. --tracing.backend=jaeger
  2. --tracing.servicename=tracing
  3. --tracing.jaeger.localagenthostport=12.0.0.1:6831
  4. --tracing.jaeger.samplingparam=1.0
  5. --tracing.jaeger.samplingserverurl=http://12.0.0.1:5778/sampling
  6. --tracing.jaeger.samplingtype=const

v2

File (TOML)

  1. # static configuration
  2. [tracing]
  3.   servicename = "tracing"
  4.   [tracing.jaeger]
  5.     samplingParam = 1.0
  6.     samplingServerURL = "http://12.0.0.1:5778/sampling"
  7.     samplingType = "const"
  8.     localAgentHostPort = "12.0.0.1:6831"

File (YAML)

  1. # static configuration
  2. tracing:
  3.   servicename: tracing
  4.   jaeger:
  5.     samplingParam: 1
  6.     samplingServerURL: 'http://12.0.0.1:5778/sampling'
  7.     samplingType: const
  8.     localAgentHostPort: '12.0.0.1:6831'

CLI

  1. --tracing.servicename=tracing
  2. --tracing.jaeger.localagenthostport=12.0.0.1:6831
  3. --tracing.jaeger.samplingparam=1.0
  4. --tracing.jaeger.samplingserverurl=http://12.0.0.1:5778/sampling
  5. --tracing.jaeger.samplingtype=const

Metrics

The v2 retains metrics tools and allows metrics to be configured for the entrypoints and/or services. For a basic configuration, the metrics configuration remains the same.

Simple Prometheus metrics configuration

v1

File (TOML)

  1. # static configuration
  2. [metrics.prometheus]
  3.   buckets = [0.1,0.3,1.2,5.0]
  4.   entryPoint = "traefik"

CLI

  1. --metrics.prometheus.buckets=[0.1,0.3,1.2,5.0]
  2. --metrics.prometheus.entrypoint=traefik

v2

File (TOML)

  1. # static configuration
  2. [metrics.prometheus]
  3.   buckets = [0.1,0.3,1.2,5.0]
  4.   entryPoint = "metrics"

File (YAML)

  1. # static configuration
  2. metrics:
  3.   prometheus:
  4.     buckets:
  5.       - 0.1
  6.       - 0.3
  7.       - 1.2
  8.       - 5
  9.     entryPoint: metrics

CLI

  1. --metrics.prometheus.buckets=[0.1,0.3,1.2,5.0]
  2. --metrics.prometheus.entrypoint=metrics

No More Root Level Key/Values

To avoid any source of confusion, there are no more configuration at the root level. Each root item has been moved to a related section or removed.

From root to dedicated section

v1

File (TOML)

  1. # static configuration
  2. checkNewVersion = false
  3. sendAnonymousUsage = true
  4. logLevel = "DEBUG"
  5. insecureSkipVerify = true
  6. rootCAs = [ "/mycert.cert" ]
  7. maxIdleConnsPerHost = 200
  8. providersThrottleDuration = "2s"
  9. AllowMinWeightZero = true
  10. debug = true
  11. defaultEntryPoints = ["web", "websecure"]
  12. keepTrailingSlash = false

CLI

  1. --checknewversion=false
  2. --sendanonymoususage=true
  3. --loglevel=DEBUG
  4. --insecureskipverify=true
  5. --rootcas=/mycert.cert
  6. --maxidleconnsperhost=200
  7. --providersthrottleduration=2s
  8. --allowminweightzero=true
  9. --debug=true
  10. --defaultentrypoints=web,websecure
  11. --keeptrailingslash=true

v2

File (TOML)

  1. # static configuration
  2. [global]
  3.   checkNewVersion = true
  4.   sendAnonymousUsage = true
  6. [log]
  7.   level = "DEBUG"
  9. [serversTransport]
  10.   insecureSkipVerify = true
  11.   rootCAs = [ "/mycert.cert" ]
  12.   maxIdleConnsPerHost = 42
  14. [providers]
  15.   providersThrottleDuration = 42

File (YAML)

  1. # static configuration
  2. global:
  3.   checkNewVersion: true
  4.   sendAnonymousUsage: true
  6. log:
  7.   level: DEBUG
  9. serversTransport:
  10.   insecureSkipVerify: true
  11.   rootCAs:
  12.     - /mycert.cert
  13.   maxIdleConnsPerHost: 42
  15. providers:
  16.   providersThrottleDuration: 42

CLI

  1. --global.checknewversion=true
  2. --global.sendanonymoususage=true
  3. --log.level=DEBUG
  4. --serverstransport.insecureskipverify=true
  5. --serverstransport.rootcas=/mycert.cert
  6. --serverstransport.maxidleconnsperhost=42
  7. --providers.providersthrottleduration=42

Dashboard

You need to activate the API to access the dashboard.

To activate the dashboard, you can either:

Activate and access the dashboard

v1

File (TOML)

  1. ## static configuration
  2. # traefik.toml
  4. [entryPoints.websecure]
  5.   address = ":443"
  6.   [entryPoints.websecure.tls]
  7.   [entryPoints.websecure.auth]
  8.     [entryPoints.websecure.auth.basic]
  9.       users = [
  10.         "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
  11.       ]
  13. [api]
  14.   entryPoint = "websecure"

CLI

  1. --entryPoints='Name:websecure Address::443 TLS Auth.Basic.Users:test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/'
  2. --api

v2

Docker

  1. # dynamic configuration
  2. labels:
  3.   - "traefik.http.routers.api.rule=Host(`traefik.docker.localhost`)"
  4.   - "traefik.http.routers.api.entrypoints=websecure"
  5.   - "traefik.http.routers.api.service=api@internal"
  6.   - "traefik.http.routers.api.middlewares=myAuth"
  7.   - "traefik.http.routers.api.tls"
  8.   - "traefik.http.middlewares.myAuth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/"

File (TOML)

  1. ## static configuration
  2. # traefik.toml
  4. [entryPoints.websecure]
  5.   address = ":443"
  7. [api]
  9. [providers.file]
  10.   directory = "/path/to/dynamic/config"
  12. ##---------------------##
  14. ## dynamic configuration
  15. # /path/to/dynamic/config/dynamic-conf.toml
  17. [http.routers.api]
  18.   rule = "Host(`traefik.docker.localhost`)"
  19.   entrypoints = ["websecure"]
  20.   service = "api@internal"
  21.   middlewares = ["myAuth"]
  22.   [http.routers.api.tls]
  24. [http.middlewares.myAuth.basicAuth]
  25.   users = [
  26.     "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
  27.   ]

File (YAML)

  1. ## static configuration
  2. # traefik.yaml
  4. entryPoints:
  5.   websecure:
  6.     address: ':443'
  8. api: {}
  10. providers:
  11.   file:
  12.     directory: /path/to/dynamic/config
  14. ##---------------------##
  16. ## dynamic configuration
  17. # /path/to/dynamic/config/dynamic-conf.yaml
  19.  http:
  20.   routers:
  21.     api:
  22.       rule: Host(`traefik.docker.localhost`)
  23.       entrypoints:
  24.         - websecure
  25.       service: api@internal
  26.       middlewares:
  27.         - myAuth
  28.       tls: {}
  30.   middlewares:
  31.     myAuth:
  32.       basicAuth:
  33.         users:
  34.           - 'test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/'

Providers

Supported providers, for now:

  • Azure Service Fabric
  • Consul
  • Consul Catalog
  • Docker
  • DynamoDB
  • ECS
  • Etcd
  • Eureka
  • File
  • Kubernetes Ingress
  • Kubernetes IngressRoute
  • Marathon
  • Mesos
  • Rancher
  • Redis
  • Rest
  • Zookeeper

Some Tips You Should Know

  • Different sources of static configuration (file, CLI flags, …) cannot be mixed.
  • Now, configuration elements can be referenced between different providers by using the provider namespace notation: @<provider>. For instance, a router named myrouter in a File Provider can refer to a service named myservice defined in Docker Provider with the following notation: myservice@docker.
  • Middlewares are applied in the same order as their declaration in router.
  • If you have any questions feel free to join our community forum.