HTTP proxy configuration

Corporate network environments often require outbound HTTP traffic to pass through a proxy. Apollo Router supports standard proxy environment variables for its control-plane and telemetry connections, and can be configured to trust a proxy's TLS certificate when the proxy performs traffic inspection.

Affected connections

Apollo Router respects HTTP_PROXY, HTTPS_PROXY, and NO_PROXY for connections that use its internal reqwest-based HTTP client. This includes:

• Apollo Uplink — fetches the supergraph schema, license, and persisted query manifests

• GraphOS telemetry — reports traces and metrics to GraphOS (Apollo Usage Reporting protocol and OTLP HTTP)

• Third-party telemetry exporters — Datadog traces and other exporters using the HTTP transport

• JWKS endpoints — fetches JSON Web Key Sets for JWT authentication

Subgraph connections are not affected. The router uses a separate high-performance HTTP client built directly on hyper for subgraph traffic. That client doesn't read proxy environment variables. To proxy subgraph traffic, configure your network layer (for example, a service mesh or sidecar) instead.

Configure proxy routing

Set HTTPS_PROXY and NO_PROXY before starting the router. The router reads these variables at startup — restart the router for changes to take effect.

1export HTTPS_PROXY=https://your-proxy.example.com:3128
2export NO_PROXY=localhost,127.0.0.1

If your proxy performs TLS inspection, also add the proxy's root certificate to the router's trust store. See Add the proxy certificate below.

Add the proxy certificate

If your proxy performs TLS inspection (SSL inspection or HTTPS interception), it decrypts and re-encrypts HTTPS traffic using its own certificate. Apollo Router must have the proxy's root CA certificate installed in its trust store to trust those connections. Without it, you'll see errors like:

• Connection failures to Apollo Uplink

• TLS handshake errors when fetching the supergraph schema

• Certificate verification failures in telemetry exporters

Apollo Router container images are based on Debian and use the system CA certificate store at /etc/ssl/certs/. You can add your proxy's certificate by either updating the container's CA store or by pointing the SSL_CERT_FILE environment variable at a certificate bundle.

Use SSL_CERT_FILE

Set SSL_CERT_FILE to the path of a PEM bundle that contains both your proxy's root CA certificate and the standard system CA certificates. Apollo Router reads this variable at startup for all TLS connections.

1# Combine your proxy CA with the system CA bundle
2cat /etc/ssl/certs/ca-certificates.crt /path/to/proxy-ca.crt > /path/to/combined-ca-bundle.pem
3export SSL_CERT_FILE=/path/to/combined-ca-bundle.pem

Add certificates to Docker containers

Mount the certificate at runtime

Mount your proxy's root certificate and update the CA store when you start the container.

1docker run -p 4000:4000 \
2  --env APOLLO_GRAPH_REF="<your-graph-ref>" \
3  --env APOLLO_KEY="<your-graph-api-key>" \
4  -v /path/to/proxy-ca.crt:/usr/local/share/ca-certificates/proxy-ca.crt:ro \
5  --user root \
6  --entrypoint /bin/bash \
7  ghcr.io/apollographql/router:<router-image-version> \
8  -c "update-ca-certificates && su -s /bin/bash router -c '/dist/router_wrapper.sh'"

Build a custom image

For production deployments, build a custom image that includes your proxy's root certificate.

1FROM ghcr.io/apollographql/router:<router-image-version>
2
3USER root
4COPY proxy-ca.crt /usr/local/share/ca-certificates/proxy-ca.crt
5RUN update-ca-certificates
6USER router

Build and run the custom image.

1docker build -t router-with-proxy-cert .
2docker run -p 4000:4000 \
3  --env APOLLO_GRAPH_REF="<your-graph-ref>" \
4  --env APOLLO_KEY="<your-graph-api-key>" \
5  router-with-proxy-cert

Add certificates in Kubernetes

Use a ConfigMap and an init container to install the certificate.

1. Create a ConfigMap with your proxy certificate.

   Bash

   copy

   1kubectl create configmap proxy-ca-cert --from-file=proxy-ca.crt=/path/to/proxy-ca.crt

2. Configure your deployment to use an init container that installs the certificate.

   YAML

   values.yaml

   copy

   1extraVolumes:
   2  - name: proxy-ca-cert
   3    configMap:
   4      name: proxy-ca-cert
   5  - name: ca-certs
   6    emptyDir: {}
   7
   8extraVolumeMounts:
   9  - name: ca-certs
   10    mountPath: /etc/ssl/certs
   11
   12initContainers:
   13  - name: install-proxy-cert
   14    image: ghcr.io/apollographql/router:<router-image-version>
   15    command: ["/bin/bash", "-c"]
   16    args:
   17      - |
   18        cp -r /etc/ssl/certs/* /ca-certs/
   19        cp /proxy-cert/proxy-ca.crt /usr/local/share/ca-certificates/
   20        update-ca-certificates
   21        cp -r /etc/ssl/certs/* /ca-certs/
   22    securityContext:
   23      runAsUser: 0
   24    volumeMounts:
   25      - name: proxy-ca-cert
   26        mountPath: /proxy-cert
   27      - name: ca-certs
   28        mountPath: /ca-certs

To use a custom Docker image with Kubernetes instead, follow Build a custom image and reference it in your Helm values.

1image:
2  repository: your-registry/router-with-proxy-cert
3  tag: <your-tag>

Add certificates for cloud deployments

For cloud deployments (AWS ECS, Azure Container Apps, GCP Cloud Run), build a custom Docker image that includes your proxy's root certificate, then push it to your cloud provider's container registry.

Follow the custom image instructions, then push the image to your registry before deploying.

Verify the configuration

If you're using SSL_CERT_FILE, confirm the variable is set and the bundle is readable before starting the router:

1echo $SSL_CERT_FILE
2openssl verify -CAfile "$SSL_CERT_FILE" "$SSL_CERT_FILE"

If you're using the container CA store approach, check that the certificate is present:

1docker run --entrypoint /bin/bash -it router-with-proxy-cert -c "ls /etc/ssl/certs | grep proxy"

Test connectivity to Apollo Uplink through the proxy:

1docker run --entrypoint /bin/bash -it router-with-proxy-cert -c "curl -v https://uplink.api.apollographql.com/"

Related topics

• TLS configuration

• Docker deployment

• Kubernetes deployment