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.

There are two ways to develop plugins in Traefik:

With Yaegi

Traefik Yaegi plugins are developed using the Go language. A Traefik plugin is essentially a Go package. Unlike pre-compiled plugins, Yaegi plugins are executed on the fly by Yaegi, a Go interpreter embedded in Traefik.

This approach eliminates the need for compilation and a complex toolchain, making plugin development as straightforward as creating web browser extensions.

To begin developing your own plugin, refer to the required skeleton and code in the following GitHub repositories:

• Middleware Demo Plugin
• Provider Demo Plugin

With Wasm

Traefik Wasm plugins can be developed using any language that compiles to WebAssembly (Wasm). This method is based on http-wasm.

For a starting point, view the required skeleton, code, and CI (release steps) in these example plugins:

• Wasm Middleware Demo Plugin
• Wasm Middleware Demo with HTTP Call Plugin

Developing Plugins With Yaegi

When developing Traefik plugins with Yaegi, adhere to a specific code architecture to ensure compatibility as middleware or a provider. The architecture varies depending on the plugin type.

For more information, check the GitHub repositories:

• Middleware Demo Plugin
• Provider Demo Plugin

Developing Plugins With Wasm

When developing Traefik plugins with Wasm, follow a specific code architecture based on http-wasm to ensure the plugins function as middleware.

For further details, refer to the following GitHub repositories:

• Wasm Middleware Demo Plugin
• Wasm Middleware Demo with HTTP Call Plugin

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 yaegi middleware demo plugin, the yaegi provider demo plugin, the wasm middleware demo plugin and the wasm middleware demo with http call 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:

• Your repository is not a fork: forks are not added to the catalog
• 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.

Remove a plugin from this catalog

Request to remove can be made with an issue on traefik/piceus repository.

On Go plugin, please note that it will only remove it from this catalog. The plugin code is published with Go Proxies.