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.
Choosing a plugin's tile brings up a page describing the plugin's function and, optionally, the configuration options available for it.
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:
[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"
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
--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:
labels:
- "traefik.http.middlewares.my-rewritebody.plugin.rewrite.rewrites[0].regex=example"
- "traefik.http.middlewares.my-rewritebody.plugin.rewrite.rewrites[0].replacement=test"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: my-rewritebody
spec:
plugin:
rewrite:
rewrites:
- regex: example
replacement: test
- "traefik.http.middlewares.my-rewritebody.plugin.rewrite.rewrites[0].regex=example"
- "traefik.http.middlewares.my-rewritebody.plugin.rewrite.rewrites[0].replacement=test"
"labels": {
"traefik.http.middlewares.my-rewritebody.plugin.rewrite.rewrites[0].regex": "example",
"traefik.http.middlewares.my-rewritebody.plugin.rewrite.rewrites[0].replacement": "test"
}
labels:
- "traefik.http.middlewares.my-rewritebody.plugin.rewrite.rewrites[0].regex=example"
- "traefik.http.middlewares.my-rewritebody.plugin.rewrite.rewrites[0].replacement=test"
[http.middlewares]
[http.middlewares.my-rewritebody.plugin.rewrite]
lastModified = true
[[http.middlewares.my-rewritebody.plugin.rewrite.rewrites]]
regex = "example"
replacement = "test"
http:
middlewares:
my-rewritebody:
plugin:
rewrite:
rewrites:
- regex: example
replacement: test