You're viewing Apigee Edge documentation.
Go to the
Apigee X documentation. info
Edge Microgateway v. 2.4.x
Audience
This topic is intended for Edge Microgateway operators who wish to use existing plugins that are installed with the microgateway. It also discusses the spike arrest and quota plugins in detail (both are included with the installation). If you're a developer who wants to develop new plugins, see Developing custom plugins.
What is an Edge Microgateway plugin?
A plugin is a Node.js module that adds functionality to Edge Microgateway. Plugin modules follow a consistent pattern and are stored in a location known to Edge Microgateway, enabling the microgateway to discover and load them automatically. Edge Microgateway includes several existing plugins and you can also create custom plugins, as explained in Developing custom plugins.
Existing plugins bundled with Edge Microgateway
Several existing plugins are provided with Edge Microgateway at installation. These include:
Plugin | Enabled by default | Description |
---|---|---|
analytics | Yes | Sends analytics data from Edge Microgateway to Apigee Edge. |
oauth | Yes | Adds OAuth token and API Key validation to Edge Microgateway. See Setting up and configuring Edge Microgateway. |
quota | No | Enforces quota on requests to Edge Microgateway. Uses Apigee Edge to store and manage the quotas. See Using the quota plugin. |
spikearrest | No | Protects against traffic spikes and DoS attacks. See Using the spike arrest plugin. |
header-uppercase | No | A commented, sample proxy intended as a guide to help developers write custom plugins. See Edge Microgateway sample plugin. |
accumulate-request | No | Accumulates request data into a single object before passing the data to the next handler in the plugin chain. Useful for writing transform plugins that need to operate on a single, accumulated request content object. |
accumulate-response | No | Accumulates response data into a single object before passing the data to the next handler in the plugin chain. Useful for writing transform plugins that need to operate on a single, accumulated response content object. |
transform-uppercase | No | Transforms request or response data. This plugin represents a best practice implementation of a transform plugin. The example plugin performs a trivial transform (converts request or response data to uppercase); however, it can easily be adapted to perform other kinds of transformations, such as XML to JSON. |
json2xml | No | Transforms request or response data based on accept or content-type headers. For details, refer to the plugin documentation in GitHub. |
quota-memory | No | Enforces quota on requests to Edge Microgateway. Stores and manages quotas in local memory. |
healthcheck | No | Returns information about the Edge Microgateway process -- memory usage, cpu usage, etc. To use the plugin, call the URL /healthcheck on your Edge Microgateway instance. This plugin is intended to be an example that you can use to implement your own health checking plugin. |
Where to find existing plugins
Existing plugins bundled with Edge Microgateway are located here,
where [prefix]
is the npm
prefix directory.
See Where
is Edge Microgateway installed.
[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins
Adding and configuring plugins
Follow this pattern to add and configure plugins:
- Stop Edge Microgateway.
- Open an Edge Microgateway configuration file. For details, see Making configuration changes for options.
- Add the plugin to the
plugins:sequence
element of the config file, as follows. Plugins are executed in the order they appear in this list.
edgemicro: home: ../gateway port: 8000 max_connections: -1 max_connections_hard: -1 logging: level: info dir: /var/tmp stats_log_interval: 60 plugins: dir: ../plugins sequence: - oauth - plugin-name
- Configure the plugin. Some plugins have optional parameters that you can configure in the
config file. For example, you can add the following stanza to configure the spike arrest
plugin. See Using the spike arrest
plugin for more information.
edgemicro: home: ../gateway port: 8000 max_connections: -1 max_connections_hard: -1 logging: level: info dir: /var/tmp stats_log_interval: 60 plugins: dir: ../plugins sequence: - oauth - spikearrest spikearrest: timeUnit: minute allow: 10
- Save the file.
- Restart or reload Edge Microgateway, depending on which configuration file you edited, as explained in Making configuration changes.
Plugin-specific configuration
You can override the plugin parameters specified in the config file by creating a plugin-specific configuration in this directory:
[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins/config
where [prefix]
is the npm
prefix directory.
See Where
is Edge Microgateway installed.
plugins/<plugin_name>/config/default.yaml
. For example, you could put this
block in plugins/spikearrest/config/default.yaml
, and they will override any
other config settings.
spikearrest: timeUnit: hour allow: 10000 buffersize: 0
Using the spike arrest plugin
This section discusses the spike arrest plugin.
About spike arrest
Spike Arrest protects against traffic spikes. It throttles the number of requests processed by an Edge Microgateway instance. For more information, see How does spike arrest work? See also What's the difference between spike arrest and quota?.
Adding the spike arrest plugin
For the basic steps to follow for any plugin, see Adding and configuring plugins.
Sample configuration for spike arrest
edgemicro: home: ../gateway port: 8000 max_connections: -1 max_connections_hard: -1 logging: level: info dir: /var/tmp stats_log_interval: 60 plugins: dir: ../plugins sequence: - oauth - spikearrest spikearrest: timeUnit: minute allow: 10 bufferSize: 5
Configuration options for spike arrest
- timeUnit: How often the spike arrest execution window resets. Valid values are second or minute.
- allow: The maximum number of requests to allow during the timeUnit.
- bufferSize: (optional, default = 0) if bufferSize > 0, spike arrest stores this number of requests in a buffer. As soon as the next execution "window" occurs, the buffered requests will be processed first. See also Adding a buffer.
How does spike arrest work?
Think of spike arrest as a way to generally protect against traffic spikes rather than as a way to limit traffic to a specific number of requests. Your APIs and backend can handle a certain amount of traffic, and the spike arrest policy helps you smooth traffic to the general amounts you want.
The runtime spike arrest behavior differs from what you might expect to see from the literal per-minute or per-second values you enter.
For example, say you specify a rate of 30 requests per minute, like this:
spikearrest: timeUnit: minute allow: 30
In testing, you might think you could send 30 requests in 1 second, as long as they came within a minute. But that's not how the policy enforces the setting. If you think about it, 30 requests inside a 1-second period could be considered a mini spike in some environments.
What actually happens, then? To prevent spike-like behavior, spike arrest smooths the allowed traffic by dividing your settings into smaller intervals, as follows:
Per-minute rates
Per-minute rates get smoothed into requests allowed intervals of seconds. For example, 30 requests per minute gets smoothed like this:
60 seconds (1 minute) / 30 = 2-second intervals, or about 1 request allowed every 2 seconds. A second request inside of 2 seconds will fail. Also, a 31st request within a minute will fail.
Per-second rates
Per-second rates get smoothed into requests allowed in intervals of milliseconds. For example, 10 requests/second gets smoothed like this:
1000 milliseconds (1 second) / 10 = 100-millisecond intervals, or about 1 request allowed every 100 milliseconds . A second request inside of 100ms will fail. Also, an 11th request within a second will fail.
When the limit is exceeded
If the number of requests exceeds the limit within the specified time interval, spike alert returns this error message with an HTTP 503 status:
{"error": "spike arrest policy violated"}
Adding a buffer
You have an option of adding a buffer to the policy. Let's say you set the buffer to 10. You'll see that the API does not return an error immediately when you exceed the spike arrest limit. Instead, requests are buffered (up to the number specified), and the buffered requests are processed as soon as the next appropriate execution window is available. The default bufferSize is 0.
Using the quota plugin
This section discusses the quota plugin.
About the quota plugin
A quota specifies the number of request messages that an app is allowed to submit to an API over the course of an hour, day, week, or month. When an app reaches its quota limit, subsequent API calls are rejected. See also What's the difference between spike arrest and quota?.
Adding the quota plugin
For the basic steps to follow for any plugin, see Adding and configuring plugins.
Product configuration in Apigee Edge
You configure quotas in the Apigee Edge UI where you configure API products. You need to know which product contains the microgateway-aware proxy that you want to limit with a quota. This product must be added to a developer app. When you make API calls that are authenticated using keys in the developer app, the quota will be applied to those API calls.
- Log in to your Apigee Edge organization account.
- In the Edge UI, open the product associated with the microgateway-aware proxy to which
you want to apply the quota.
- In the UI, select Products from the Publish menu.
- Open the product containing the API to which you want to apply the quota.
- Click Edit.
- In the Quota field, specify the quota interval. For example, 100 requests every
one minute. Or 50000 requests every 2 hours.
- Click Save.
- Be sure the product is added to a developer app. You'll need the keys from this app to make authenticated API calls.
Sample configuration for quota
edgemicro: home: ../gateway port: 8000 max_connections: -1 max_connections_hard: -1 logging: level: info dir: /var/tmp stats_log_interval: 60 plugins: dir: ../plugins sequence: - oauth - quota
Configuration options for quota
There are no additional configuration options for the quota plugin.
Testing the quota plugin
When the quota is exceeded, an HTTP 403 status is returned to the client, along with the following message:
{"error": "exceeded quota"}
What's the difference between spike arrest and quota?
It’s important to choose the right tool for the job at hand. Quota policies configure the number of request messages that a client app is allowed to submit to an API over the course of an hour, day, week, or month. The quota policy enforces consumption limits on client apps by maintaining a distributed counter that tallies incoming requests.
Use a quota policy to enforce business contracts or SLAs with developers and partners, rather than for operational traffic management. For example, a quota might be used to limit traffic for a free service, while allowing full access for paying customers. See also Using the quota plugin.
Use spike arrest to protect against sudden spikes in API traffic. Typically, spike arrest is used to head off possible DDoS or other malicious attacks.