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.

Plugin Catalog

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.

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 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.

Middleware Plugins

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

Static Configuration

In the examples below, we add the blockpath and rewritebody plugins in the Traefik Static 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"

Dynamic Configuration

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

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

Provider Plugins

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:

Copy
experimental:
  traefikServiceFabricPlugin:
    moduleName: github.com/dariopb/traefikServiceFabricPlugin
    version: v0.2.2

providers:
  plugin:
    traefikServiceFabricPlugin:
      pollInterval: 4s
      clusterManagementURL: http://dariotraefik1.southcentralus.cloudapp.azure.com:19080/
      #certificate : ./cert.pem
      #certificateKey: ./cert.key

Local Mode

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:

Copy
./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

Copy
# Static configuration
# Local mode
entryPoints:
  web:
    address: :80

log:
  level: DEBUG

experimental:
  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.