

Middlewares

Tweaking the Request

Attached to the routers, pieces of middleware are a means of tweaking the requests before they are sent to your service (or before the answer from the services are sent to the clients).

There are several available middleware in Traefik, some can modify the request, the headers, some are in charge of redirections, some add authentication, and so on.

Pieces of middleware can be combined in chains to fit every scenario.

Configuration Example

Docker

# As a Docker Label
whoami:
  #  A container that exposes an API to show its IP address
  image: traefik/whoami
  labels:
    # Create a middleware named `foo-add-prefix`
    - "traefik.http.middlewares.foo-add-prefix.addprefix.prefix=/foo"
    # Apply the middleware named `foo-add-prefix` to the router named `router1`
    - "traefik.http.routers.router1.middlewares=foo-add-prefix@docker"

Kubernetes IngressRoute

# As a Kubernetes Traefik IngressRoute
apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
  name: middlewares.traefik.containo.us
spec:
  group: traefik.containo.us
  version: v1alpha1
  names:
    kind: Middleware
    plural: middlewares
    singular: middleware
  scope: Namespaced

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

---
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
  name: ingressroute
spec:
# more fields...
  routes:
    # more fields...
    middlewares:
      - name: stripprefix

Consul Catalog

# Create a middleware named `foo-add-prefix`
- "traefik.http.middlewares.foo-add-prefix.addprefix.prefix=/foo"
# Apply the middleware named `foo-add-prefix` to the router named `router1`
- "traefik.http.routers.router1.middlewares=foo-add-prefix@consulcatalog"

Marathon

"labels": {
  "traefik.http.middlewares.foo-add-prefix.addprefix.prefix": "/foo",
  "traefik.http.routers.router1.middlewares": "foo-add-prefix@marathon"
}

Rancher

# As a Rancher Label
labels:
  # Create a middleware named `foo-add-prefix`
  - "traefik.http.middlewares.foo-add-prefix.addprefix.prefix=/foo"
  # Apply the middleware named `foo-add-prefix` to the router named `router1`
  - "traefik.http.routers.router1.middlewares=foo-add-prefix@rancher"

File (TOML)

# As TOML Configuration File
[http.routers]
  [http.routers.router1]
    service = "myService"
    middlewares = ["foo-add-prefix"]
    rule = "Host(`example.com`)"

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

[http.services]
  [http.services.service1]
    [http.services.service1.loadBalancer]

      [[http.services.service1.loadBalancer.servers]]
        url = "http://127.0.0.1:80"

File (YAML)

# As YAML Configuration File
http:
  routers:
    router1:
      service: myService
      middlewares:
        - "foo-add-prefix"
      rule: "Host(`example.com`)"

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

  services:
    service1:
      loadBalancer:
        servers:
          - url: "http://127.0.0.1:80"

Provider Namespace

When you declare a middleware, it lives 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 a middleware declared in another provider (aka referencing a cross-provider middleware), then you'll have to append to the middleware name, the @ separator, followed by the provider 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 the middleware 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 declare the 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 Middleware 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

Available Middlewares

Middleware	Purpose	Area
AddPrefix	Add a Path Prefix	Path Modifier
BasicAuth	Basic auth mechanism	Security, Authentication
Buffering	Buffers the request/response	Request Lifecycle
Chain	Combine multiple pieces of middleware	Middleware tool
CircuitBreaker	Stop calling unhealthy services	Request Lifecycle
Compress	Compress the response	Content Modifier
DigestAuth	Adds Digest Authentication	Security, Authentication
Errors	Define custom error pages	Request Lifecycle
ForwardAuth	Authentication delegation	Security, Authentication
Headers	Add / Update headers	Security
IPWhiteList	Limit the allowed client IPs	Security, Request lifecycle
InFlightReq	Limit the number of simultaneous connections	Security, Request lifecycle
PassTLSClientCert	Adding Client Certificates in a Header	Security
RateLimit	Limit the call frequency	Security, Request lifecycle
RedirectScheme	Redirect easily the client elsewhere	Request lifecycle
RedirectRegex	Redirect the client elsewhere	Request lifecycle
ReplacePath	Change the path of the request	Path Modifier
ReplacePathRegex	Change the path of the request	Path Modifier
Retry	Automatically retry the request in case of errors	Request lifecycle
StripPrefix	Change the path of the request	Path Modifier
StripPrefixRegex	Change the path of the request	Path Modifier