What version of Node.js is supported on Apigee Edge?

Which standard Node.js modules are supported on Edge?

Use the following table to determine which standard Node.js modules are included on Edge. In some cases, included modules are only partially supported. These are modules that are built-in to Node.js.

Module

Status

Notes

assert

Supported

buffer

Supported

child_process

Restricted

An exception will be thrown if an attempt is made to spawn a sub-process. However, "fork" is supported for spawning sub-scripts.

cluster

Disabled

The method cluster.isMaster always returns true, and other methods are not implemented. One copy of each Node.js script is deployed to each Edge message processor.

crypto

Supported

dns

Supported

domain

Supported

dgram

Restricted

Node.js applications in the Apigee environment will not be able to access services on the Internet via UDP due to our network architecture.

events

Supported

fs

Restricted

Filesystem access is restricted to the directory where the script was launched: the /resources/node directory. Node.js scripts may read and write files within this directory, for instance as a temporary scratch area, but there are no guarantees as to how long the files will persist.

Attempts to listen for incoming TCP connections will generate an exception.

path

Supported

module

Supported

process

Partial support

Functionality to manipulate user ID, group membership, and working directory is not supported.

punycode

Supported

querystring

Supported

readline

Disabled

There is no standard input for scripts running on Apigee Edge.

repl

Disabled

There is no standard input for scripts running on Apigee Edge.

module

Included

STDIO

Supported

Standard output and error are routed to a log file within the Apigee Edge infrastructure. You can view these logs by clicking the Node.js Logs button in and Apigee Edge management UI for your API proxy.

There is no standard input for scripts running on Apigee Edge. However, you can pass arguments using the ScriptTarget element of TargetEndpoint. See Advanced ScriptTarget configuration for more information.

Additional supported modules

This section lists additional modules that are not supported in standard Node.js, but are supported by Trireme and Trireme running on Apigee Edge. Trireme is the open-source Node.js container that runs on Apigee Edge. It is designed to run Node.js scripts inside a Java Virtual Machine (JVM). All of these modules are available on NPM.

Allows Node.js applications running on the Apigee Edge platform a way to access Apigee-specific functionality. You can use this module to: access and modify flow variables, retrieve data from the secure store, and use Edge cache, quota, and OAuth services. See also Using the apigee-access module.

Lets Node.js applications take advantage of features specific to Trireme. Currently there is only one feature supported -- loading Node.js modules built in Java. Note: loadJars is not supported in Edge Cloud.

Support for commonly used Node.js modules

Node.js on Apigee Edge includes some pre-installed Node.js modules, such as Express, that you can use without uploading them with your Node.js project. However, using these pre-installed modules is not recommended as they are not guaranteed to be up to date, and for this reason, they are no longer documented.

Restrictions on Node.js scripts

Note, however, that Edge imposes certain restrictions on Node.js scripts, such as the following:

Node.js applications in the Apigee Edge environment cannot access services on the Internet via UDP because of the Edge network architecture.

Filesystem access is restricted to the directory where the Node.js script was launched: the /resources/node directory. Node.js scripts can read and write files within this directory, for instance as a temporary scratch area, but there are no guarantees as to how long the files will persist.

Attempts to listen for incoming TCP connections generate an exception.

Functionality to manipulate user ID, group membership, and working directory is not supported.

For standard output, you are limited to using the Node.js Logs button in the Edge management UI for your proxy. You can also use the "apigeetool getlogs" command. For more information, see Deploying a standalone Node.js app.

Modules that depend on native code are not supported.

Modules that depend on EcmaScript 6 features, such as Promises and Generators, are not supported.

The Node.js runtime flags such as "harmony-proxies" are not supported.

Setting IP connection restrictions on Edge for Private Cloud

Edge for Private Cloud can restrict Node.js code from accessing IP addresses starting with “10.", "192.168", and localhost. If you attempt to access these IP addresses, you will see an error in the form:

You can modify these restrictions by setting the conf_nodejs_connect.ranges.denied property in the message-processors.properties file for each Message Processor. By default, this property has the value:

Understanding support for the http and https modules

All Node.js applications running in Apigee Edge must use the http or https module to listen for incoming requests. If you were to deploy a script that doesn't listen for incoming requests, it would simply execute and exit.

The listen method of the http and https modules in Node.js takes a port number as a parameter. For example:

This "port" argument is required in Node.js, but Apigee Edge ignores this parameter. Instead, the API proxy in which the Node.js script runs specifies the "virtual host" that it listens on, and the Node.js application uses those same virtual hosts, just like any other Apigee Edge proxy.

Coding the port number to be retrieved from an environment variable conditionally, as shown in the example above, is considered a best practice by Apigee.

Every environment in Apigee has at least one virtual host. The virtual host defines the HTTP settings for connection with the Apigee organization. All API proxies in an environment share the same virtual hosts. By default, two virtual hosts are available for each environment: default and secure. For more information, see Get Virtual Host and API development lifecycle.

The apigeetool deploynodeapp command generates an Apigee Edge proxy wrapper around the Node.js application. When deployed, the Node.js application listens on the default virtual host defined for the environment. The URL for a Node.js application will always be http://{org_name}-{env_name}.apigee.net.

Handling incoming requests

Like other Apigee Edge applications, if the proxy application is set up to listen on the secure virtual host, then it will accept incoming requests using HTTPS.

Handling outgoing requests

In addition to receiving incoming traffic, Node.js applications inside Apigee Edge may use the http and https modules to make outbound requests like any other Node.js application. These modules work just as they always do inside Node.js.

If you use custom TLS/SSL certificates or trust stores, the Apigee Edge support for outbound requests works differently. Contact Apigee Support if you have questions.

To understand how the tls module works on Apigee Edge, it's important to understand how virtual hosts are used on Apigee Edge. Every environment in Apigee has at least one virtual host. The virtual host defines the HTTP settings for connection with the Apigee organization. All API proxies in an environment share the same virtual hosts. By default, two virtual hosts are available for each environment: default and secure. For more information on virtual hosts, see Get Virtual Host and API development lifecycle.

Handling incoming requests

Depending on how virtual hosts are configured for your organization, Edge provides these options:

If the API proxy is configured to listen on the default virtual host, then it accepts requests over HTTP.

If the API proxy is configured to listen on the secure virtual host, then it accepts requests over HTTPS. The URL will be under the apigee.net domain, and a wildcard SSL certificate for *.apigee.net will be used. As long as apps make requests to the apigee.net domain, then the SSL certificate will validate normally.

To use custom TLS/SSL certificates for inbound traffic, see Apigee Support at the Support Portal.

Handling outgoing requests

You can make outgoing requests with the tls module the same way you would normally in Node.js. Basically, you need to add client-side keys and certificates (.pem files) to the resources/node directory and load them inside your script. For information on using the tls module and its methods, see the Node.js tls module documentation.

Advanced ScriptTarget Configuration

In the <TargetEndpoint> definition, the <ScriptTarget> element takes additional optional parameters besides <ResourceURL>. You can also pass command-line arguments and environment variables to a Node.js script using the <EnvironmentVariables> and <Arguments> parameters:

You can get a listing of all environment variables that are set when a Node.js app starts up on Edge by executing this line of code in your Node.js server:console.log('environment variables: ' + JSON.stringify(process.env));

Variables set include APIGEE_ORGANIZATION and APIGEE_ENVIRONMENT. For example (actual values are omitted):