Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update local plugin documentation #13

Merged
merged 2 commits into from
Aug 17, 2021
Merged

Update local plugin documentation #13

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
465ded2
doc: update local plugin
jbdoumenjou Jun 24, 2021
3d00294
Update readme.md
ldez Jun 29, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 26 additions & 13 deletions readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ For security reasons, it is not possible to start a new plugin or modify an exis
Once loaded, middleware plugins behave exactly like statically compiled middlewares.
Their instantiation and behavior are driven by the dynamic configuration.

Plugin dependencies must be [vendored](https://golang.org/ref/mod#tmp_25) for each plugin.
Plugin dependencies must be [vendored](https://golang.org/ref/mod#vendoring) for each plugin.
Vendored packages should be included in the plugin's GitHub repository. ([Go modules](https://blog.golang.org/using-go-modules) are not supported.)

### Configuration
Expand Down Expand Up @@ -68,23 +68,40 @@ http:
Foo: Bar
```

### Dev Mode
### 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 dev mode, the Traefik static configuration must define the module name (as is usual for Go packages) and a path to a [Go workspace](https://golang.org/doc/gopath_code.html#Workspaces), which can be the local GOPATH or any directory.
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](https://golang.org/doc/gopath_code.html#Workspaces), which can be the local GOPATH or any directory.

The plugins must be placed in `./plugins-local` directory, which should be next to 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
```

```yaml
# Static configuration
pilot:
token: xxxxx

experimental:
devPlugin:
goPath: /plugins/go
moduleName: github.com/traefik/plugindemo
localPlugins:
example:
moduleName: github.com/traefik/plugindemo
```

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

```yaml
# Dynamic configuration
Expand All @@ -108,15 +125,11 @@ http:
middlewares:
my-plugin:
plugin:
dev:
example:
headers:
Foo: Bar
```

#### Dev Mode Limitations

Note that only one plugin can be tested in dev mode at a time, and when using dev mode, Traefik will shut down after 30 minutes.

## Defining a Plugin

A plugin package must define the following exported Go objects:
Expand Down Expand Up @@ -150,7 +163,7 @@ func CreateConfig() *Config {
type Example struct {
next http.Handler
name string
// ...
// ...
}

// New created a new plugin.
Expand Down