example-plugin

Example plugin of the engine's source tree.

Category GeneralAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin example-pluginPriority 0

What it does

example-plugin is the sample plugin of the engine's source code, there for trying out how a plugin is added to a route and saved. It does no work for your clients. I, S and T are read by nothing but the log line it writes in each phase.

IP is the one setting that changes where requests go. An address there replaces the route's upstream for every request and is used exactly as written. Leave it and Port empty on a route whose backend should answer.

When to use it

• Trying out on a route no client calls how a plugin is added, saved and shown in the console.
• Showing a new team member what the plugin metadata is, with Ikey and Skey shared by every route that carries the plugin.
• Checking that a change saved in the console reaches the gateway nodes, by finding the plugin's log line there.

Not for making a route fail or slow on purpose — see fault-injection (Injects delays or fixed responses for testing), answering with a made-up response and no backend at all — see mocking (Answers requests with a mocked response instead of an upstream) or running code of your own on a route — see serverless-pre-function (Runs Lua functions before the other plugins of a phase).

Set it up

Try the sample plugin with a number and a string

The plugin only writes its settings to the gateway's log in each phase; the request goes on unchanged.

Set I to 3 and set S to hello.

example-plugin · as the console saves it

{
  "i": 3,
  "s": "hello"
}

More scenarios

Give the sample plugin the two settings every route that carries it sharesenvironment-wide settings

The plugin only writes them to the gateway's log; the request goes on unchanged.

Set Ikey to 10 and set Skey to shared.

example-plugin environment-wide settings · as the console saves it

{
  "ikey": 10,
  "skey": "shared"
}

Things to know

• I — A configuration without I is refused when you save.
• I — A number below 0, -1 for example, is refused when you save.
• T — An empty list is refused when you save.
• IP — An address here replaces the route’s upstream for every request and is used exactly as written, so a host name is not resolved and the request fails.
• IP — An address with a scheme, http://127.0.0.1 for example, is refused when you save.
• IP — An address without a port is refused when you save.
• Port — Read only beside an address: on its own it is stored and never looked at, and the request goes to the object's own upstream.
• Port — A port above 65535, 70000 for example, is refused when you save.
• Plugin metadata without Ikey is refused when you save.
• Plugin metadata without Skey is refused when you save.
• AdviceKeep the plugin off routes your clients call.

Settings

The fields as the console shows them, section by section.

IinumberRequired

Read by nothing but the log line the plugin writes in each phase, like s and t.

at least 0

Ssstring

Ttarray

at least 1 item · example ["one",2]

IPipstring

Needs Port beside it.

a host name, with an optional leading wildcard, or * alone

pattern

^\*$|^\*?[0-9a-zA-Z-._\[\]:]+$

Portportinteger

1 to 65535

Environment-wide settings

Set once per environment, under Plugins › example-plugin. Every example-plugin in the environment uses these.

IkeyikeynumberRequired

at least 0

SkeyskeystringRequired

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.