Proxy configuration

Certain features of the Apollo platform (such as managed federation) require Apollo Server to make outgoing requests to Apollo Studio. Depending on security policies, you might need to configure an outgoing HTTP proxy in order to allow these requests.

Although Apollo Server supports standard Node.js "agent" configuration via https.globalAgent and http.globalAgent directly, we recommend using the global-agent package to reduce the amount of necessary configuration involved with creating a custom agent.

The global-agent package enables the common technique of setting proxy settings using environment variables (e.g. HTTP_PROXY, NO_AGENT, etc.), which is not supported by Node.js itself (and may never be).

Configuring the proxy agent

This guide covers the global-agent package, which is supported by Node.js version 10 and later.

Installing the global-agent dependency

First, install the global-agent package with your dependency manager:

1
npm install global-agent

Bootstrapping the global-agent proxy agent

After the global-agent dependency has been installed, invoke its bootstrap method before Apollo Server is initialized:

1
import { ApolloServer } from '@apollo/server';
2
import { bootstrap } from 'global-agent'; 
3

4
// Setup global support for environment variable based proxy configuration.
5
bootstrap(); 
6

7
// The following represents existing configuration, though its
8
// important to bootstrap the agent before Apollo Server.
9
const server = new ApolloServer({
10
  typeDefs,
11
  resolvers,
12
});

Configuring the proxy using environment variables

Depending on the deployment environment (e.g. AWS, Heroku, Kubernetes, Docker, etc.), environment variables may be set differently. These instructions will demonstrate how to start a node process using environment variables in a Unix-based shell.

By default, the above bootstrapping step will enable the following environment variables:

• GLOBAL_AGENT_HTTP_PROXY

  This is often the most important and solely necessary environment variable to set.

• GLOBAL_AGENT_HTTPS_PROXY

  This variable defines where HTTPS traffic (i.e. encrypted SSL/TLS traffic) is proxied. If this is not set, HTTPS traffic will route through the HTTP proxy.

• GLOBAL_AGENT_NO_PROXY

  This variable allows the exclusion of certain domains from being proxied.

By setting these environment variables, it is possible to configure global-agent's creation of the agent that is used for outgoing requests. If the proxy requires special certificates for SSL/TLS requests, read the details later in this page.

Using the appropriate environment variables, define them when starting the server. For example, to send all outgoing requests from a Node.js server through http://proxy:3128, the configuration would be:

1
$ GLOBAL_AGENT_HTTP_PROXY=http://proxy:3128/ node index.js

The GLOBAL_AGENT_NO_PROXY environment variable can also be defined to exclude certain URLs from being proxied:

1
$ GLOBAL_AGENT_NO_PROXY='*.foo.com,10.0.1.100,baz.com' node index.js

As shown above, the supported environment variables are all prefixed with GLOBAL_AGENT_ to avoid undesirable by-products of using the more common non-prefixed versions (e.g. HTTP_PROXY). To disable this default namespacing (i.e. prefixing), the server can be started with GLOBAL_AGENT_ENVIRONMENT_VARIABLE_NAMESPACE set to an empty string:

1
$ GLOBAL_AGENT_ENVIRONMENT_VARIABLE_NAMESPACE="" HTTP_PROXY=http://proxy:3128/ node index.js

Of course, a custom namespace can also be provided as well. For more details on the configuration, see the documentation for global-agent.

Specifying a custom SSL/TLS certificate

Depending on the proxy communication, it may be necessary to extend the default "root" certificates which Node.js trusts to include a certificate provided by the proxy administrator. These certificates will usually allow the proxy to handle SSL/TLS traffic and permits the proxy to analyze such traffic.

This can be done via Node.js' NODE_EXTRA_CA_CERTS environment variable:

1. The appropriate certificate (i.e. PEM file) must be present on the file-system where the server is running.
2. Start the server with the NODE_EXTRA_CA_CERTS environment variable set to that path, combined with the existing proxy configuration variables which were explained above:

1
$ NODE_EXTRA_CA_CERTS=/full/path/to/certificate.pem \
2
  GLOBAL_AGENT_HTTP_PROXY=http://proxy:3128/ \
3
  node index.js