Overview¶

Traefik's Many Friends

Providers

Configuration discovery in Traefik is achieved through Providers.

The providers are existing infrastructure components, whether orchestrators, container engines, cloud providers, or key-value stores. The idea is that Traefik will query the providers' API in order to find relevant information about routing, and each time Traefik detects a change, it dynamically updates the routes.

Deploy and forget is Traefik's credo.

Orchestrators¶

Even if each provider is different, we can categorize them in four groups:

Label based (each deployed container has a set of labels attached to it)
Key-Value based (each deployed container updates a key-value store with relevant information)
Annotation based (a separate object, with annotations, defines the characteristics of the container)
File based (the good old configuration file)

Provider Namespace¶

When you declare certain objects, in Traefik dynamic configuration, such as middleware, service, TLS options or servers transport, they live in its provider's namespace. For example, if you declare a middleware using a Docker label, under the hoods, it will reside in the docker provider namespace.

If you use multiple providers and wish to reference such an object declared in another provider (aka referencing a cross-provider object, e.g. middleware), then you'll have to append the @ separator, followed by the provider name to the object name.

<resource-name>@<provider-name>

Kubernetes Namespace

As Kubernetes also has its own notion of namespace, one should not confuse the "provider namespace" with the "kubernetes namespace" of a resource when in the context of a cross-provider usage.
In this case, since the definition of a traefik dynamic configuration object is not in kubernetes, specifying a "kubernetes namespace" when referring to the resource does not make any sense, and therefore this specification would be ignored even if present.
On the other hand, if you, say, declare a middleware as a Custom Resource in Kubernetes and use the non-crd Ingress objects, you'll have to add the Kubernetes namespace of the middleware to the annotation like this <middleware-namespace>-<middleware-name>@kubernetescrd.

Referencing a Traefik dynamic configuration object from Another Provider

Declaring the add-foo-prefix in the file provider.

File (TOML)

[http.middlewares]
  [http.middlewares.add-foo-prefix.addPrefix]
    prefix = "/foo"

File (YAML)

http:
  middlewares:
    add-foo-prefix:
      addPrefix:
        prefix: "/foo"

Using the add-foo-prefix middleware from other providers:

Docker

your-container: #
  image: your-docker-image

  labels:
    # Attach add-foo-prefix@file middleware (declared in file)
    - "traefik.http.routers.my-container.middlewares=add-foo-prefix@file"

Kubernetes Ingress Route

apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
  name: ingressroutestripprefix

spec:
  entryPoints:
    - web
  routes:
    - match: Host(`example.com`)
      kind: Rule
      services:
        - name: whoami
          port: 80
      middlewares:
        - name: add-foo-prefix@file
        # namespace: bar
        # A namespace specification such as above is ignored
        # when the cross-provider syntax is used.

Kubernetes Ingress

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: stripprefix
  namespace: appspace
spec:
  stripPrefix:
    prefixes:
      - /stripit

---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress
  namespace: appspace
  annotations:
    # referencing a middleware from Kubernetes CRD provider: 
    # <middleware-namespace>-<middleware-name>@kubernetescrd
    "traefik.ingress.kubernetes.io/router.middlewares": appspace-stripprefix@kubernetescrd
spec:
  # ... regular ingress definition

Supported Providers¶

Below is the list of the currently supported providers in Traefik.

Provider	Type	Configuration Type
Docker	Orchestrator	Label
Kubernetes	Orchestrator	Custom Resource or Ingress
Consul Catalog	Orchestrator	Label
ECS	Orchestrator	Label
Marathon	Orchestrator	Label
Rancher	Orchestrator	Label
File	Manual	TOML/YAML format
Consul	KV	KV
Etcd	KV	KV
ZooKeeper	KV	KV
Redis	KV	KV
HTTP	Manual	JSON format

More Providers

The current version of Traefik doesn't support (yet) every provider. See the previous version (v1.7) for more providers.

Configuration reload frequency¶

In some cases, some providers might undergo a sudden burst of changes, which would generate a lot of configuration change events. If Traefik took them all into account, that would trigger a lot more configuration reloads than what is necessary, or even useful.

In order to mitigate that, the providers.providersThrottleDuration option can be set. It is the duration that Traefik waits for, after a configuration reload, before taking into account any new configuration refresh event. If any event arrives during that duration, only the most recent one is taken into account, and all the previous others are dropped.

This option cannot be set per provider, but the throttling algorithm applies independently to each of them. It defaults to 2 seconds.

File (TOML)

[providers]
  providers.providersThrottleDuration = 10s

File (YAML)

providers:
  providersThrottleDuration: 10s

CLI

--providers.providersThrottleDuration=10s

Restrict the Scope of Service Discovery¶

By default Traefik will create routes for all detected containers.

If you want to limit the scope of Traefik's service discovery, i.e. disallow route creation for some containers, you can do so in two different ways: either with the generic configuration option exposedByDefault, or with a finer granularity mechanism based on constraints.

`exposedByDefault` and `traefik.enable`¶

List of providers that support that feature:

Constraints¶

List of providers that support constraints: