Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

Use plugins

Edge Microgateway v. 2.1.x

Audience

This topic is intended for Edge Microgateway operators who wish to add existing plugins, like quota or spike arrest, to Edge Microgateway.

Getting started

If you're new to Edge Microgateway, the Setting up and configuring Edge Microgateway is the best place to start. The setup and configuration guide covers all the steps you need to do to install, configure, start, use and add plugins to an instance of Edge Microgateway.

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.

By default, Edge Microgateway is essentially a secure pass-through proxy that passes requests unchanged to a target. Through plugins, you can add features to the microgateway, such as support for Apigee Edge analytics, OAuth authentication, and rate limiting features like quotas and spike arrest.

Predefined plugins provided with Edge Microgateway

Several predefined plugins are provided with Edge Microgateway out-of-the-box. These include:

  • analytics - (Added by default) Sends analytics data from Edge Microgateway to Apigee Edge.
  • oauth - Adds OAuth token and API Key validation to Edge Microgateway. The steps needed to obtain and use a token are explained in the Setting up and configuring Edge Microgateway.
  • quota - Enforces quota on requests to Edge Microgateway. Uses Apigee Edge to store and manage the quotas. See Using the quota plugin.

    Note: If you want to use the quota plugin, you must use the oauth plugin, and the oauth plugin must be placed before quota in the plugin sequence. See Using the quota plugin for details.
     
  • spikearrest - Protects against traffic spikes and DoS attacks. See Using the spike arrest plugin.
  • header-uppercase - A commented, sample proxy intended as a guide to help developers write custom plugins. See Edge Microgateway sample plugin.
  • accumulate-request - 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 - 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 - Transforms request or response data. This plugin represents a best practice implementation of a transform plugin. The example plugin performs a trival 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. 

Where to find 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

This folder includes a set of default plugins, and examples to help you build your own plugins.

Adding and configuring a plugin

Follow this pattern to add and configure any Edge Microgatway plugin:

  1. Stop Edge Microgateway.
  2. To add a plugin, you need to edit the Edge Microgateway config file. You have these options:
    • Edit the ~/.edgemicro/config.yaml file. In this case, your change will take effect immediately when you restart Edge Microgateway.
    • Edit the <microgateway-root-dir>/config/default.yaml file, where <microgateway-root-dir> is the directory where Edge Microgateway was installed when you ran the npm install command. See Where is Edge Microgateway installed. In this case, your change will take effect only if you re-run the edgemicro configure command, choose to overwrite the ~/.edgemicro/<org>-<env>-config.yaml file, and restart Edge Microgateway.
  3. 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. The Analytics plugin is always added by default, and does not need to be included 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
  1. Configure the plugin. 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 to the config file:
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

You can also create a plugin-specific configuration file. See Plugin-specific configuration. For details on the spike arrest plugin, see Using the spike arrest plugin.

  1. ファイルを保存します。
  2. Restart Edge Microgateway.

Plugin-specific configuration

You can override the plugin parameters specified in the config file by creating a plugin-specific configuration in 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

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?.

Configuring spike arrest

  1. Stop Edge Microgateway.
  2. Open the Edge Microgateway config file in an editor. You have these options:
    • Edit the ~/.edgemicro/config.yaml file. In this case, your change will take effect immediately when you restart Edge Microgateway.
    • Edit the <microgateway-root-dir>/config/default.yaml file, where <microgateway-root-dir> is the directory where Edge Microgateway was installed when you ran the npm install command. See Where is Edge Microgateway installed. In this case, your change will take effect only if you re-run the edgemicro configure command, choose to overwrite the ~/.edgemicro/<org>-<env>-config.yaml file, and restart Edge Microgateway.
  3. Add the following top-level element. You can add it anywhere in the file.
spikearrest:
  timeUnit: second
  allow: 10
  bufferSize: 10
  1. Configure the spike arrest attributes, as explained below:
    • 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.
  1. Add the spikearrest plugin to the sequence element. For example:
plugins:    
    dir: ../plugins    
    sequence:       
        - oauth
        - spikearrest
  1. Save the config file.
  2. Restart Edge Microgateway.

When you call APIs on the Edge Microgateway instance, spike arrest is now active.

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

About quotas

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?.

 

Configuring a quota

To use quota, OAuth authentication must be enabled in the Edge Microgateway config file AND the quota plugin must be placed after the oauth plugin in the sequence list. Quotas are only enforced when client authentication is enabled. The Setting up and configuring Edge Microgateway covers all the steps required to make authenticated API calls.

You configure quotas in the Apigee Edge UI where API products are defined. You need to know which product contains the API you want to limit with a quota.

  1. Stop Edge Microgateway.
  2. Be sure that OAuth authentication is enabled. You have these options:
    • Edit the ~/.edgemicro/config.yaml file. In this case, your change will take effect immediately when you restart Edge Microgateway.
    • Edit the <microgateway-root-dir>/config/default.yaml file, where <microgateway-root-dir> is the directory where Edge Microgateway was installed when you ran the npm install command. In this case, your change will take effect only if you re-run the edgemicro configure command, choose to overwrite the ~/.edgemicro/<org>-<env>-config.yaml file, and restart Edge Microgateway.
  3. Make sure these properties are set to false. If necessary, follow the steps in the Setting up and configuring Edge Microgateway to learn how to configure and make authenticated API calls.
oauth:
      allowNoAuthorization: false
      allowInvalidAuthorization: false
  1. Add the quota plugin to the sequence element. The quota plugin must be placed after the oauth plugin, as shown below:
plugins:    
   dir: ../plugins     
sequence:
    - oauth      
    - quota
  1. Log in to your Apigee Edge organization account.
  2. In the Edge UI, open the product associated with the API proxy to which you want to apply the quota.
    1. In the UI, select Products from the Publish menu.
    2. Open the product containing the API to which you want to apply the quota.
    3. 「Edit」をクリックします。
    4. In the Quota field, specify the quota interval. For example, 100 requests every one minute. Or 50000 requests every 2 hours.

  1. 「Save」をクリックします。 
  2. Restart Edge Microgateway.

When you call APIs on the Edge Microgateway instance, quota is now active.

Testing the quota

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.

Help or comments?