Edge Microgateway FAQ

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation.
info

Getting started

How do I install Edge Microgateway?
See Installing Edge Microgateway.
How do I run Edge Microgateway?
See Setting up and configuring Edge Microgateway.
Do I need a database to run Microgateway?
APIs proxied through Edge Microgateway may interact with a database running as part of a target service. However, Edge Microgateway operates independently of any database or backend data store.

Operation

What changes on Edge require a restart of Edge Microgateway?
Edge Microgateway automatically polls for changes made on Apigee Edge, such as changes to microgateway-aware proxies, products, or developer apps. The default polling interval is 600 seconds; however, you can change the interval with the config_change_poll_interval configuration setting. See edgemicro attributes.
If you do not want to wait for the polling interval, use the edgemicro reload command to pick up the latest changes. See Reloading the microgateway cluster.
How do I differentiate between a proxy deployed on Edge vs. a proxy on Edge Microgateway?
When you configure Edge Microgateway, a list of microgateway-aware proxies deployed on Apigee Edge is downloaded to the local configuration of Edge Microgateway. Microgateway-aware proxies are ones named with the prefix edgemicro_.
What are my options for logging with Edge Microgateway?
Edge Microgateway has a built-in logging feature. For details, see Managing log files.
You can also write a custom plugin to use a third-party logging service with Edge Microgateway. Because of the way Edge Microgateway works, you cannot use the Apigee Edge Message Logging policy to log messages for Edge Microgateway. See also the Logging Plugin for Microgateway community article.
Can I reuse key/secret combinations between instances of Edge Microgateway?
As long as the organization and environment are the same for the Microgateway instances, you can reuse the key/secret pair that get generated during configuration.
How do I configure Edge Microgateway to start up in a production environment?
You can set the environment variables for startup command parameters, such as EDGEMICRO_KEY, EDGEMICRO_SECRET, EDGEMICRO_ORG, and EDGEMICRO_ENV. With these (and other) variables you can start Edge Microgateway with the single command edgemicro start. See also Setting environment variables.
Can I use custom product or developer app attributes with Edge Microgateway?
No. By default, Edge Microgateway only acts on attributes related to basic routing and security. However, as workarounds, you have the following possible option:
  1. Add custom attributes to the edgemicro-auth proxy that Edge Microgateway deploys to Apigee Edge. These attributes will be available when using API Key or OAuth token security.
  2. Modify the OAuth plugin to act on those attributes.
Is there a limit on request header size?
If you upgrade Node.js to v8.14.0 or a later version, be aware that the maximum header size allowed on requests was reduced from 80KB to 8KB. Headers that exceed 8KB result in an HTTP 431 error.
A Node.js configuration option added in Node.js v11.6.0 lets you change the default maximum header size. This parameter, --max-http-header-size, lets you specify the maximum size, in bytes, of HTTP headers.
To change the default configuration, set the value of the NODE_OPTIONS environment variable on the command line as follows:
NODE_OPTIONS=--max-http-header-size=NUM_BYTES

For example:

NODE_OPTIONS=--max-http-header-size=80000

What management APIs does Edge Microgateway use?

The following Edge Microgateway commands call Apigee Edge management APIs to do their work, as described in CLI reference for Edge Microgateway:

  • edgemicro configure
  • edgemicro upgradeauth
  • edgemicro upgradekvm
  • edgemicro rotatekey
  • edgemicro cert check
  • edgemicro cert delete
  • edgemicro cert install

The following sections list the management API calls that each command uses.

The edgemicro configure and upgradeauth commands call the following management APIs:

  • (list deployments) GET: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/deployments
  • (get deployment info) GET: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth
  • (upload resources) POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=java&name=micro-gateway-products-javacallout-2.0.0.jar
  • (upload resources) POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=adjust-quota.js
  • (upload resources) POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=generate-jwk.js
  • (upload resources) POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=generate-verify-jwt.js
  • (upload resources) POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=jsrsasign-all-min.js
  • (upload resources) POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=jwt-initialization.js
  • (upload resources) POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=send-jwk-response.js
  • (upload resources) POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=send-product-list.js
  • (upload resources) POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=send-public-key.js
  • (upload resources) POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=set-jwt-variables.js
  • (upload resources) POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=set-quota-variables.js
  • (upload resources) POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=set-response.js
  • (upload resources) POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=validate-params.js
  • (create api proxy) POST: https://api.enterprise.apigee.com/v1/o/[org]/apis?action=import&validate=false&name=edgemicro-auth
  • (upload policies) POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/policies
  • (upload proxies) POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/proxies?name=default
  • (deploy proxy) POST: https://api.enterprise.apigee.com/v1/o/[org]/e/[env]/apis/edgemicro-auth/revisions/1/deployments

The upgradekvm command calls the following management API:

  • PUT: https://api.enterprise.apigee.com/v1/organizations/[org]/environments/[env]/keyvaluemaps/microgateway

The rotatekey command calls the following management API:

  • GET: https://api.enterprise.apigee.com/v1/organizations/[org]/environments/[env]/keyvaluemaps/microgateway/entries/private_key

The cert check command calls the following management API:

  • GET: https://api.enterprise.apigee.com/v1/organizations/[org]/environments/[env]/keyvaluemaps/microgateway

The cert delete command calls the following management API:

  • DELETE: https://api.enterprise.apigee.com/v1/organizations/[org]/environments/[env]/keyvaluemaps/microgateway

The cert install command calls the following management API:

  • POST: https://api.enterprise.apigee.com/v1/organizations/[org]/environments/[env]/keyvaluemaps

Deployment

Can I deploy Edge Microgateway on the same server where my target service is running?
Yes. Edge Microgateway is a lightweight process that can run close to your target service, including on the same machine.
Can I deploy an existing Edge proxy bundle as an Edge Microgateway deployment?
No. Edge Microgateway-aware proxies have specific requirements and do not support all the features of regular Edge proxies. See Part 2: Create entities on Apigee Edge
Can I enable failover between an Edge proxy bundle deployment and Edge Microgateway deployment for the same API Proxy?
No. Edge Microgateway does not know about non-microgateway API proxy deployments on Apigee Edge.
What is the high availability deployment model for Edge Microgateway?
For a good discussion of how to run Edge Microgateway using NGINX as a load balancer, see Managing APIs with Apigee Edge Microgateway and NGINX.
Which load balancers can I use with Edge Microgateway?
Edge Microgateway can work with any load balancer.
Is there a limit on how many Edge Microgateway proxies I can deploy?
Refer to the product configuration limits specified for regular Edge proxies. The number of microgateway-aware proxies you can deploy in an Apigee Edge organization and environment and call through Edge Microgateway must conform to those same limits.
Can I associate my Edge Microgateway deployment to a specific organization and environment?
When you configure an instance of Edge Microgateway you must associate it with a specific Edge organization and environment.
Can I associate my Edge Microgateway deployment to a specific region (if I am a multi-region customer)?
Edge Microgateway automatically picks the best region for its interaction with Apigee Edge. You can deploy Edge Microgateway instances in each region that you want to service.

Administration

Do I need to be an org administrator to configure and deploy Edge Microgateway?
Yes. You need to have org admin credentials to configure and deploy Edge Microgateway.
Do I need to be an org administrator to run Edge Microgateway?
No. Edge Microgateway is a Node.js application, and can be run by anyone with permission to run such applications on a given machine.
Can any of my organization users use Edge Microgateway?
You do not need to be an Apigee Edge organization user to make API calls through Edge Microgateway. However, you must have org-level permissions to create or change Edge Microgateway aware proxies that are deployed on Edge.

Performance

What are the performance considerations for using Edge Microgateway?
If running Edge Microgateway collocated with the target application, be sure the server has sufficient capacity.
What are best practices for running Edge Microgateway at scale?
Apigee recommends running multiple instances of Edge Microgateway on different servers fronted by load balancers like NGINX. See also Managing APIs with Apigee Edge Microgateway and NGINX and Vertical horizontal scaling on the Apigee Community.
What are the Edge Microgateway TPS by default and what are hardware requirements required for a Microgateway instance
Hardware requirements and TPS measurements are difficult to gauge with Edge Microgateway. It depends on your setup, which is a combination of tuning Edge Microgateway, plugin usage, custom plugins, and configuring other things like TLS. Apigee typically recommends that you get an idea of that combination of items and do performance testing with your specific setup.

Private Cloud deployment

Does Edge Microgateway work with Edge for Private Cloud?
Yes. For details, see Apigee Private Cloud configuration steps.

Plugins

How is Quota enforced with Edge Microgateway?
You can optionally add a quota plugin to your instance of Edge Microgateway. For details see Using the quota plugin.
How is Spike Arrest enforced with Edge Microgateway?
You can optionally add a spike arrest plugin to your instance of Edge Microgateway. For details see Using the spike arrest plugin.
Are there other ways to write plugins other than Node.js for Edge Microgateway?
No. Plugins must be written in Node.js.
What happens when Edge Microgateway is not able to upload Analytics data to Edge?
Edge Microgateway has an in-memory buffer. If the buffer fills up, older payloads are dropped to let API traffic flow smoothly.
Can I add policies to Edge Microgateway?
If you attach regular Apigee Edge policies to microgateway-aware proxies in Apigee Edge, they are ignored. Instead, Edge Microgateway uses plugins to provide functionality similar to policies in Edge, such as quota, spike arrest, API key security, and OAuth2 security. You can also write custom plugins. See Use plugins and Develop custom plugins.

The following Apigee Community posts and blogs discuss additional plugin use cases:

Security

How do I protect the /products resource?
Overview
When you configure Edge Microgateway, an API proxy called edgemicro-auth is deployed to your organization:environment on Apigee Edge. This proxy exposes a /products endpoint that returns a list of API Products. If you installed Edge Microgateway on or before October 5, 2018, Apigee recommends that you take steps to protect this endpoint, because the response contains the email address of the developer who created and modified the API Products in your Apigee organization.
You can protect the endpoint by upgrading Edge Microgateway or by configuring Mutual TLS. Both of these options are described below.
Check if the /products endpoint is protected

If you are unsure whether the /products endpoint is protected, go to the section Verify that the /products resource is protected and do the steps there before continuing.

Option 1: Upgrade Edge Microgateway

If you installed Edge Microgateway on or before October 5, 2018, Apigee recommends that you upgrade to the latest version of Edge Microgateway. Follow the steps in Upgrading Edge Microgateway if you have an internet connection.

If you are unable to upgrade at this time, go to Option 2.

Option 2: Configure Mutual TLS

If you are unable to upgrade Edge Microgateway at this time, Apigee recommends that you protect the communication between Edge Microgateway and the edgemicro-auth proxy with mutual TLS (also known as two-way TLS).

  1. Open the file $HOME/.edgemicro/org-env-config.yaml. See Where is Edge Microgateway installed if you can't locate this file.
  2. Add the following tlsOptions block to the org-env-config.yaml file to enable mutual TLS between Edge Microgateway and Apigee Edge:
    edge_config:
      bootstrap: >-
        https://domain/edgemicro/bootstrap/organization/org/environment/env
      jwt_public_key: 'https://domain/edgemicro-auth/publicKey'
      managementUri: 'https://api.enterprise.apigee.com'
      tlsOptions:
        agentOptions:
          requestCert: true
          cert: 'path/to/cert'
          key: 'path/to/key'

    For example:

    tlsOptions:
      agentOptions:
        requestCert: true
        cert: '/Users/jdoe/twowayssl/ssl/client.key'
        key: '/Users/jdoe/twowayssl/ssl/ca.crt'

    You can also include the following optional agentOptions parameters:

    • ca: Specifies the path to certificate authority.
    • pfx: Include if you wish to use a p12/pfx file instead of cert and key.
    • passphrase: The passphrase for a pfx file.
    • ciphers: Specifies TLS ciphers.
  3. Ensure the virtual host to which the edgemicro-auth proxy is deployed has mutual TLS enabled. For details, see Defining a virtual host for two-way TLS in the Apigee Edge documentation.

    The following screenshot shows how to enable mutual TLS on a virtual host in the Apigee Edge UI:

  4. Look at the edgemicro-auth API proxy in the Edge UI, and ensure that the correct virtual host is specified in the proxy config. For example, if you created a TLS-enabled virtual host called mutualtls, the proxy's HTTPProxyConnection stanza should look like this:
    <HTTPProxyConnection>
        <BasePath>/edgemicro-auth</BasePath>
        <Properties/>
        <VirtualHost>mutualtls</VirtualHost>
    </HTTPProxyConnection>
Verify that the /products resource is protected
This section explains how to test to check if the /products resource is protected. It's important to perform this test after you have completed the steps (Option 1 or Option 2) to protect the resource. You can do this with cURL, for example:
curl -v https://your_domain/edgemicro-auth/products
If you see a response like one of the following, the /products endpoint is protected:
{
  "error":"unauthorized",
  "error_description": "authentication failed"
}

OR

curl: (35) error:1408F10B:SSL routines:ssl3_get_record:wrong version number

If you see a response that looks like this, then the /products resource is unprotected and developer emails can be exposed:

{
   "apiProduct":[
      {
         "apiResources":[
            "/",
            "/**"
         ],
         "approvalType":"auto",
         "attributes":[

         ],
         "createdAt":1537374680948,
         "createdBy":"jdoe@foo.com",
         "description":"",
         "displayName":"mock",
         "environments":[
            "test"
         ],
         "lastModifiedAt":1537374680948,
         "lastModifiedBy":"test@test.com",
         "name":"mock",
         "proxies":[
            "edgemicro-auth",
            "edgemicro_mock"
         ],
         "quota":"null",
         "quotaInterval":"null",
         "quotaTimeUnit":"null",
         "scopes":[
            ""
         ]
      }
   ]
}

Apigee also recommendeds that you test the HTTP virtual host:

For example:

curl -v http://your_domain/edgemicro-auth/products

If the cURL call returns the list of API Products, then it's possible that developer emails are exposed. If you do not wish to expose the endpoint with this non-TLS virtual host, be sure to remove it from the edgemicro-auth HTTPProxyConnection configuration.

To protect the resource do one of the following options:

How can I renew an expired access token?

Currently, you cannot renew the JWT token for a given Edge Microgateway instance.

Workaround:

Each JWT token has an exp attribute that states the expiration date of the token. An app can calculate the expiration time and request a new token by making an API call directly to the edgemicro-auth token endpoint. For example, you can make an API call like this:

POST https: //{your_org}-{your_env}.apigee.net/edgemicro-auth/token

... with a JSON body like this:

{ "client_id": {your_id}, "client_secret": {your_secret}, "grant_type": "client_credentials" }

See also:

Configuring SSL on Windows
If you are running Edge Microgateway on Windows, OpenSSL must be installed on the machine and added to the PATH. Not all Windows machines are shipped with OpenSSL. Refer to the OpenSSL documentation for information about downloading and installing OpenSSL.
Can I allow access to API resources using the API product associated with an Edge Micro-aware proxy?

Currently, only the basepath is checked to determine if an API is approved for API Products associated with a particular OAuth token.

For example:

  1. You create an edgemicro_ prefixed proxy with base path and target.
  2. You add this proxy to a product. Let's call it edgemicro-prod1.
  3. When an API call is made through Edge Microgateway using either an API key or an OAuth token, Edge Microgateway checks if the basepath of the API matches with the basepath of edgemicro_* proxy that is approved for the list of products approved for that key or token.

See also When using the edgemicro gateway in the products which url needs whitelisting in the products used under resources? on the Apigee Community.

Can I use custom SSL certificates with Edge Microgateway?

Only the default Apigee SSL cert is currently supported. Custom SSL certs are not supported at this time.

Workarounds:

If you wish to use a custom (non-Apigee default) SSL cert, you have these options:

  • Use a non-SSL jwt_public_key endpoint. Modify Edge Microgateway configuration file to use http://{org}-{env}.apigee.net/edgemicro-auth/publicKey -or-
  • Before starting Edge Microgateway, set this environment variable: export NODE_TLS_REJECT_UNAUTHORIZED ="0"

See also Verify Edge Micro install errors on SSL cert on the Apigee Community.

Can I avoid using Org Admin accounts with Edge Microgateway?
The Edge Microgateway configuration script deploys an edgemicro-auth proxy to Edge, and this deployment requires Org Admin credentials.
However, after this initial deployment, you should be able to do the remaining setup and configuration without needing Org Admin credentials. See also this community post on org admin credentials.
Can I use my own OAuth token with Edge Microgateway?

You can use your own token, but first, you must turn off the built-in authorization for Edge Microgateway. To do this:

  1. Open the config file for Edge Microgateway.
  2. Change the two oauth settings to true, as follows:

    oauth:
        allowNoAuthorization: true
        allowInvalidAuthorization: true
I am getting an access denied error when starting Edge Microgateway
If you get an access denied error when starting Edge Microgateway with this command:
edgemicro start -o [org] -e [env] -k [key] -s [secret]
It is possible the key and secret are not valid for some reason. The best thing to do is regenerate the key and secret with the edgemicro genkeys command.

Testing and debugging

How do I prevent "too many file open" errors during load testing?

In some cases, your system may run into a situation where too many open file connections, and this can cause Edge Micro to crash. The default logging requires two HTTP connections for incoming and outgoing transactions through the Microgateway.

For testing and benchmarking purposes, Apigee recommends setting your system's ulimit command to unlimited: ulimit -n unlimited. See also Edge Microgateway error during load testing on the Apigee Community.

Tips for rapid development and debugging

If you are developing plugins for Edge Microgateway, you may find that support for rapid development is limited.

For now, here are some tips:

  • For starting Edge Microgateway, you can set the environment variables EDGEMICRO_KEY and EDGEMICRO_SECRET to the key/secret pair required by the Microgateway startup command. This allows you to start Edge Microgateway without entering the key/secret at the command line. See also Setting environment variables in the Edge Microgateway docs.
  • Start Edge Microgateway in DEBUG mode to see additional output in the command terminal: DEBUG=* edgemicro start -o [org] -e [env] -k [key] -s [secret]

Business and licensing

What is the relationship between Apigee-127 and Edge Microgateway support models?

Apigee-127 is an open source software project that is supported in the open source model. That is, you can raise issues in the GitHub project and make a pull request if you attempt to fix something. Apigee-127 does not require or include any Software Licenses Agreements with Apigee.

Edge Microgateway, on the other hand, is an Enterprise product that is supported by Apigee for Apigee customers. That is, Apigee customers can create support tickets, feature requests, and bug reports using Google Cloud Apigee Edge Support.