Add Proxy Certificates to Apollo Router Containers

If your organization uses a corporate proxy that performs TLS inspection (SSL inspection or HTTPS interception), add the proxy's root certificate to your router container. Adding this certificate enables Apollo Router to establish secure connections to GraphOS and your subgraphs.

Understanding proxy certificate requirements

Corporate proxies often intercept HTTPS traffic for security monitoring. They decrypt and re-encrypt traffic using their own certificate. Apollo Router must have the proxy's root certificate authority (CA) certificate installed in its trust store to trust these connections.

A missing proxy certificate causes these common symptoms:

• Connection failures to Apollo Uplink

• TLS handshake errors when fetching the supergraph schema

• Certificate verification failures when connecting to subgraphs

Adding certificates to Docker containers

Apollo Router container images are based on Debian and use the system CA certificate store at /etc/ssl/certs/.

Mounting the certificate at runtime

The recommended approach is to 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'"

Building 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

Adding certificates in Kubernetes

When deploying with Kubernetes, use a ConfigMap or Secret to provide the certificate and an init container to install it.

Using an init container

Create a ConfigMap with your proxy certificate:

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

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

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

Build a custom image for Kubernetes

The recommended approach is to build a custom Docker image with the certificate as described in Building a custom image and reference it in your Helm values.

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

Adding 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 that image to your cloud provider's container registry.

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

Verify certificate installation

Check the container's CA store:

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

Test connectivity to a service 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: Configure TLS settings for Apollo Router

• Docker deployment: Deploy Apollo Runtime using Docker

• Kubernetes deployment: Deploy Apollo Router using Helm