Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/blesswinsamuel/traefik-request-headers-middleware
https://github.com/blesswinsamuel/traefik-request-headers-middleware
traefik-plugin
Last synced: 6 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/blesswinsamuel/traefik-request-headers-middleware
- Owner: blesswinsamuel
- License: apache-2.0
- Created: 2024-08-04T11:58:44.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2024-08-04T12:31:50.000Z (3 months ago)
- Last Synced: 2024-09-13T14:09:28.125Z (2 months ago)
- Topics: traefik-plugin
- Language: Go
- Homepage:
- Size: 36.1 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
README
This repository includes an example plugin, `demo` using [http-wasm](https://http-wasm.io/), for you to use as a reference for developing your own plugins.
[](https://github.com/traefik/plugindemowasm/actions)
The existing plugins can be browsed into the [Plugin Catalog](https://plugins.traefik.io).
# Developing a Traefik plugin
[Traefik](https://traefik.io) plugins are developed using [http-wasm](https://http-wasm.io/).
## Usage
For a plugin to be active for a given Traefik instance, it must be declared in the static configuration.
Plugins are parsed and loaded exclusively during startup, which allows Traefik to check the integrity of the code and catch errors early on.
If an error occurs during loading, the plugin is disabled.
For security reasons, it is not possible to start a new plugin or modify an existing one while Traefik is running.
Once loaded, middleware plugins behave exactly like statically compiled middlewares.
Their instantiation and behavior are driven by the dynamic configuration.
### Configuration
For each plugin, the Traefik static configuration must define the module name (as is usual for Go packages).
The following declaration (given here in YAML) defines a plugin:
```yaml
# Static configuration
experimental:
plugins:
example:
moduleName: github.com/traefik/plugindemowasm
version: v0.0.1
```
Here is an example of a file provider dynamic configuration (given here in YAML), where the interesting part is the `http.middlewares` section:
```yaml
# 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).
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
└── plugindemowasm
├── plugin.wasm
└── .traefik.yml
```
```yaml
# Static configuration
experimental:
localPlugins:
example:
moduleName: github.com/traefik/plugindemowasm
```
(In the above example, the `plugindemowasm` plugin will be loaded from the path `./plugins-local/src/github.com/traefik/plugindemowasm`.)
```yaml
# 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
ABI is available [here](https://http-wasm.io/http-handler-abi/)
```go
package main
import (
"encoding/json"
"fmt"
"os"
"github.com/http-wasm/http-wasm-guest-tinygo/handler"
"github.com/http-wasm/http-wasm-guest-tinygo/handler/api"
)
// Config the plugin configuration.
type Config struct {
Headers map[string]string `json:"headers,omitempty"`
}
func main() {
var config Config
err := json.Unmarshal(handler.Host.GetConfig(), &config)
if err != nil {
handler.Host.Log(api.LogLevelError, fmt.Sprintf("Could not load config %v", err))
os.Exit(1)
}
mw, err := New(config)
if err != nil {
handler.Host.Log(api.LogLevelError, fmt.Sprintf("Could not load config %v", err))
os.Exit(1)
}
handler.HandleRequestFn = mw.handleRequest
}
// Demo a Demo plugin.
type Demo struct{}
// New created a new Demo plugin.
func New(config Config) (*Demo, error) {
return &Demo{}, nil
}
func (d Demo) handleRequest(req api.Request, resp api.Response) (next bool, reqCtx uint32) {
return true, 0
}
```
## Plugins Catalog
Traefik plugins are stored and hosted as public GitHub repositories.
Every 30 minutes, the Plugins Catalog online service polls Github to find plugins and add them to its catalog.
### Prerequisites
To be recognized by Plugins Catalog, 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.
- You need a zip archive in the release assets containing the wasm file (by default `plugin.wasm`) and the `.traefik.yml` file.
If your repository fails to meet either of these prerequisites, Plugins Catalog 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 Plugins Catalog with information about your plugin, such as a description, a full name, and so on.
Here is an example of a typical `.traefik.yml`file:
```yaml
# The name of your plugin as displayed in the Plugins Catalog web UI.
displayName: Name of your plugin
# For now, `middleware` is the only type available.
type: middleware
runtime: wasm
# 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 Plugins Catalog 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 Plugins Catalog web UI.
- `type` (required): For now, `middleware` is the only type available.
- `runtime` (required): The runtime `wasm`.
- `summary` (required): A brief description of what your plugin is doing.
- `testData` (required): Configuration data for your plugin. This is mandatory, and Plugins Catalog 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.
### Tags and Dependencies
Your plugins need to be versioned with a git tag.
If something goes wrong with the integration of your plugin, Plugins Catalog will create an issue inside your Github repository and will stop trying to add your repo until you close the issue.
## Troubleshooting
If Plugins Catalog 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 Plugins Catalog, 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.
- Your plugin must be versioned with a git tag.