Edge Microgateway release notes

Version 3.2.x

Bug fixes and enhancements v.3.2.x

3.2.0

On Thursday, January 21, 2021, we released the following fixes and enhancements to Edge Microgateway.

Component versions:

The following table lists the version numbers for the individual component projects associated with Edge Microgateway 3.2.0. Note that because each component is a separate project, release numbers may not match up with the main product version:

Bug fixes and enhancements:

Version 3.1.x

Bug fixes and enhancements v.3.1.x

3.1.8

On Monday, November 16, 2020, we released the following fixes and enhancements to Edge Microgateway.

Component versions:

The following table lists the version numbers for the individual component projects associated with Edge Microgateway 3.1.8. Note that because each component is a separate project, release numbers may not match up with the main product version:

Bug fixes and enhancements:

3.1.7

On Thursday, September 24, 2020, we released the following fixes and enhancements to Edge Microgateway.

Component versions:

The following table lists the version numbers for the individual component projects associated with Edge Microgateway 3.1.7. Note that because each component is a separate project, release numbers may not match up with the main product version:

Bug fixes and enhancements:

{"message":"write after end","code":"ERR_STREAM_WRITE_AFTER_END"}

3.1.6

On Thursday, August 20, 2020, we released the following fixes and enhancements to Edge Microgateway.

Component versions:

The following table lists the version numbers for the individual component projects associated with Edge Microgateway 3.1.6. Note that because each component is a separate project, release numbers may not match up with the main product version:

Bug fixes and enhancements:

3.1.5

On Friday, June 26, 2020, we released the following fixes and enhancements to Edge Microgateway.

Component versions:

The following table lists the version numbers for the individual component projects associated with Edge Microgateway 3.1.5. Note that because each component is a separate project, release numbers may not match up with the main product version:

Bug fixes and enhancements:

3.1.4

On Friday, April 23, 2020, we released the following fix to Edge Microgateway.

Bug fix:

A dependency issue in version 3.1.3 was fixed. Version 3.1.3 has been marked as deprecated in the npm repository. Otherwise, all of the bug fixes and enhancements described in the version 3.1.3 release note apply to this release.

3.1.3

On Wednesday, April 15, 2020, we released the following fixes and enhancements to Edge Microgateway.

Component versions:

The following table lists the version numbers for the individual component projects associated with Edge Microgateway 3.1.3. Note that because each component is a separate project, release numbers may not match up with the main product version:

Bug fixes and enhancements:

• 153509313 - An issue was fixed where the Node.js debug module results in memory leaks. The issue exists in version v3.1.0, v3.1.1, and 3.1.2.
• 153509313 - An issue was fixed where the same message ID for two different transactions was printed in the logging output.
• 151673570 - An issue was fixed where Edge Microgateway was not updated to use new Apigee KVM APIs. Edge Microgateway now uses the new commands for adding and updating the KVM values.
• 152822846 - In previous releases, Edge Microgateway was updated so that its processing of resource path mapping matches that of Apigee Edge. In this release, an issue was fixed where the pattern /literal_string/* was not handled correctly. For example, /*/2/*. See also Configuring the behavior of a resource path of '/', '/*', and '/**'.
• 152005003 - Changes were made to enable organization and environment scoped identifiers for quotas.
• 152005003 - Changes were made to enable organization and environment scoped identifiers for quotas. The combination of 'org + env + appName + productName' is used as the quota identifier.

3.1.2

On Monday, March 16, 2020, we released the following fixes and enhancements to Edge Microgateway.

Component versions:

The following table lists the version numbers for the individual component projects associated with Edge Microgateway 3.1.3. Note that because each component is a separate project, release numbers may not match up with the main product version:

Bug fixes and enhancements:

• 151285018 - A feature enhancement was made to add HTTP proxy support for traffic between Edge Microgateway and backend targets. In addition, issues were fixed for existing HTTP proxy support between Edge Microgateway and Apigee Edge. For details, see:
  • Use an HTTP proxy for communication with Apigee Edge
  • Use an HTTP proxy for target communication
• 149101890 - The log notification code for cases where the target server or load balancer closes its connection was changed from ERROR to INFO.
• 150746985 - An issue was fixed where the edgemicro verify command did not work properly if either redisBasedConfigCache: true or quotaUri: https://%s-%s.apigee.net/edgemicro-auth were present in the config file.
• 151284716 - An enhancement was made to close server connections faster when workers are restarted during a reload.
• 151588764 - Update Node.js version in the Docker image used to run Edge Microgateway in a Docker container to 12, because Node.js v8 is deprecated.
• 151306049 - A documentation update was made to list the Apigee Edge management APIs that are used by Edge Microgateway CLI commands. See What management APIs does Edge Microgateway use?.

3.1.1

On Thursday, February 20, we released the following fixes and enhancements to Edge Microgateway.

Component versions:

The following table lists the version numbers for the individual component projects associated with Edge Microgateway 3.1.1. Note that because each component is a separate project, release numbers may not match up with the main product version:

Bug fixes and enhancements:

• 146069701 - An issue was fixed where the microgateway-core module did not respect HTTP_PROXY and HTTPS_PROXY environment variables. With this change, proxy settings in the YAML configuration file, if specified, are now ignored; only the environment variables are used to specify the proxy.

  If you want to specify proxy configuration in the configuration file, you must also specify an HTTP_PROXY variable that mentions the same proxy URL as the one specified in the config file. For example, if you specify the following configuration:

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

  You must also specify this environment variable:

  HTTP_PROXY=http://10.128.0.20:3128

• 146320620 - A new configuration parameter, edgemicro.headers_timeout, was added. This attribute limits the amount of time (in milliseconds) the HTTP parser will wait to receive the complete HTTP headers. For example:

  edgemicro:
  keep_alive_timeout: 6000
  headers_timeout: 12000

  Internally, the parameter sets the Node.js Server.headersTimeout attribute on requests. (Default: 5 seconds more than the time set with edgemicro.keep_alive_timeout. This default setting prevents load balancers or proxies from erroneously dropping the connection.)

• 149278885 - A new feature was added that allows you to set the target API timeout at the API proxy level instead of using one global timeout setting.

  If you set the TargetEndpoint property io.timeout.millis in the API proxy, Edge Microgateway will be able to retrieve that property and apply target endpoint-specific timeouts. If this parameter is not applied, Edge Microgateway uses the global timeout specified with edgemicro.request_timeout.

3.1.0

On Tuesday, January 21, we released the following fixes and enhancements to Edge Microgateway.

Component versions:

The following table lists the version numbers for the individual component projects associated with Edge Microgateway 3.1.0. Note that because each component is a separate project, release numbers may not match up with the main product version:

Bug fixes and enhancements:

• 144187500 - A new WARN level event will be logged when the quotas.failOpen flag is triggered. This flag is triggered if a quota-processing error occurs or if the "quota apply" request to Edge fails to update remote quota counters. In this case, the quota will be processed based on local counts only until the next successful remote quota sync happens. Previously, this event was only logged when the log level was set to DEBUG.

  For example:

  2020-01-20T02:52:53.040Z [warn][localhost:8000][5][foo-eval][test][hello/][]
  [DbpGIq9jKfzPX8jvXEivhA0LPwE][f372cc30-3b2f-11ea-845f-a627f][quota][remote quota not
  available so processing locally, setting quota-failed-open for identifier: AppQuota60.Quota60]
  [GET][][][][]

• 145023519 - An issue was fixed where in-flight or new transactions were impacted whenever Edge Microgateway detected a change to an API proxy. Now, when a change is made to a proxy, Edge Microgateway refreshes the cache and worker nodes restart. With this change, in-flight transactions and new API calls being sent to the microgateway are not impacted.
• 146378327 - The log level of sourceRequest, targetRequest, and targetResponse have been changed to the INFO level.
• 146019878 - A discrepancy between the latency that was calculated for "API Proxy Performance" in Edge analytics and Edge Microgateway sourceResponse/targetResponse log events has been fixed. Now, the latency in Edge analytics and Microgateway log events is aligned.
• Pattern matching logic related changes:
  • 147027862 - The oauth plugin was updated to support the following resource path matching patterns as specified in API Products:
    • /{literal}**
    • /{literal}*
    • Any combination of above two patterns

    With this change, Edge Microgateway plugin now follows the same pattern matching as Apigee Edge, as explained in Configuring the behavior of a resource path of '/', '/*', and '/**'.

  • 145644205 - Update pattern matching logic of apiKeys plugin to match oauth plugin.
• 143488312 - A problem was fixed where leading or trailing spaces in the client ID parameter caused the creation of the JWT product list to be empty for OAuth token and API key requests.
• 145640807 and 147579179 - A new feature has been added that allows a special Edge Microgateway instance called "the synchronizer" to retrieve configuration data from Apigee Edge and write it to a local Redis database. Other microgateway instances can then be configured to read their configuration data from the database. This feature adds a level of resilience to Edge Microgateway. It allows microgateway instances to start up and function without needing to communicate with Apigee Edge. For details, see Using the synchronizer.

  The syncrhonizer feature is currently supported to work with Redis 5.0.x.

Version 3.0.x

Bug fixes and enhancements v.3.0.x

3.0.10

On Friday, November 8, we released the following fixes and enhancements to Edge Microgateway.

Component versions:

The following table lists the version numbers for the individual component projects associated with Edge Microgateway 3.0.10. Note that because each component is a separate project, release numbers may not match up with the main product version:

Bug fixes and enhancements:

• 142677575 - A feature update was made so that the pattern matching for resource paths used in API products for Edge Microgateway now aligns with the resource path pattern matching used by Apigee Edge, as described in Configuring the behavior of a resource path of '/', '/*', and '/**'.

  Note: If you use a compound resource pattern like /*/2/**, you must ensure that the edgemicro_auth proxy is added to a standalone API product. Then, you must include that product in the proxy's Developer App, as illustrated in the following screenshot:

  

  Note: The features.isSingleForwardSlashBlockingEnabled configuration property, as described in Configuring the behavior of a resource path of '/', '/*', and '/**', is not supported for Edge Microgateway.

• 143740696 - The quotas configuration structure has changed (see also the release notes for version 3.0.9). The quotas property is used to configure the quota plugin. The change in structure was made to improve the clarity of the configuration elements. To configure the quota plugin, use the following YAML configuration. Note that the configuration property is called quotas. For details about the individual quotas configuration properties, see Configuration options 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
  quotas:
    bufferSize:
      hour: 20000
      minute: 500
      default: 10000
    useDebugMpId: true
    failOpen: true
  ...

• 141750056 - A new feature was added that allows you to use Redis as the quota backing store. If useRedis is true then the volos-quota-redis module used. When true, the quota is restricted to only those Edge Microgateway instances that connect to Redis. If false, the volos-quota-apigee module is used as the backing store, and the quota counter is global. For details, see Configuration options for quota. For example:

  edgemicro:
  ...
  quotas:
    useRedis: true
    redisHost: localhost
    redisPort: 6379
    redisDb: 1

• 140574210 - The default expiration time for tokens generated by the edgemicro-auth proxy has been changed from 108000 milliseconds (1.8 minutes) to 1800 seconds (30 minutes).
• 143551282 - To support SAML enabled orgs, the edgemicro genkeys command has been updated to include a ‑‑token parameter. This parameter lets you use an OAuth token for authentication instead of username/password. For details, see Generating keys.

3.0.9

On Friday, October 11, we released the following fixes and enhancements to Edge Microgateway.

Component versions:

The following table lists the version numbers for the individual component projects associated with Edge Microgateway 3.0.9. Note that because each component is a separate project, release numbers may not match up with the main product version:

Bug fixes and enhancements:

• 141989374 - A new "fail open" feature was added for the quota plugin. When this feature is enabled, if a quota-processing error occurs or if the "quota apply" request to Edge fails to update remote quota counters, the quota will be processed based on local counts only until the next successful remote quota sync happens. In both of these cases, a quota-failed-open flag is set in the request object.

  To enable the quota "fail open" feature, set the following configuration:

  quotas :
   failOpen : true

  Note: In addition, the name of the OAuth plugin's fail-open request object flag has been changed to oauth-failed-open.

• 142093764 - A configuration change was made to the edgemicro-auth proxy to prevent quota overruns. The change is to set the quota type to calendar. To use this improvement, you must update your edgemicro-auth to version 3.0.7 or higher.
• 142520568 - A new feature has been added to enable the logging of the MP (message processor) ID in quota responses. To use this feature, you must update your edgemicro-auth proxy to version 3.0.7 or higher and set the following configuration:

  quotas:
    useDebugMpId: true

  When useDebugMpId is set, quota responses from Edge will contain the MP id and will be logged by Edge Microgateway. For example:

  {
      "allowed": 20,
      "used": 3,
      "exceeded": 0,
      "available": 17,
      "expiryTime": 1570748640000,
      "timestamp": 1570748580323,
      "debugMpId": "6a12dd72-5c8a-4d39-b51d-2c64f953de6a"
  }

3.0.8

On Thursday, September 26, we released the following fixes and enhancements to Edge Microgateway.

Component versions:

The following table lists the version numbers for the individual component projects associated with Edge Microgateway 3.0.8. Note that because each component is a separate project, release numbers may not match up with the main product version:

Bug fixes and enhancements:

• 140025210 - A new "fail open" feature was added. This feature allows API processing to continue if an expired JWT token cannot be refreshed due to a connection error that prevents a successful API key verification call to the edgemicro-auth proxy.

  The feature allows you to set a grace period where the old token remains in cache and is re-used until the grace period expires. The feature allows Edge Microgateway to continue processing requests in case of a temporary connection failure. When connectivity resumes, and a successful Verify API Key call goes through, a new JWT is fetched and replaces the old JWT in the cache.

  To configure the new "fail open" feature, do the following:

  1. Set the following properties in the oauth stanza in the Edge Microgateway configuration file:

     oauth:
       failOpen: true
       failopenGraceInterval: time_in_seconds
       cacheKey: true
       ...

     For example:

     oauth:
       failOpen: true
       failopenGraceInterval: 5
       cacheKey: true
       ...

     In this example, the old token will be used for 5 seconds if it cannot be refreshed due to a connectivity problem. After 5 seconds, an authentication error will be returned.

• 141168968 - An update was made to include the correlation_id in all plugin log output. In addition, the log levels for some logs were changed to error as required.
• 140193349 - A update was made to the edgemicro-auth proxy to require the Edge Microgateway key and secret to be verified on every Verify API Key request. Edge Microgateway has been updated to always send the key and secret on every Verify API Key request. This change prevents clients from obtaining a JWT with only an API key.
• 140090250 - An update was made to add diagnostic logging for quota processing. With this change, it is now possible to correlate quoto log output with the rest of Edge Microgateway logs.

3.0.7

On Thursday, September 12, we released the following fixes and enhancements to Edge Microgateway.

Component versions:

The following table lists the version numbers for the individual component projects associated with Edge Microgateway 3.0.7. Note that because each component is a separate project, release numbers may not match up with the main product version:

Bug fixes and enhancements:

• 140075602 - An update was made to the OAuth plugin to return a 5xx status code where appropriate. Previously, the plugin only returned 4xx status codes in all non-200 cases. Now, for any message response that is not a 200 status, the exact 4xx or 5xx code will be returned, depending on the error.

  This feature is disabled by default. To enable this feature, add the oauth.useUpstreamResponse: true property to your Edge Microgateway configuration. For example:

  oauth:
    allowNoAuthorization: false
    allowInvalidAuthorization: false
    gracePeriod: 10
    useUpstreamResponse: true

• 140090623 - In release 3.0.6, a new configuration property was added, quota.quotaUri. Set this config property if you want to manage quotas through the edgemicro-auth proxy that is deployed to your org. If this property is not set, the quota endpoint defaults to the internal Edge Microgateway endpoint. For example:

  edge_config:
    quotaUri: https://%s-%s.apigee.net/edgemicro-auth

  In release 3.0.7, the edgemicro-auth was updated to accept this new configuration. To use the quotaUri property, you must upgrade to the latest edgemicro-auth proxy. For details, see Upgrading the edgemicro-auth proxy.

• 140470888 - An Authorization header was added to quota calls to provide authentication. Also, the edgemicro-auth proxy was modified to remove "organization" from the quota identifier. Because the quota endpoint resides in the customer's organization, the quota identifier is no longer needed.
• 140823165 - The following property name:

  edgemicro:
      keepAliveTimeout

  was documented incorrectly in release 3.0.6. The correct property name is:

  edgemicro:
      keep_alive_timeout

• 139526406 - A bug was fixed where an incorrect quota count occurred if a developer app had multiple products. Quota is now correctly enforced for each product in an app that has multiple products. The combination of 'appName + productName' is used as the quota identifier.

3.0.6

On Thursday, August 29, we released the following fixes and enhancements to Edge Microgateway.

• 138633700 - Added a new configuration property, keepAliveTimeout. This property enables you to set the Edge Microgateway timeout (in milliseconds). (Default: 5000 milliseconds)

  For example:

  edgemicro:
    keep_alive_timeout: 600

• 140090623 - Added a new configuration property, quotaUri. Set this config property if you want to manage quotas through the edgemicro-auth proxy that is deployed to your org. If this property is not set, the quota endpoint defaults to the internal Edge Microgateway endpoint. For example:

  edge_config:
    quotaUri: https://your_org-your_env.apigee.net/edgemicro-auth
  

  To use this feature, you must first deploy the latest version of the edgemicro-auth proxy to your org. For details, see Upgrading the edgemicro-auth proxy.

• 138722809 - Added a new configuration property, stack_trace. This property lets you to control whether or not stack traces appear in log files. For example:

  stack_trace: false

  If stack_trace is set to true, the stack trace will be printed in logs. If it is set to false, the stack trace will not be printed in logs.

3.0.5

On Thursday, August 15, we released the following fixes and enhancements to Edge Microgateway.

• 139005279 - An issue was fixed where the edgemicro status command did not return the right number of worker processes.
• 138437710 - An issue was fixed in the ExitCounter class that prevented the proper log from being written.

• 139064652 - Added the capability to add trace and debug logging levels for event and system logs. For now, only the capability to add these log levels was added. Currently, available log levels are info, warn, and error.
• 139064616 - Log output has been standardized for all console log statements. Console logging statements now includes these attributes:
• Timestamp
• Component name
• Process ID
• Console log message

• 138413755 - Improve JWT key and secret-related log messages for these CLI commands: cert, verify, upgradekvm, token, genkeys, revokekeys, rotatekey, and configure.

• 138413577 - Add and improve error handling for backend service timeouts.
• 138413303 - Add and improve error handling for response and socket timeouts.
• 138414116 - Add and improve error handling for "connection refused" errors.

3.0.4

On Thursday, August 1, we released the following fixes and enhancements to Edge Microgateway.

• 134445926 - Improvements to internal Edge Microgateway authentication.
• 137582169 - Addressed an issue where unwanted processes started up. The extra processes caused plugins to reload and used excessive memory. Edge Microgateway now keeps the number of processes within the expected limit.
• 137768774 - Log message improvements:
  • Cleaned up transaction (request) logs.
  • Added more log messages where needed.
  • Moved transaction (request) log messages from console output to relevant log file.
  • Updated console logs to use a centralized logging function.
• 138321133, 138320563 - Foundational internal change to quota buffer to enable future quota enhancements.

3.0.3

On Tuesday, July 23, we released the following fixes and enhancements to Edge Microgateway.

• Logging enhancements: Existing runtime logs use a new eventLog() function that captures and logs runtime data in a consistent format. Log info includes:
  • Timestamp (ISO 8601: YYYY-MM-DDTHH:mm:ss.sssZ).
  • Log level (error, warn, or info).
  • Hostname - The requesting hostname from the request header.
  • Process ID - If you're running a cluster of Node.js processes, this is the ID of the process where the logging occurred.
  • Apigee organization name.
  • Environment name in the organization.
  • API proxy name.
  • Client IP address.
  • ClientId.
  • Correlation ID (not currently set).
  • Edge Microgateway component name.
  • Custom message - Some objects may print additional information that is passed to this error property.
  • Request method (if HTTP request).
  • Response status code (if HTTP request).
  • Error message.
  • Error code - If an object includes an error code, it is printed in this property.
  • Time taken.
  • Operating system end of line marker.

  Null property values result in empty brackets, [].

  The following example shows the log format:

  Timestamp [level][hostname][ProcessId][Org][Environment][APIProxy][ClientIp][ClientId][][component][customMessage][reqMethod][respStatusCode][errMessage][errCode][timeTaken]

  (137770055)

• Performance: API products were not being filtered based on environment. This issue has been fixed. (135038879)
• Miscellaneous functional test integrations and code quality improvements.

3.0.2

On Wednesday, July 3, 2019, we released the following fixes and enhancements to Edge Microgateway.

Code quality - Code has been reviewed for quality and code changes have been made to meet quality standards requested by users. We addressed code quality errors and warnings derived from JSHint. Some actual code errors were identified and repaired as a result. All Apigee Edge Microgateway modules were put through this process. See the June 28 and July 2 commits for microgateway-config, microgateway-core, microgateway-plugins,and microgateway. All modules with code quality changes have been tested with internal tools that verify the execution of Edge Microgateway for customer use cases.

3.0.1

On Friday, June 21, 2019, we released the following fixes and enhancements to Edge Microgateway.

• 134834551 - Change the supported Node.js versions for Edge Microgateway
  (Node.js supported versions: 8 and 12; versions 7, 9, and 11 are experimental)
• 134751883 - Edge Microgateway crashes when reloading under load
• 134518428 - Products endpoint for Edge Microgateway returns 5XX if filter pattern is incorrect
• 135113408 - Workers should restart if they terminate unexpectedly
• 134945852 - tokenCacheSize is not used in oauth plug-in
• 134947757 - set cacheTTL in oauth plug-in
• 135445171 - gracePeriod calculation in OAuth is not correct
• Use memored module provided with the Edge Microgateway installation
• 135367906 - Security audit

Version 2.5.x

New features and enhancements v.2.5.x

(Fixed 2.5.38, 06/07/2019)

Improperly formatted JWTs can cause workers to crash when using token cache. Fixed in the Edge microgateway-plugins module. (b/134672029)

(Added 2.5.37) Add the CLI option edgemicro-cert -t.

The edgemicro cert -t option lets you specify an OAuth token to authenticate management APIs. See also Managing certificates.

(Added 2.5.35) Add support to debug Edge Microgateway using edgemicroctl.

You can use the mgdebug flag with edgemicroctl. See also Kubernetes integration tasks.

(Added 2.5.35) Enable a Windows build for edgemicroctl.

(Added 2.5.31) New edgemicro-auth/token API

A new edgemicro-auth/token API was added that allows you to pass the client/secret as a Base64 Encoded Basic Authorization header and the grant_type as a form parameter. See Obtaining bearer tokens directly.

(Fixed 2.5.31) Private configure does not respect token flag

An issue was fixed where configuring Edge Microgateway to use an OAuth2 access token on Edge for Private Cloud did not work properly (the token was not respected).

Docker: Support for using self-signed certificates

(Added 2.5.29) If you are using a Certificate Authority (CA) that's not trusted by default by Node.js, you can use the parameter NODE_EXTRA_CA_CERTS when you run a Docker container with Edge Microgateway. For details, see Using a CA that is not trusted by Node.js.

Docker: Support for TLS

(Added 2.5.29) Edge Microgateway running in a Docker container now supports TLS for incoming requests to the Edge Microgateway server (northbound requests) and for outgoing requests from Edge Microgateway to a target application (southbound requests).

The following examples explain in detail how to set up these TLS configurations:

• Example northbound TLS configuration
• Example southbound TLS configuration

In these examples, you will see how to use the container mount point /opt/apigee/.edgemicro to load the certificates, which are then referred to in the Edge Microgateway configuration file.

Docker: Support for request proxying

(Added 2.5.27) If you run Edge Microgateway in a Docker container, you can use these options to control proxy behavior when the microgateway is running behind a firewall:

• HTTP_PROXY
• HTTPS_PROXY
• NO_PROXY

For details, see Run Edge Micro as a Docker container.

Docker: Updated plugin instructions

(Added 2.5.27) If you run Edge Microgateway in a Docker container, you now have two options for deploying plugins. One option, using a Docker mount point, is new. The other option existed previously, is basically unchanged; however, the Dockerfile has been updated. For details, refer to the following links:

• Option A: Mount the plugins directory on a volume (New)
• Option B: Build the plugins into the container (Updated)

New OAuth token support for KVM upgrade command

(Added 2.5.27) You can use an OAuth token with the upgradekvm command. For details, see Upgrading the KVM.

Segregating APIs in Edge Analytics

(Added 2.5.26) New analytics plugin flags allow you to segregate a specific API path so that it appears as a separate proxy in the Edge Analytics dashboards. For example, you can segregate health check APIs to avoid confusing them with actual API calls. For more information, see Excluding paths from analytics.

Configuring a local proxy

(Added 2.5.25) With a local proxy, you do not need to manually create a microgateway-aware proxy on Apigee Edge. Instead, the microgateway will use the local proxy's base path. For more information, see Using local proxy mode.

Using standalone mode

(Added 2.5.25) You can run Edge Microgateway disconnected completely from any Apigee Edge dependency. This scenario, called standalone mode, lets you run and test Edge Microgateway without an Internet connection., see Running Edge Microgateway in standalone mode.

Revoking keys

(Added 2.5.19) A new CLI command has been added that revokes the key and secret credentials for an Edge Microgateway configuration.

edgemicro revokekeys -o [organization] -e [environment] -u [username] -k [key] -s [secret]

Docker support

(Added 2.5.19) You can now download the latest Edge Microgateway release as a Docker image:

docker pull gcr.io/apigee-microgateway/edgemicro:latest

Kubernetes support

(Added 2.5.19) You can deploy Edge Microgateway as a service or as a sidecar gateway in front of services deployed in a Kubernetes cluster. See: Integrate Edge Microgateway with Kubernetes overview.

Support for TCP nodelay option

(Added 2.5.16) A new configuration setting, nodelay, has been added to the Edge Micro configuration.

By default TCP connections use the Nagle algorithm to buffer data before sending it off. Setting nodelay to true, disables this behavior (data will immediately fire off data each time socket.write() is called). See also the Node.js documentation for more details.

To enable nodelay, edit the Edge Micro config file as follows:

edgemicro:
  nodelay: true
  port: 8000
  max_connections: 1000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

New CLI options for Forever monitoring

(Added 2.5.12) New parameters have been added to the edgemicro forever command. These parameters let you specify the location of the forever.json file, and let you either start or stop the Forever background process. See also Forever monitoring

Examples:

To start Forever:

edgemicro forever -f ~/mydir/forever.json -a start

To stop Forever:

edgemicro forever -a stop

JWT key rotation

A new feature was added that lets you rotate the public/private key pairs used to generate the JWT tokens used for OAuth security on Edge Microgateway. See Rotating JWT keys.

Filtering downloaded API proxies

By default, Edge Microgateway downloads all of the proxies in your Edge organization that start with the naming prefix "edgemicro_". You can change this default to download proxies whose names match a pattern. See Filtering downloaded proxies.

Specifying products without API proxies

In Apigee Edge, you can create an API product that does not contain any API proxies. This product configuration allows an API key associated with that product to work for with any proxy deployed in your organization. As of version 2.5.4, Edge Microgateway supports this product configuration.

Support for forever monitoring

Edge Microgateway has a forever.json file that you can configure to control how many times and with what intervals Edge Microgateway should be restarted. This file configures a service called forever-monitor, which manages Forever programmatically. See Forever monitoring.

Central management of the Edge Micro configuration file

If you run multiple Edge Microgateway instances, you may wish to manage their configurations from a single location. You can do this by specifying an HTTP endpoint where Edge Micro can download its configuration file. See Specifying a config file endpoint.

Support for forever CLI option

(Added 2.5.8) Use the edgemicro forever [package.json] command to specify the location of the forever.json file. Before the addition of this command, the config file had to be in the Edge Microgateway root directory.

For example:

edgemicro forever ~/mydir/forever.json

Addition of configUrl option to reload command

(Added 2.5.8) You can now use the --configUrl or -u option with the edgemicro reload command.

Grace period for JWT time discepancies

(Added 2.5.7) A gracePeriod attribute in OAuth configuration helps prevent errors caused by slight discrepancies between your system clock and the Not Before (nbf) or Issued At (iat) times specified in the JWT authorization token. Set this attribute to the number of seconds to allow for such discrepancies. See OAuth attributes.

(Added 2.5.7) A gracePeriod attribute in OAuth configuration helps prevent errors caused by slight discrepancies between your system clock and the Not Before (nbf) or Issued At (iat) times specified in the JWT authorization token. Set this attribute to the number of seconds to allow for such discrepancies. See OAuth attributes.

Bugs fixed v2.5.x

• (Issue #236) Fix typo in clearing the cache.
• (Issue #234) Reload crashes for Edge Microgateway 2.5.35.
• (Issue #135) Invalid virtual host reference "secure" error when using the -v option. This fix modifies the edgemicro-auth proxy before deployment to ensure the virtual hosts match exactly what is specified in the "-v" flag. In addition, you can specify any number of and any name for the virtual host (no longer restricted to default and secure).
• (Issue #141) The edgemicro reload command does not support the configuration file option -c. This issue has been fixed.
• (Issue #142) Edge Microgateway complains about deprecated crypto at install time. This issue has been fixed.
• (Issue #145) Quota not working with Edge Microgateway. This issue has been fixed.
• (Apigee Community issue: https://community.apigee.com/questions/33149/emg-jwt-token-validated-against-both-api-proxies-a.html#answer-33336) JWT token validated against both API Proxies and Resource URI in OAUTH. This issue has been fixed.
• (Apigee Community issue: https://community.apigee.com/questions/47846/microgateway-not-working-with-oauth.html) Microgateway not working with OAuth. This issue has been fixed.
• Fix pidPath on Windows.
• (Issue #157) Problem that caused the following error message has been fixed: ReferenceError: deployProxyWithPassword is not defined.
• (Issue #169) Update Node.js dependencies (npm audit)
• The edgemicro-auth proxy now uses the Edge JWT policies. The proxy no longer depends on Node.js to provide JWT support.

Version 2.4.x

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.

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

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

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.

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

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:

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 Create API products.

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 of multi-core systems. 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.

New config file location

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

Log file rotation

A new config attribute lets you specify a rotation interval for Edge Microgateway logs.

Bugs fixed v1.1.2

The following bugs are fixed in v. 1.1.2.