Docs
Launch GraphOS Studio
Apollo Server 3 is officially deprecated, with end-of-life scheduled for 22 October 2024. Learn more about upgrading to a supported Apollo Server version.

Proxy configuration

Configuring proxy settings for outgoing requests


Certain features of the Apollo platform (such as

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

).

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:

npm install global-agent

Bootstrapping the global-agent proxy agent

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

const { ApolloServer, gql } = require('apollo-server');
const {
ApolloServerPluginLandingPageLocalDefault
} = require('apollo-server-core');
const { bootstrap: bootstrapGlobalAgent } = require('global-agent');
// Setup global support for environment variable based proxy configuration.
bootstrapGlobalAgent();
// The following represents existing configuration, though its
// important to bootstrap the agent before Apollo Server.
const server = new ApolloServer({
typesDefs,
resolvers,
csrfPrevention: true,
cache: 'bounded',
plugins: [
ApolloServerPluginLandingPageLocalDefault({ embed: true }),
],
});

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 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 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:

$ 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:

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

For more information, see

in the global-agent documentation.

As shown above, the

are all prefixed with GLOBAL_AGENT_ to avoid undesirable by-products](
https://github.com/gajus/global-agent#what-is-the-reason-global-agentbootstrap-does-not-use-http_proxy
) 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:

$ 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

.

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

:

  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:

    $ NODE_EXTRA_CA_CERTS=/full/path/to/certificate.pem \
    GLOBAL_AGENT_HTTP_PROXY=http://proxy:3128/ \
    node index.js
Previous
Terminating SSL
Next
Heroku
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company