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?

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:

• How to override the default URL on Edge Microgateway
• How to get Quota working in Edge Microgateway
• Adding a logger plugin to Edge Microgateway

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>
   

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

{
  "error":"unauthorized",
  "error_description": "authentication failed"
}

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

{
   "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":[
            ""
         ]
      }
   ]
}

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

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.