Learn Traefik - Plugins & Extensibility

#Introduction

Traefik's built-in middlewares are complete, but the real world always has additional needs. Episode 29 covers plugins: custom middlewares that extend Traefik without changing the core. From ready-to-use community plugins to developing your own plugin in Go.

Traefik's plugin architecture is simple: each plugin is a Go module implementing the middleware interface. Traefik v3 loads plugins through the Yaegi interpreter — so plugins can be enabled without rebuilding the image, even though they are compiled to Go. Let us explore the plugin marketplace, how to install, and how to write them.

#The Plugin Ecosystem

#Marketplace and Community

Plugins are distributed through Traefik Hub (formerly Traefik Pilot) — the official catalog that can be searched and installed directly. Besides that, many open-source plugins circulate on GitHub with the same installation pattern.

Some popular plugin categories:

• GeoIP blocking: restricts access based on the IP's country of origin.
• Request/response logging: additional detail beyond the built-in access log.
• Custom authentication: integration with specialized auth mechanisms.
• Advanced rate limiting: more complex key-based policies.
• ModSecurity WAF: a Web Application Firewall layer with OWASP rules.

#Installing Plugins

#LocalPlugins in Static Config

Plugins are installed through static configuration. The simplest way is experimental.localPlugins, which loads code from a local directory:

experimental:
  localPlugins:
    geo-block:
      moduleName: github.com/yourorg/geo-block

services:
  traefik:
    image: traefik:v3
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./config/plugins:/plugins-local/src/github.com/yourorg/geo-block

Plugins from Traefik Hub are installed with a different pattern — via a Hub token and experimental.plugins configuration with a specific version. Once registered, a plugin is used like a regular middleware:

http:
  middlewares:
    geo-filter:
      plugin:
        geo-block:
          allowedCountries:
            - "ID"
            - "SG"
  routers:
    app:
      rule: "Host(`app.example.com`)"
      entrypoints:
        - web
      service: app-svc
      middlewares:
        - geo-filter

#Plugin Architecture

#Go Module and HTTP Handler

A plugin is a Go module with this structure:

geo-block/
├── go.mod
├── plugin.toml
├── geo_block.go
└── geo_block_test.go

The plugin core implements the http.Handler interface — receives a request, does the logic, then calls the next handler:

package geoblock
 
import "net/http"
 
type Config struct {
    AllowedCountries []string `json:"allowedCountries"`
}
 
func New(ctx context.Context, next http.Handler, config Config, name string) (http.Handler, error) {
    return http.HandlerFunc(func(rw http.ResponseWriter, req *http.Request) {
        if !isAllowed(req) {
            rw.WriteHeader(http.StatusForbidden)
            return
        }
        next.ServeHTTP(rw, req)
    }), nil
}

The New function receives the user-defined configuration and returns a handler that wraps next. As long as context and net/http are available, a plugin can do anything a middleware does.

#plugin.toml

The plugin.toml file is the metadata that makes Traefik recognize a plugin:

[plugin]
description = "Geo blocking by country"
version = "0.1.0"
[go]
version = "1.21"
[go.mod]
module = "github.com/yourorg/geo-block"

• description: a short description.
• version: the plugin version.
• go.mod.module: the Go module name — must match the moduleName in the Traefik configuration.

#Versioning and Testing

#Development Practices

• Versioning: tag releases with semantic versioning; Traefik Hub plugins pin a version at install time.
• Testing: write unit tests for the middleware logic before using it in production.
• Staging first: test the plugin in a staging environment before production — a buggy plugin can take down the entire routing pipeline.
• Pin versions: do not use latest; specify an explicit version so behavior is reproducible.

#Closing

Key takeaways:

• Plugins extend Traefik as custom middlewares.
• The main plugin catalog is Traefik Hub; many community plugins are on GitHub.
• Local installation via experimental.localPlugins and directory mounts.
• A plugin is a Go module with plugin.toml and the http.Handler interface.
• Versioning, testing, and staging are required before production.
• Limit the number of plugins; review third-party plugin code.

In episode 30 next — the final episode of this series — we will bring all the lessons together: production checklist & best practices, a comparison of Traefik v2 versus v3, common pitfalls, and a complete checklist for a production-ready Traefik deployment.