Expand Traefik Proxy with Custom Plugins | Traefik Labs

Plugins for Traefik Proxy were introduced back in September 2020 as a way to extend Traefik's capabilities with custom features and behaviors. With Traefik plugins, users can create, share, and integrate their own plugins easily.

Plugins are written in Go and are executed on the fly by Yaegi, an embedded Go interpreter in Traefik Proxy. Source code for each plugin is hosted in a GitHub public repository, and the catalog is updated automatically when a new plugin is published on GitHub.

While these plugins are public and open-sourced, hosting them in a centralized location serves as a way to block plugins that contain something malicious, and that was why, initially, plugins were hosted within Traefik Pilot. The catalog counts more than 100 plugins available to anyone using Traefik Proxy. As of today, plugins for Traefik will have a new home.

The Plugin Catalog

The Plugin Catalog is where users can find all of the available Traefik plugins and the information related to them. The Plugin Catalog is directly accessible from the Traefik dashboard (from Traefik Proxy 2.8 onward) and from the Traefik Labs homepage.

No token, no problem

There are some fundamental changes and enhancements brought about by the new Plugin Catalog. Firstly, forget about the token that was previously needed to install a plugin. The Plugin Catalog is fully public with no authentication needed to access any of its content, and as of now, users don’t need to register their Traefik instances and get a token before using any of the plugins. If you already use Traefik plugins in your current configuration, there is a little change you have to apply to continue using plugins, which is to remove the Pilot token.

For example, previously, the static configuration for the Simple Cache plugin via command line was:

 --pilot.token=xxxx
--experimental.plugins.plugin-simplecache.modulename=github.com/traefik/plugin-simplecache
--experimental.plugins.plugin-simplecache.version=v0.2.1

With the new Plugin Catalog, simply take off the token line, and all is well!

--experimental.plugins.plugin-simplecache.modulename=github.com/traefik/plugin-simplecache
--experimental.plugins.plugin-simplecache.version=v0.2.1

In short, now you can freely access the Plugin Catalog, see all of the available plugins to use, copy and paste the necessary code for static — and/or dynamic configuration of your preferred ones — and go crazy with it! Straightforward and easy as pie.

Note: If you are using plugins with a previous version of Traefik Proxy and you want to upgrade to 2.8, your plugins will still work but you’ll see a warning in the logs prompting you to remove the Pilot token.

Getting started with Traefik plugins

If you haven’t used plugins for Traefik Proxy yet, now is the time!

The Plugin Catalog UI was designed to deliver a seamless experience, such as copy-pasting ready configuration snippets in one click from the main page.

Choose a plugin to install and click on Install plugin. In the card that opens, you have access to the code you need to add to your Traefik Proxy static and/or dynamic configuration. You can also choose among YAML, TOML, CLI, or Kubernetes CRD snippets.

These configuration snippets are also accessible from the plugin’s details page. By clicking on any plugin from the list, you are able to see more details about it — complete documentation and previous versions, among others — and there is also an Install Plugin button on the top right corner that will show you the snippets.

Installing a plugin

To activate a plugin, you need to declare it on the static configuration of the Traefik instance, as it is parsed and loaded during startup to be able to catch errors early on. The plugin will be disabled if an error occurs during loading time. Here’s an example of a static configuration that is included in the YAML file to install the Simple Cache plugin:

 experimental:
  plugins:
    plugin-simplecache:
      moduleName: "github.com/traefik/plugin-simplecache"
      version: "v0.2.1"

Some plugins also need dynamic configuration to be added on top of the static configuration to control their instantiation and behavior. Here’s an example of a dynamic configuration that is included to install the Simple Cache plugin:

http:
    middlewares:
        my-plugin-simplecache:
            plugin:
                plugin-simplecache:
                    path: /tmp

You can get all of the necessary code to install the plugins directly from the Plugin Catalog. Note that it is not possible to start a new plugin or modify an existing one while Traefik is running; you’ll need to restart your Traefik instances after installing or modifying a plugin.

Embedded documentation

If you want to learn more about how to use plugins, or if you want to create one but are not sure how there is embedded documentation on how to install and create a plugin.

There are some specific criteria and code architecture to allow a plugin to be used by Traefik, so, on top of going through the documentation, and if needed, you can see more details about each type of plugins in the dedicated repositories for middleware demo plugin and provider demo plugin.

Ready, set, plug ‘n play!

So, that’s it! If you’re using Traefik v2.3 and later, you can directly go have fun with any plugins now (or create one, for that matter). As plugins are loaded dynamically and executed on the fly by an embedded interpreter, there is no need to compile binaries, it’s 100% cross-platform and easy to use for the broad Traefik community, hassle-free.

We wish for users to be able to utilize Traefik and adjust it according to their needs as painlessly as possible, and the Plugin Catalog is one of the tools to facilitate this. We will always work on enhancing our products with Traefik users in our mind, so give Plugin Catalog a try and let us know what you think!


This is a companion discussion topic for the original entry at https://traefik.io/blog/expand-the-power-of-traefik-proxy-with-custom-plugins/
2 Likes