Working with Traefik Plugins¶

Plugin support is a powerful feature that allows developers to add new functionality to Traefik and define new behaviors. For example, plugins can modify requests or headers, issue redirects, add authentication, and so on, providing similar functionality to Traefik middlewares.

Unlike traditional middlewares, however, plugins are loaded dynamically and executed by an embedded interpreter. There is no need to compile binaries and all plugins are 100% cross-platform, making them easy to develop and share with the broader Traefik community.

Availability

Support for plugins is available in Traefik v2.3 and later.

Experimental Features

Plugins can potentially modify the behavior of Traefik in undesired ways. Exercise caution when adding new plugins to production Traefik instances.

Plugins and Traefik Pilot¶

Traefik works together with Traefik Pilot to enable the plugin ecosystem. Traefik operators can browse and install plugins from the online catalog, which is available from the Plugins tab in the Traefik Pilot dashboard.

Plugin catalog

Choosing a plugin's tile brings up a page describing the plugin's function and, optionally, the configuration options available for it.

Plugin description

From there, selecting Install Plugin will display the necessary code to be added to the Traefik proxy's static and/or dynamic configurations to complete the installation process.

Installing Plugins¶

For a plugin to be active for a given Traefik instance, it must be declared in the static configuration. The code to be added is provided by the Traefik Pilot UI when you choose Install Plugin.

Plugins are parsed and loaded exclusively during startup, which allows Traefik to check the integrity of the code and catch errors early on. If an error occurs during loading, the plugin is disabled.

Restart Required

For security reasons, it is not possible to start a new plugin or modify an existing one while Traefik is running.

Once loaded, middleware plugins behave like statically compiled middlewares. Their instantiation and behavior are driven by the dynamic configuration.

Static Configuration¶

In the example below, we add the blockpath and rewritebody plugins:

File (TOML)

[entryPoints]
  [entryPoints.web]
    address = ":80"

[pilot]
  token = "xxxxxxxxx"

[experimental.plugins]
  [experimental.plugins.block]
    modulename = "github.com/traefik/plugin-blockpath"
    version = "v0.2.0"

  [experimental.plugins.rewrite]
    modulename = "github.com/traefik/plugin-rewritebody"
    version = "v0.3.0"

File (YAML)

entryPoints:
  web:
    address: :80

pilot:
    token: xxxxxxxxx

experimental:
  plugins:
    block:
      modulename: github.com/traefik/plugin-blockpath
      version: v0.2.0
    rewrite:
      modulename: github.com/traefik/plugin-rewritebody
      version: v0.3.0

CLI

--entryPoints.web.address=:80
--pilot.token=xxxxxxxxx
--experimental.plugins.block.modulename=github.com/traefik/plugin-blockpath
--experimental.plugins.block.version=v0.2.0
--experimental.plugins.rewrite.modulename=github.com/traefik/plugin-rewritebody
--experimental.plugins.rewrite.version=v0.3.0

Dynamic Configuration¶

Some plugins will need to be configured by adding a dynamic configuration. For the bodyrewrite plugin, for example:

Docker

labels:
  - "traefik.http.middlewares.my-rewritebody.plugin.rewrite.rewrites[0].regex=example"
  - "traefik.http.middlewares.my-rewritebody.plugin.rewrite.rewrites[0].replacement=test"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: my-rewritebody
spec:
  plugin:
    rewrite:
      rewrites:
        - regex: example
          replacement: test

Consul Catalog

- "traefik.http.middlewares.my-rewritebody.plugin.rewrite.rewrites[0].regex=example"
- "traefik.http.middlewares.my-rewritebody.plugin.rewrite.rewrites[0].replacement=test"

Marathon

"labels": {
  "traefik.http.middlewares.my-rewritebody.plugin.rewrite.rewrites[0].regex": "example",
  "traefik.http.middlewares.my-rewritebody.plugin.rewrite.rewrites[0].replacement": "test"
}

Rancher

labels:
  - "traefik.http.middlewares.my-rewritebody.plugin.rewrite.rewrites[0].regex=example"
  - "traefik.http.middlewares.my-rewritebody.plugin.rewrite.rewrites[0].replacement=test"

File (TOML)

[http.middlewares]
  [http.middlewares.my-rewritebody.plugin.rewrite]
    lastModified = true
    [[http.middlewares.my-rewritebody.plugin.rewrite.rewrites]]
      regex = "example"
      replacement = "test"

File (YAML)

http:
  middlewares:
    my-rewritebody:
      plugin:
        rewrite:
          rewrites:
            - regex: example
              replacement: test