Plugin config

Plugin configs hold a set of plugins that several routes reference.

In the console Plugin configsEngine resource plugin_config

What a plugin config is

A plugin config holds a set of plugins that several routes share. A route names it under Plugin config, in its Plugins section, and runs the config's plugins together with its own. You add the plugins in the config's own Plugins tab once it exists.

A plugin config carries no backend: each route keeps its own target, nodes of its own or a service. Where a route carries the same plugin as its config, the route's own copy is used whole, and the config's other plugins still apply. Where a plugin runs shows how it sits beside the other places a plugin can live.

When to use it

• Every route the web app calls from the browser needs the same CORS policy and the same rate limit, for example 100 requests a minute for each client address.
• Routes that reach different backends, each with nodes of its own, should run one set of plugins that you change in one place.
• One route needs other settings for one plugin of the set, for example a cors with an origin of its own, and keeps the rest of the set.

Not for routes of one backend that share its instances as well as its plugins — see Service (Services hold the upstream and plugins that several routes share), plugins that run on every request of the environment, whatever the route — see Global rule (Global rules run their plugins on every request the engine handles) or a plugin's settings for the whole environment — see Environment-wide settings (Environment-wide settings are shared by every use of a plugin in the environment and are edited on the plugin's page).

Set it up

Share one rate limit and one CORS policy across public routes

A route carries it by its ID under Plugin config, beside its own plugins.

Under General set ID to public-api-defaults, set Name to Public API defaults, set Description to Attached to every route the web app calls from the browser and fill Labels as in the JSON below. Once it is created, open its Plugins tab and add cors and limit-count, each with its settings from the JSON below.

plugin_config · as the console saves it

{
  "id": "public-api-defaults",
  "name": "Public API defaults",
  "desc": "Attached to every route the web app calls from the browser",
  "labels": {
    "audience": "public"
  },
  "plugins": {
    "cors": {
      "allow_origins": "https://app.example.com",
      "allow_methods": "GET,POST,PUT,DELETE",
      "allow_headers": "Authorization,Content-Type"
    },
    "limit-count": {
      "count": 100,
      "time_window": 60,
      "key": "remote_addr",
      "rejected_code": 429
    }
  }
}

Things to know

• Plugins — A route that names public-api-defaults answers a browser from https://app.example.com with Access-Control-Allow-Methods: GET,POST,PUT,DELETE and X-Ratelimit-Limit: 100, both from the config.
• Plugins — A route with cors settings of its own uses them instead of the config's: it answers a browser from https://orders.example.com with Access-Control-Allow-Origin: https://orders.example.com, and still carries the config's limit of 100.
• Plugins — For the same plugin, the route's settings win over the plugin config's, and the plugin config's over the service's.
• Plugins — Routes that name a plugin config gain nothing until it holds a plugin.
• A plugin config that routes still name cannot be deleted: g8 refuses the delete while they still use it. Clear Plugin config on each route first.
• AdviceKeep in a plugin config only what every route that names it needs, and add a plugin that one route alone needs to that route.

Settings

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

General

IDidstring or integerRequired

Letters, digits, dots, hyphens and underscores, up to 64 characters. The ID cannot be changed later.

string 1 to 64 characters or integer at least 1 · letters, digits, dots, hyphens and underscores

pattern

^[a-zA-Z0-9-_.]+$

NamenamestringRequired

Descriptiondescstring

up to 256 characters

Labelslabelsobject

Key and value pairs of your own, for grouping and filtering. They change nothing about traffic. An object whose keys are any name, each with a string as its value.

Plugins

Plugins on this plugin config are managed in the Plugins tab once the plugin config exists. Routes that name the config run them together with their own plugins.

PluginspluginsobjectRequired

The plugins of this plugin config, keyed by plugin name. The engine runs them by their priority, not by the order they are written in.