Add Proxy Certificates to 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. Without this certificate, Apollo Router can't establish secure connections to GraphOS or 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

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

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

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

Building a custom image for Kubernetes

Build a custom Docker image with the certificate as described in Building a custom image and reference it in your Helm values.

1router:
2  image:
3    repository: your-registry/router-with-proxy-cert
4    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.

Verifying the 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