Skip to content

Developing Traefik Plugins

The Traefik plugin architecture makes it easy for developers to create new plugins, modify existing ones, and share plugins with the Traefik community.

Traefik plugins are developed using the Go language, and a Traefik plugin is just a Go package.

Rather than being pre-compiled and linked, however, plugins are executed on the fly by Yaegi, a Go interpreter that's embedded in the Traefik application proxy.

This means plugins do not need to be compiled and no elaborate toolchain is required to get started. The process of developing Traefik plugins is comparable to that of web browser extensions.

To start developing your own plugin, view the required skeleton and the code, and explore further, please visit the middleware demo plugin and the provider demo plugin GitHub repositories.

Experimental Features

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

Developing Plugins

Developing Traefik Plugins requires respecting a specific code architecture to allow the plugins to be used by Traefik as a middleware or a provider.

Depending on the plugin type, either middleware or provider, the required architecture is not the same.

You can find further information in both the middleware demo plugin and the provider demo plugin GitHub repositories.

Packaging Plugins

As mentioned in the Plugin Installation section, Traefik admins can browse and add plugins to their instances from the Plugin Catalog.

From a technical perspective, the actual code for each plugin is stored and hosted in a public GitHub repository. Every 30 minutes, the Plugin Catalog polls GitHub to find repositories that match the criteria for a Traefik plugin and adds them.

To be recognized by the Plugin Catalog, your plugin’s catalog must meet a couple of criteria and contain a manifest that provides the Plugin Catalog with information about your plugin.

You can find further information in both the middleware demo plugin and the provider demo plugin GitHub repositories.

Tags and Dependencies

The Plugin Catalog gets your sources from a Go module proxy, so your plugins need to be versioned with a git tag.

Local Mode

The local mode described in the Plugin Installation section can be used to develop and test locally a plugin before hosting it on Github.

Troubleshooting

If something goes wrong with the integration of your plugin, the Plugin Catalog will create an issue inside your GitHub repository explaining the problem and will stop trying to add your plugin until you close the issue.

In order for your plugin to be successfully imported by the Plugin Catalog, consult this checklist:

  • The traefik-plugin topic must be set on your repository.
  • There must be a .traefik.yml file at the root of your project describing your plugin, and it must have a valid testData property for testing purposes.
  • There must be a valid go.mod file at the root of your project.
  • Your plugin must be versioned with a git tag.
  • If you have package dependencies, they must be vendored and added to your GitHub repository.