Developing a Traefik plugin

# Dynamic configuration

http:
  routers:
    my-router:
      rule: host(`demo.localhost`)
      service: service-foo
      entryPoints:
        - web
      middlewares:
        - my-plugin

  services:
   service-foo:
      loadBalancer:
        servers:
          - url: http://127.0.0.1:5000
  
  middlewares:
    my-plugin:
      plugin:
        example:
          headers:
            Foo: Bar

Local Mode

Traefik also offers a developer mode that can be used for temporary testing of plugins not hosted on GitHub. To use a plugin in local mode, the Traefik static configuration must define the module name (as is usual for Go packages) and a path to a Go workspace, which can be the local GOPATH or any directory.

The plugins must be placed in ./plugins-local directory, which should be in the working directory of the process running the Traefik binary. The source code of the plugin should be organized as follows:

./plugins-local/
    └── src
        └── github.com
            └── traefik
                └── plugindemo
                    ├── demo.go
                    ├── demo_test.go
                    ├── go.mod
                    ├── LICENSE
                    ├── Makefile
                    └── readme.md

# Static configuration
pilot:
  token: xxxxx

experimental:
  localPlugins:
    example:
      moduleName: github.com/traefik/plugindemo

(In the above example, the plugindemo plugin will be loaded from the path ./plugins-local/src/github.com/traefik/plugindemo.)

# Dynamic configuration

http:
  routers:
    my-router:
      rule: host(`demo.localhost`)
      service: service-foo
      entryPoints:
        - web
      middlewares:
        - my-plugin

  services:
   service-foo:
      loadBalancer:
        servers:
          - url: http://127.0.0.1:5000
  
  middlewares:
    my-plugin:
      plugin:
        example:
          headers:
            Foo: Bar

Defining a Plugin

A plugin package must define the following exported Go objects:

• A type type Config struct { ... }. The struct fields are arbitrary.
• A function func CreateConfig() *Config.
• A function func New(ctx context.Context, next http.Handler, config *Config, name string) (http.Handler, error).

// Package example a example plugin.
package example

import (
	"context"
	"net/http"
)

// Config the plugin configuration.
type Config struct {
	// ...
}

// CreateConfig creates the default plugin configuration.
func CreateConfig() *Config {
	return &Config{
		// ...
	}
}

// Example a plugin.
type Example struct {
	next     http.Handler
	name     string
	// ...
}

// New created a new plugin.
func New(ctx context.Context, next http.Handler, config *Config, name string) (http.Handler, error) {
	// ...
	return &Example{
		// ...
	}, nil
}

func (e *Example) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
	// ...
	e.next.ServeHTTP(rw, req)
}

Traefik Pilot

Traefik plugins are stored and hosted as public GitHub repositories.

Every 30 minutes, the Traefik Pilot online service polls Github to find plugins and add them to its catalog.

Prerequisites

To be recognized by Traefik Pilot, your repository must meet the following criteria:

• The traefik-plugin topic must be set.
• The .traefik.yml manifest must exist, and be filled with valid contents.

If your repository fails to meet either of these prerequisites, Traefik Pilot will not see it.

Manifest

A manifest is also mandatory, and it should be named .traefik.yml and stored at the root of your project.

This YAML file provides Traefik Pilot with information about your plugin, such as a description, a full name, and so on.

Here is an example of a typical .traefik.ymlfile:

# The name of your plugin as displayed in the Traefik Pilot web UI.
displayName: Name of your plugin

# For now, `middleware` is the only type available.
type: middleware

# The import path of your plugin.
import: github.com/username/my-plugin

# A brief description of what your plugin is doing.
summary: Description of what my plugin is doing

# Medias associated to the plugin (optional)
iconPath: foo/icon.png
bannerPath: foo/banner.png

# Configuration data for your plugin.
# This is mandatory,
# and Traefik Pilot will try to execute the plugin with the data you provide as part of its startup validity tests.
testData:
  Headers:
    Foo: Bar

Properties include:

• displayName (required): The name of your plugin as displayed in the Traefik Pilot web UI.
• type (required): For now, middleware is the only type available.
• import (required): The import path of your plugin.
• summary (required): A brief description of what your plugin is doing.
• testData (required): Configuration data for your plugin. This is mandatory, and Traefik Pilot will try to execute the plugin with the data you provide as part of its startup validity tests.
• iconPath (optional): A local path in the repository to the icon of the project.
• bannerPath (optional): A local path in the repository to the image that will be used when you will share your plugin page in social medias.

There should also be a go.mod file at the root of your project. Traefik Pilot will use this file to validate the name of the project.

Tags and Dependencies

Traefik Pilot gets your sources from a Go module proxy, so your plugins need to be versioned with a git tag.

Last but not least, if your plugin middleware has Go package dependencies, you need to vendor them and add them to your GitHub repository.

If something goes wrong with the integration of your plugin, Traefik Pilot will create an issue inside your Github repository and will stop trying to add your repo until you close the issue.

Troubleshooting

If Traefik Pilot fails to recognize your plugin, you will need to make one or more changes to your GitHub repository.

In order for your plugin to be successfully imported by Traefik Pilot, 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.

Sample Code

This repository includes an example plugin, demo, for you to use as a reference for developing your own plugins.