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 useTo 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-repositoryLocal 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=v2A 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.