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 middleware; they can be used as a Traefik provider to allow providing configuration from a new infrastructure component such as an orchestrator or a cloud provider.
Unlike traditional middleware or providers, 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.
Support for plugins is available in Traefik v2.3 and later.
Plugins can potentially modify the behavior of Traefik in undesired ways. Exercise caution when adding new plugins to production Traefik instances.
Traefik operators can browse and install plugins from the online catalog, which is available from the Plugin Catalog.
Choosing a plugin's tile brings up a page describing the plugin's function and, optionally, the configuration options available for it.
Selecting Install Plugin from either a tile or a plugin details page will display the necessary code to be added to the Traefik proxy's static and/or dynamic configurations to complete the installation process.
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 Plugin Catalog 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.
For security reasons, it is not possible to start a new plugin or modify an existing one while Traefik is running.
Once loaded, these plugins behave like statically compiled middlewares. Their instantiation and behavior are driven by the dynamic configuration.
[entryPoints][entryPoints.web]address = ":80"[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"
Some plugins will need to be configured by adding a dynamic configuration.
bodyrewrite plugin, for example:
apiVersion: traefik.containo.us/v1alpha1kind: Middlewaremetadata:name: my-rewritebodyspec:plugin:rewrite:rewrites: - regex: examplereplacement: test
Once loaded, these plugins behave like statically compiled providers. Their instantiation and behavior are driven by the static configuration.
In the examples below, we add and configure the
service-fabric-plugin plugin in the Traefik Static Configuration:
experimental:traefikServiceFabricPlugin:moduleName: github.com/dariopb/traefikServiceFabricPluginversion: v0.2.2providers:plugin:traefikServiceFabricPlugin:pollInterval: 4sclusterManagementURL: http://dariotraefik1.southcentralus.cloudapp.azure.com:19080/#certificate : ./cert.pem#certificateKey: ./cert.key
Traefik also offers a local mode that can be used for:
- Using private plugins that are not hosted on GitHub
- Testing the plugins during their development
To use a plugin in local mode, the Traefik static configuration must define the module name (as is usual for Go packages) and a path to a Go workspace, which can be the local GOPATH or any directory.
The plugins must be placed in
./plugins-local directory, which should be in the working directory of the process running the Traefik binary.
The source code of the plugin should be organized as follows:
./plugins-local/└── src└── github.com└── traefik└── plugindemo├── demo.go├── demo_test.go├── go.mod├── go.sum├── LICENSE├── Makefile├── readme.md└── vendor├── github.com│ └── traefik│ └── genconf│ ├── dynamic│ │ ├── config.go│ │ ├── http_config.go│ │ ├── marshaler.go│ │ ├── middlewares.go│ │ ├── plugins.go│ │ ├── tcp_config.go│ │ ├── tls│ │ │ ├── certificate.go│ │ │ └── tls.go│ │ ├── types│ │ │ ├── domains.go│ │ │ └── tls.go│ │ └── udp_config.go│ └── LICENSE└── modules.txt
# Static configuration# Local modeentryPoints:web:address: :80log:level: DEBUGexperimental:localPlugins:example:moduleName: github.com/traefik/plugindemo
In the above example, the
plugindemo plugin will be loaded as a
localPlugins from the path
./plugins-local/src/github.com/traefik/plugindemo instead of being downloaded from the internet.