• Migration Guide: From v1 to v2
    • Frontends and Backends Are Dead… … Long Live Routers, Middlewares, and Services
      • v1
      • v2
    • TLS configuration is now dynamic, per router.
      • v1
      • v2
    • HTTP -> HTTPS Redirection
    • ACME (let's encrypt)
    • Traefik Logs
    • Tracing
    • Metrics
    • No more root level key/values
    • Providers

    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.

    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

    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"
    1. apiVersion: extensions/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.locahost
    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
    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

    1. labels:
    2.   - "traefik.http.routers.router0.rule=Host(`bar.com`) && 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"
    1. # The definitions below require the definitions for the Middleware and IngressRoute kinds.  
    2. # https://docs.traefik.io/v2.0/providers/kubernetes-crd/#traefik-ingressroute-definition
    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
    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.     ]
    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 web-secure entryPoint becomes TLS option on Router-1

    v1

    1. # static configuration
    2. [entryPoints]
    3.   [entryPoints.web-secure]
    4.     address = ":443"
    6.     [entryPoints.web-secure.tls]
    7.       minVersion = "VersionTLS12"
    8.       cipherSuites = [
    9.         "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
    10.         "TLS_RSA_WITH_AES_256_GCM_SHA384"
    11.        ]
    12.       [[entryPoints.web-secure.tls.certificates]]
    13.         certFile = "path/to/my.cert"
    14.         keyFile = "path/to/my.key"
    1. --entryPoints='Name:web-secure 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_128_GCM_SHA384'

    v2

    1. # dynamic configuration
    2. [http.routers]
    3.   [http.routers.Router-1]
    4.     rule = "Host(`bar.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.default]
    16.     minVersion = "VersionTLS12"
    18.   [tls.options.myTLSOptions]
    19.     minVersion = "VersionTLS13"
    20.     cipherSuites = [
    21.           "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
    22.           "TLS_RSA_WITH_AES_256_GCM_SHA384"
    23.         ]
    1. http:
    2.   routers:
    3.     Router-1:
    4.       rule: "Host(`bar.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: VersionTLS13
    17.       cipherSuites:
    18.       - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
    19.       - TLS_RSA_WITH_AES_256_GCM_SHA384
    1. # The definitions below require the definitions for the TLSOption and IngressRoute kinds.  
    2. # https://docs.traefik.io/v2.0/providers/kubernetes-crd/#traefik-ingressroute-definition
    3. apiVersion: traefik.containo.us/v1alpha1
    4. kind: TLSOption
    5. metadata:
    6.   name: mytlsoption
    7.   namespace: default
    9. spec:
    10.   minVersion: VersionTLS13
    11.   cipherSuites:
    12.     - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
    13.     - TLS_RSA_WITH_AES_256_GCM_SHA384
    15. ---
    16. apiVersion: traefik.containo.us/v1alpha1
    17. kind: IngressRoute
    18. metadata:
    19.   name: ingressroutebar
    21. spec:
    22.   entryPoints:
    23.     - web
    24.   routes:
    25.   - match: Host(`bar.com`)
    26.     kind: Rule
    27.     services:
    28.     - name: whoami
    29.       port: 80
    30.   tls:
    31.     options: 
    32.       name: mytlsoption
    33.       namespace: default
    1. labels:
    2.   # myTLSOptions must be defined by another provider, in this instance in the File Provider.
    3.   # see the cross provider section
    4.   - "[email protected]"

    HTTP -> HTTPS Redirection

    1. TODO

    ACME (let's encrypt)

    1. TODO

    Traefik Logs

    1. TODO

    Tracing

    1. TODO

    Metrics

    1. TODO

    No more root level key/values

    1. TODO

    Providers

    Supported providers, for now:

    • Azure Service Fabric
    • BoltDB
    • Consul
    • Consul Catalog
    • Docker
    • DynamoDB
    • ECS
    • Etcd
    • Eureka
    • File
    • Kubernetes Ingress (without annotations)
    • Kubernetes IngressRoute
    • Marathon
    • Mesos
    • Rest
    • Zookeeper