Skip to content

Commit

Permalink
doc: update local plugin
Browse files Browse the repository at this point in the history
  • Loading branch information
jbdoumenjou committed Jun 24, 2021
1 parent e1c443b commit d388906
Showing 1 changed file with 26 additions and 13 deletions.
39 changes: 26 additions & 13 deletions readme.md
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
localPlugin:
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

0 comments on commit d388906

Please sign in to comment.