Skip to content

Traefik Plugins

Plugins are a powerful feature for extending Traefik Enterprise with custom features and behaviors.

You can browse community-contributed plugins from the catalog in the Plugin Catalog.

Experimental Features

Plugins can potentially modify the behavior of Traefik Enterprise in unforeseen ways. Exercise caution when adding new plugins to production Traefik Enterprise clusters.

Using plugins in Traefik Enterprise

In Traefik Enterprise, using plugins relies on an additional component called the plugin registry.

Depending on how Traefik Enterprise has been installed you may need to install this component separately.

For instance, when Traefik Enterprise is installed using Helm on Kubernetes and the values-ha.yaml file then, by default, plugin registry is not enabled.

On Helm, you can enable it by setting registry.enabled values to true.

In any case this should result in adding --plugin.url and --plugin.token to your control plane command line arguments. Those parameters should target your registry instance with a resolvable address and use a valid token.

Please make sure the plugin registry is able to write to the --plugindir location which defaults to ./traefik-plugins/.

Community Plugins

To add a community plugin to a Traefik Enterprise cluster, you must modify that instance's static configuration. The code to be added is provided for you when you choose Install the Plugin from the Plugin Catalog. To learn more about Traefik plugins, consult the documentation.

Private Plugins

To add a private plugin to a Traefik Enterprise cluster, you must first zip your plugin, with the plugin code under a root folder in the zip. It can then be added to the plugin registry using teectl:

teectl create plugin --archivepath=./plugin.zip --version=v0.1.0

Once the plugin has been added to the plugin registry, it can be added to the instance's static configuration.

experimental:
  plugins:
    example:
      moduleName: github.com/your/plugin
      version: v0.1.0
[experimental]
  [experimental.plugins]
    [experimental.plugins.example]
      moduleName = "github.com/your/plugin"
      version = "v0.1.0"

To learn more about developing plugins and see code for example plugins, please see the developer documentation.

Using a Middleware Plugin

To use a middleware plugin, it must be added and configured in the dynamic configuration. An example of this is shown below:

labels:
  - "traefik.http.middlewares.my-middleware.plugin.example.heaader.Foo=Bar"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: my-middleware
spec:
  plugin:
    example:
      headers:
        Foo: Bar

- "traefik.http.middlewares.my-middleware.plugin.example.headers.Foo=Bar"
"labels": {
  "traefik.http.middlewares.my-middleware.plugin.example.headers.Foo": "Bar"
}
labels:
  - "traefik.http.middlewares.my-middleware.plugin.example.headers.Foo=Bar"
http:
  middlewares:
    my-middleware:
      plugin:
        example:
          headers:
            Foo: Bar
[http.middlewares]
  [http.middlewares.my-middleware.plugin.example.headers]
    Foo = "Bar"

Viewing Added Plugins

You can view the plugins that have been added to the plugin registry using a teectl command:

teectl get plugins
NAME         TYPE        SUMMARY                    MODULE                         VERSION
Demo Plugin  middleware  [Demo] Add Request Header  github.com/traefik/plugindemo  v0.2.1

Deleting Unused Plugins

All plugins, both community and private, are stored in the plugin registry. Unused plugins can be removed using a teectl command:

teectl delete plugin --modulename=github.com/your/plugin --version=v0.1.0

Deleting Private Plugins

Once a version of a private plugin has been deleted, it can never be added to the plugin registry again. This is done to ensure a plugin version cannot be replaced unbeknownst to the user.