Skip to content

Traefik Plugins Experimental Configuration

Overview

This guide provides instructions on how to configure and use the new experimental plugins install configuration option in Traefik. The plugins option introduces a system to extend Traefik capabilities with custom middlewares and providers.

Experimental

The plugins option is currently experimental and subject to change in future releases. Use with caution in production environments.

Enabling Plugins

The plugins option is an install configuration parameter. To enable a plugin, you need to define it in your Traefik install configuration

experimental:
  plugins:
    plugin-name: # The name of the plugin in the routing configuration
      moduleName: "github.com/github-organization/github-repository" # The plugin module name
      version: "vX.XX.X" # The version to use
[experimental.plugins.plugin-name]
  moduleName = "github.com/github-organization/github-repository" # The plugin module name
  version = "vX.XX.X" # The version to use
# The plugin module name
# With plugin-name the name of the plugin in the routing configuration
--experimental.plugins.plugin-name.modulename=github.com/github-organization/github-repository
--experimental.plugins.plugin-name.version=vX.XX.X # The version to use

To learn more about how to add a new plugin to a Traefik instance, please refer to the developer documentation.

Plugin Options

Field Description Type Required
moduleName Plugin's module name. string Yes
version Plugin's version. string Yes
hash Plugin's hash to validate. string No
settings Plugin's settings (wasm plugins; useUnsafe also applies to Yaegi plugins, mounts and fileMapping to Yaegi v2 plugins). object No
settings.envs Environment variables to forward to the wasm guest. []string No
settings.mounts Directory to mount to the wasm guest. For Yaegi v2 plugins, the only directories the plugin can reach by path (dir or dir:ro). No mount gives the whole file system. []string No
settings.useUnsafe Allow the plugin to use unsafe and syscall packages. bool No
settings.fileMapping Allow a Yaegi v2 plugin to lock and map its own files (flock, mmap). Requires useUnsafe. bool No

Local Plugins

Local plugins allow you to use plugins from a local directory, without publishing them to the Traefik plugin catalog.

experimental:
  localPlugins:
    plugin-name: # The name of the plugin in the routing configuration
      moduleName: "github.com/github-organization/github-repository" # The plugin module name
[experimental.localPlugins.plugin-name]
  moduleName = "github.com/github-organization/github-repository" # The plugin module name
# The plugin module name
# With plugin-name the name of the plugin in the routing configuration
--experimental.localplugins.plugin-name.modulename=github.com/github-organization/github-repository

Local Plugin Options

Field Description Type Required
moduleName Plugin's module name. string Yes
settings Plugin's settings (wasm plugins; useUnsafe also applies to Yaegi plugins, mounts and fileMapping to Yaegi v2 plugins). object No
settings.envs Environment variables to forward to the wasm guest. []string No
settings.mounts Directory to mount to the wasm guest. For Yaegi v2 plugins, the only directories the plugin can reach by path (dir or dir:ro). No mount gives the whole file system. []string No
settings.useUnsafe Allow the plugin to use unsafe and syscall packages. bool No
settings.fileMapping Allow a Yaegi v2 plugin to lock and map its own files (flock, mmap). Requires useUnsafe. bool No

Runtime Version

Yaegi plugins only

The defaultRuntimeVersion option and the runtimeVersion manifest field only apply to Yaegi plugins. They have no effect on Wasm plugins.

Yaegi plugins run with Yaegi v1 by default. The defaultRuntimeVersion option selects the version of the Yaegi interpreter, v1 (default) or v2, for all the Yaegi plugins.

experimental:
  defaultRuntimeVersion: v2
[experimental]
  defaultRuntimeVersion = "v2"
--experimental.defaultruntimeversion=v2

A Yaegi plugin can also ask for Yaegi v2 in its manifest (.traefik.yml), with runtimeVersion: v2. Such a plugin always runs with Yaegi v2, whatever the value of the defaultRuntimeVersion option. A manifest cannot ask for Yaegi v1.

Yaegi v2 only loads plugins that the Go compiler accepts, and limits the CPU time, the memory and the number of goroutines of a plugin. A plugin that Yaegi v2 cannot load is reported as a plugin load failure.