Send Docs Feedback
Nonexistent node nid: 9.

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.

Edge Microgateway release notes

Questions or issues? Get help here.

Release notifications: Go to http://status.apigee.com and click Subscribe to Updates.

Download and install: Go to Install Edge Microgateway

Release notes home page

Version 2.4.x

This version of Edge Microgateway works on Apigee Edge Private Cloud version 4.16.01 and later versions. Also, you can use this version of Microgateway with Apigee Edge trial organizations.

New features and enhancements v.2.4.x

 

1. Set a custom alias for the edgemicro-auth proxy (PR 116)

You can change the default basepath for the edgemicro-auth proxy. By default, the basepath is /edgemicro-auth. To change it, use the -x flag on the edgemicro configure command.

Example:

edgemicro configure -x /mypath …


2. Wildcard support for base paths (PR 77)

You can use one or more "*" wildcards in the base path of an edgemicro_* proxy. For example, a base path of /team/*/members allows clients to call https://[host]/team/blue/members and https://[host]/team/green/members without you needing to create new API proxies to support new teams. Note that /**/ is not supported.

Important: Apigee does NOT support using a wildcard "*" as the first element of a base path. For example, this is NOT supported: /*/search.

 

3. Custom config path added to CLI for Private Cloud configuration (PR 99)

By default, the microgateway configuration file is in ./config/config.yaml. On the init, configure, and start commands, you can now specify a custom config path on the command line using the -c or --configDir flags. Fixed an issue where a custom config directory for Private Cloud installations was not recognized.

Example:

edgemicro start -o docs -e test -k abc123 -s xyz456 -c /home/microgateway/config

 

4. Respect *_PROXY variables (PR 61)

If Edge Microgateway is installed behind a firewall and is not able to communicate with Apigee Edge in the public cloud, there are two options to consider:

Option 1:

The first option is to set the edgemicro: proxy_tunnel option to true in the microgateway config file:

edge_config:
   proxy: http://10.224.16.85:3128
   proxy_tunnel: true

When proxy_tunnel is true, Edge Microgateway uses the HTTP CONNECT method to tunnel HTTP requests over a single TCP connection. (The same is true if the environment variables for configuring the proxy are TLS enabled).

Option 2:

The second option is to specify a proxy and set proxy_tunnel to false in the microgateway config file. For example:

edge_config:
   proxy: http://10.224.16.85:3128
   proxy_tunnel: false

In this case, you can set the following variables to control the hosts for each HTTP proxy that you wish to use, or which hosts should not handle Edge Microgateway proxies: HTTP_PROXY, HTTPS_PROXY, and NO_PROXY. You can set NO_PROXY as a comma delimited list of domains that Edge Microgateway should not proxy to. For example:

export HTTP_PROXY='http://localhost:3786'
export HTTPS_PROXY='https://localhost:3786'

For more information on these variables, see:

https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables


5. Set a custom timeout for target requests (PR 57)

You can set a custom timeout for target requests with this configuration:

edgemicro:
    request_timeout: 10

The timeout is set in seconds. If a timeout occurs, Edge Microgateway responds with a 504 status code.

6. Respect custom HTTP status messages on the target response (PR 53)

Edge Microgateway respects custom HTTP status messages set on the target response. In previous releases, status messages sent from the target were overridden with Node.js defaults.

 

7. The X-Forwarded-For header can set the client_ip for analytics

If present, the X-Forwarded-For header will set the client_ip variable that is reported in Edge Analytics. This feature lets you know the IP of the client that sent a request to Edge Microgateway.

 

8. OAuth plugin changes

The OAuth plugin supports API Key verification and OAuth access token verification. Before this change, the plugin accepted either form of security. With this change, you can allow only one of those security models (while maintaining backward compatibility).

The OAuth plugins adds two new flags:

  • allowOAuthOnly -- If set to true, every API must carry an Authorization header with a Bearer Access Token.

  • allowAPIKeyOnly -- If set to true, every API must carry an x-api-key header (or a custom location) with an API Key.

You set these flags in the Edge Microgateway configuration file like this:

oauth:
    allowNoAuthorization: false
    allowInvalidAuthorization: false
    keep-authorization-header: false
    allowOAuthOnly: false
    allowAPIKeyOnly: false

Do not set both flags to true. The default setting is both flags are set to false (for backward compatibility).

 

9. Improved the edgemicro-auth proxy (PR 40)

Improvements have been made to the edgemicro-auth proxy. Before these changes, the proxy stored keys in the Edge Secure Store, an encrypted vault. Now, the proxy stores keys in Edge's encrypted key-value map (KVM).

If you want to continue using your currently deployed edgemicro-auth proxy, you can continue doing so. However, if you want to switch to the new proxy, you need to re-run the edgemicro configure command. This command deploys the new edgemicro-auth proxy for you. The improved proxy allows custom claims to be made to a JSON Web Token (JWT), allows expiry configuration and supports refresh tokens. For details, see the edgemicro-auth page in GitHub. 

 

10. Rewriting default target URL in a plugin (PR 74)

You can also override the target endpoint port and choose between HTTP and HTTPS. Modify these variables in your plugin code: req.targetPort and req.targetSecure. To choose HTTPS, set req.targetSecure to true; for HTTP, set it to false. If you set req.targetSecure to true, see this discussion thread for more information. 

A sample plugin called eurekaclient has been added to Edge Microgateway. This plugin demonstrates how to use the req.targetPort and req.targetSecure variables and illustrates how Edge Microgateway can perform dynamic endpoint lookup using Eureka as a service endpoint catalog.

 

11. Initial support for OAuth token authentication (PR 125)

You can configure Edge Microgateway to use an OAuth token for authentication instead of username/password. To use an OAuth token, use the following parameter on the edgemicro configure command:

-t, --token <token>

For example:

edgemicro configure -o docs -e test -t <your token>

Bugs fixed v2.4.3

  • Fixed an issue where a paid org was required to properly run the edgemicro-auth proxy. Now, you can use Edge Microgateway with trial orgs as well. (PR 5)
  • Fixed an issue where the stream was not finished processing data, but end handlers were executing anyway. This caused a partial response to be sent. (PR 71)
  • Fixed an issue where a custom config directory for Private Cloud installations was not recognized. (PR 110)
  • Fixed an issue with bi-directional SSL between the client and Edge Microgateway. (PR 70)
  • Fixed an issue where a trailing slash was required on the proxy basepath for API key verification to workk properly. Now, a trailing slash is not needed at the end of the basepath. (PR 48)

 

Version 2.3.5

New features and enhancements v.2.3.5

Proxy filtering

You can filter which microgateway-aware proxies an Edge Microgateway instance will process. When Edge Microgateway starts, it downloads all of the microgateway-aware proxies in the organization it's associated with. Use the following configuration to limit which proxies the microgateway will process. For example, this configuration limits the proxies the microgateway will process to three: edgemicro_proxy-1, edgemicro_proxy-2, and edgemicro_proxy-3:

proxies:
  - edgemicro_proxy-1
  - edgemicro_proxy-2
  - edgemicro_proxy-3

Analytics data masking

A new configuration lets you prevent request path information from showing up in Edge analytics. Add the following to the microgateway configuration to mask the request URI and/or request path. Note that the URI consists of the hostname and path parts of the request.

analytics:
  mask_request_uri: 'string_to_mask'
  mask_request_path: 'string_to_mask'

Version 2.3.3

If you are considering upgrading to v.2.3.3: If you have configured an HTTP proxy server for your Edge Microgateway setup, we recommend that you do not upgrade to version 2.3.3. The HTTP_PROXY variable and the edge_config:proxy and edge_config:proxy_tunnel config settings do not work in v. 2.3.3.

New features and enhancements v.2.3.3

Following are the new features and enhancements for this release.

Disable automatic change polling

You can turn off automatic change polling by setting this attribute in the microgateway config:

disabled_config_poll_interval: true

By default, periodic polling picks up any changes made on Edge (changes to products, microgateway-aware proxies, etc) as well as changes made to the local config file. The default polling interval is 600 seconds (five minutes). 

Rewriting target URLs in plugins

You can override the default target URL dynamically in a plugin by modifying these variables in your plugin code: req.targetHostname and req.targetPath

New plugin function signature

A new plugin function signature has been added that provides the target response as an argument. This addition makes it easier for plugins to access the target response.

function(sourceRequest, sourceResponse, targetResponse, data, cb)

Simplified default logging output

By default, the logging service now omits the JSON of downloaded proxies, products, and JWT. You can change to default to output these objects by setting DEBUG=* when you start Edge Microgateway. For example:

DEBUG=* edgemicro start -o docs -e test -k abc123 -s xyz456

Custom config path added to CLI

By default, the microgateway configuration file is in ./config/config.yaml. On the init, configure, and start commands, you can now specify a custom config path on the command line. For example:

edgemicro start -o docs -e test -k abc123 -s xyz456 -c /home/microgateway/config

Bugs fixed v2.3.3

  • A memory leak was fixed that occurred during large request/responses.
  • Plugin execution order was fixed. It now behaves the way it is explained in the documentation.
  • The plugin accumulate-request plugin no longer hangs for GET requests.
  • An issue was fixed in the accumulate-response plugin where a lack of response body caused errors.

Release 2.3.1

Installation note

Some previous versions of Edge Microgateway let you install the software by downloading a ZIP file. These ZIP files are no longer supported. To install Edge Microgateway, you must use:

npm install -g edgemicro

Refer to the installation topic for more details.

New features and enhancements v.2.3.1

Following are the new features and enhancements for this release.

Filter proxies

A new configuration lets you filter which proxies that Edge Microgateway will load upon startup. Previously, the microgateway loaded all microgateway-aware proxies (proxies named edgemicro_*) pulled from the Edge organization/environment that you specified in the edgemicro configure command. This new feature lets you filter this list of proxies so that Edge Microgateway only loads the ones you specify. Simply add the proxies element to the microgateway config file like this:

edge micro:
proxies:
    - edgemicro_[name]
    - edgemicro_[name]
    ...

For example, let’s say you have 50 edgemicro_* proxies in your Edge org/env, including ones named edgemicro_foo and edgemicro_bar. You can tell the microgateway to use only these two proxies like this:

edge micro:
proxies:
    - edgemicro_foo
    - edgemicro_bar

Upon startup, the microgateway will only be able to call the specified proxies. Any attempts to call other microgateway-aware proxies downloaded from the Edge organization/environment will result in an error.

Set target request headers in plugins

There are two basic patterns to consider if you want to add or modify target request headers: one where the incoming request contains data (as in a POST request) and one where it does not (as in a simple GET request).

Let's consider a case where the incoming request contains data, and you want to set request headers on the target request. In previous versions of Edge Microgateway, it was not possible to set target headers reliably in this case.

The key to this pattern is to first accumulate all incoming data from the client. Then, in the onend_request() function, use the new function request.setOverrideHeader(name, value) to customize the headers.

Here is sample plugin code showing how to do this. The headers set in onend_request are sent to the target:

module.exports.init = function(config, logger, stats) {


  function accumulate(req, data) {
    if (!req._chunks) req._chunks = [];
    req._chunks.push(data);
  }

  return {

    ondata_request: function(req, res, data, next) {
      if (data && data.length > 0) accumulate(req, data);
      next(null, null);
    },

    onend_request: function(req, res, data, next) {
      if (data && data.length > 0) accumulate(req, data);
      var content = Buffer.concat(req._chunks);
      delete req._chunks;
      req.setOverrideHeader('foo', 'bar');
      req.setOverrideHeader('content-length', content.length);
      next(null, content);
    },


    onerror_request: function(req, res, data, next) {
      next(null, null);
    }

  };

}

If the request does not include data, then you can set target headers in the onrequest() handler. This pattern is not new -- it has been documented previously and has been used in the sample plugins provided with Edge Microgateway.

onrequest: function(req, res, next) {
      debug('plugin onrequest');
      req.headers['x-foo-request-id'] = "bar";
      req.headers['x-foo-request-start'] = Date.now();
      next();
    }

 

Zero-downtime reload feature

After making a configuration change to Edge Microgateway, you can load the configuration without dropping any messages. With this change, Edge Microgateway always starts in cluster mode, and he --cluster option has been removed from the edgemicro start command.

In addition, three new CLI commands have been added. You must run these commands from the same directory where the edgemicro start command was executed:

  • edgemicro status - Checks to see if the Edge Microgateway is running or not.
  • edgemicro stop - Stops the Edge Microgateway cluster.
  • edgemicro reload - Reloads the Edge Microgateway configuration with no downtime.

 

Automatic config reload with zero downtime

Edge Microgateway loads a new configuration periodically and executes a reload if anything changed. The polling picks up any changes made on Edge (changes to products, microgateway-aware proxies, etc) as well as changes made to the local config file. The default polling interval is 600 seconds (five minutes). You can change the default in the microgateway config file as follows:

edgemicro:
    config_change_poll_interval: [seconds]

 

Added version information to CLI

A --version flag was added to the CLI. To get the current version of Edge Microgateway, use:

edgemicro --version

 

New Edge Microgateway server SSL options

Edge Microgateway now supports the following server SSL options in addition to key and cert:

Option Description
pfx Path to a pfx file containing the private key, certificate, and CA certs of the client in PFX format.
passphrase A string containing the passphrase for the private key or PFX.
ca Path to a file containing a list of trusted certificates in PEM format.
ciphers A string describing the ciphers to use separated by a ":".
rejectUnauthorized If true, the server certificate is verified against the list of supplied CAs. If verification fails, an error is returned.
secureProtocol The SSL method to use. For example, SSLv3_method to force SSL to version 3.
servername The server name for the SNI (Server Name Indication) TLS extension.

 

Send log files to stdout

You can send log data to standard output with a new configuration setting:

edgemicro:
  logging:
    to_console: true  

See Managing log files

Version 2.1.2

Following are the new features and enhancements for this release.

Allow custom API endpoint for configuration

There are new configurable endpoints for the authorization proxy that support the use of a custom auth service. These endpoints are:

  • edgeconfig:verify_api_key_url
  • edgeconfig:products

For details, see Using a custom auth service

Version 2.1.1

Following are the new features and enhancements for this release.

Deploy auth proxy cross-platform compatible

An enhancement was made so that the command used to deploy the Edge Microgateway authorization proxy to Edge is compatible on Windows systems.

Version 2.1.0

New features and enhancements v.21.0

Following are the new features and enhancements:

Specify client SSL/TLS options

You can specify client options for SSL/TSL connections to targets using a new set of config options. See Using client SSL/TSL options.

Version 2.0.11

Installation note v2.0.11

Some previous versions of Edge Microgateway let you install the software by downloading a ZIP file. These ZIP files are no longer supported. To install Edge Microgateway, you must use:

npm install -g edgemicro

Refer to the installation topic for more details.

New features and enhancements v.2.0.11

Following are the new features and enhancements:

Specify a port on startup

The start command lets you specify a port number to override the port specified in the configuration file. You can also specify a port number using the PORT environment variable. See start command for details.

Optionally preserve auth headers

A new configuration setting, keepAuthHeader, lets you preserve the Authorization header sent in the request. If set to true, the Auth header is passed on to the target. See oauth attributes.

Ability to use a custom authorization service

If you want to use your own custom service to handle authentication, change the authUri value in the Edge Microgateway config file to point to your service. For details, see Using a custom auth service.

 

Version 2.0.4

Edge Microgateway v.2.0.4 was released on May 25, 2016.

New features and enhancements v2.0.4

Following are the new features and enhancements in this release.

Support for resource paths in products

Edge Microgateway now supports resource paths in products. Resource paths let you restrict access to APIs based on the proxy path suffix. For details on creating products and configuring resource paths, see

Nonexistent node nid: 9.

Support for npm global install

You can now install Edge Microgateway using the npm -g (global) option. For details on this option refer to the npm documentation

Version 2.0.0

Edge Microgateway v2.0.0 was released on April 18, 2016.

New features and enhancements v.2.0.0

Following are the new features and enhancements in this release.

Single process server

Edge Microgateway is now a single process server. It no longer uses a two process model where one process (previously known as the "agent") launches Edge Microgateway, the second process. The new architecture makes automation and containerization easier.

Namespaced configuration files

Configuration files now are namespaced using organization and environment so that multiple Microgateway instances can run on the same host. You can find the config files in ~/.edgemicro after you run the Edge Microgateway config command. 

New environment variables

There are now 4 environment variables: EDGEMICRO_ORG, EDGEMICRO_ENV, EDGEMICRO_KEY, EDGEMICRO_SECRET. If you set these variables on your system, you do not have to specify their values when you use the Command-Line Interface (CLI) to configure and start Edge Microgateway.

Cached configuration

Edge Microgateway uses a cached configuration file if it restarts with no connection to Apigee Edge. 

Cluster mode

There are now options to start Edge Microgateway in cluster mode. Cluster mode allows you to take advantage The microgateway employs the Node.js cluster module for this feature. For details, see the Node.js documentation. 

Bugs fixed v2.0.0

Plugin event lifecycle now properly handles async code that contains code with a new callback.

Version 1.1.2

Edge Microgateway v. 1.1.2 was released on March 14, 2016.

New features and enhancements v.1.1.2

Following are the new features and enhancements in this release.

Performance Improvement

Edge Microgateway now uses the Node.js HTTP agent properly for better connection pooling. This enhancement improves performance and overall stability under high load.

Remote debugger support

You can configure Edge Microgateway to run with a remote debugger, like node-inspector. See Debugging and troubleshooting.

New config file location

When you configure Edge Microgateway, the agent/config/default.yaml file is now copied to ~./edgemicro/config.yaml. See Location of the agent config file.

Log file rotation

A new config attribute lets you specify a rotation interval for Edge Microgateway logs. See Managing log files

Bugs fixed v1.1.2

The following bugs are fixed in v. 1.1.2.

Description
Java callout for edgemicro-internal proxy used with on-prem Edge now uses right MGMT server.
Remove typescript depenencies from the agent.
Fix CLI bug when using lean deployment option.
Fix cert logic dependency reference.

 

Help or comments?