|
| 1 | +--- |
| 2 | +title: Adding proxy certificates to router containers |
| 3 | +subtitle: Configure the router to trust your proxy's root certificate |
| 4 | +description: Learn how to add your corporate proxy's root certificate to Apollo Router containers to enable TLS inspection in enterprise environments. |
| 5 | +--- |
| 6 | + |
| 7 | +import ElasticNotice from '../../../../shared/elastic-notice.mdx'; |
| 8 | + |
| 9 | +If your organization uses a corporate proxy that performs TLS inspection (also known as SSL inspection or HTTPS interception), you need to add the proxy's root certificate to your router container. Without this, the router cannot establish secure connections to GraphOS or your subgraphs. |
| 10 | + |
| 11 | +<ElasticNotice /> |
| 12 | + |
| 13 | +## Why proxy certificates are required |
| 14 | + |
| 15 | +Corporate proxies often intercept HTTPS traffic for security monitoring. When they do, they decrypt and re-encrypt traffic using their own certificate. For the router to trust these connections, it must have the proxy's root certificate authority (CA) certificate installed in its trust store. |
| 16 | + |
| 17 | +Common symptoms of a missing proxy certificate include: |
| 18 | +- Connection failures to Apollo Uplink |
| 19 | +- TLS handshake errors when fetching the supergraph schema |
| 20 | +- Certificate verification failures when connecting to subgraphs |
| 21 | + |
| 22 | +## Adding certificates to Docker containers |
| 23 | + |
| 24 | +The Apollo Router container images are based on Debian and use the system CA certificate store at `/etc/ssl/certs/`. |
| 25 | + |
| 26 | +### Option 1: Mount the certificate at runtime |
| 27 | + |
| 28 | +Mount your proxy's root certificate and update the CA store when starting the container: |
| 29 | + |
| 30 | +```bash title="Docker" |
| 31 | +docker run -p 4000:4000 \ |
| 32 | + --env APOLLO_GRAPH_REF="<your-graph-ref>" \ |
| 33 | + --env APOLLO_KEY="<your-graph-api-key>" \ |
| 34 | + -v /path/to/proxy-ca.crt:/usr/local/share/ca-certificates/proxy-ca.crt:ro \ |
| 35 | + --user root \ |
| 36 | + --entrypoint /bin/bash \ |
| 37 | + ghcr.io/apollographql/router:<router-image-version> \ |
| 38 | + -c "update-ca-certificates && su -s /bin/bash router -c '/dist/router_wrapper.sh'" |
| 39 | +``` |
| 40 | + |
| 41 | +### Option 2: Build a custom image with the certificate |
| 42 | + |
| 43 | +For production deployments, build a custom image that includes your proxy's root certificate: |
| 44 | + |
| 45 | +```dockerfile title="Dockerfile" |
| 46 | +FROM ghcr.io/apollographql/router:<router-image-version> |
| 47 | + |
| 48 | +# Switch to root to install the certificate |
| 49 | +USER root |
| 50 | + |
| 51 | +# Copy the proxy's root certificate |
| 52 | +COPY proxy-ca.crt /usr/local/share/ca-certificates/proxy-ca.crt |
| 53 | + |
| 54 | +# Update the CA certificate store |
| 55 | +RUN update-ca-certificates |
| 56 | + |
| 57 | +# Switch back to the router user |
| 58 | +USER router |
| 59 | +``` |
| 60 | + |
| 61 | +Build and run the custom image: |
| 62 | + |
| 63 | +```bash |
| 64 | +docker build -t router-with-proxy-cert . |
| 65 | +docker run -p 4000:4000 \ |
| 66 | + --env APOLLO_GRAPH_REF="<your-graph-ref>" \ |
| 67 | + --env APOLLO_KEY="<your-graph-api-key>" \ |
| 68 | + router-with-proxy-cert |
| 69 | +``` |
| 70 | + |
| 71 | +## Adding certificates in Kubernetes |
| 72 | + |
| 73 | +When deploying with Kubernetes, you can use a ConfigMap or Secret to provide the certificate and an init container to install it. |
| 74 | + |
| 75 | +### Using an init container |
| 76 | + |
| 77 | +1. Create a ConfigMap with your proxy certificate: |
| 78 | + |
| 79 | + ```bash |
| 80 | + kubectl create configmap proxy-ca-cert --from-file=proxy-ca.crt=/path/to/proxy-ca.crt |
| 81 | + ``` |
| 82 | + |
| 83 | +2. Configure your deployment to use an init container that installs the certificate: |
| 84 | + |
| 85 | + ```yaml title="values.yaml" |
| 86 | + router: |
| 87 | + extraVolumes: |
| 88 | + - name: proxy-ca-cert |
| 89 | + configMap: |
| 90 | + name: proxy-ca-cert |
| 91 | + - name: ca-certs |
| 92 | + emptyDir: {} |
| 93 | + |
| 94 | + extraVolumeMounts: |
| 95 | + - name: ca-certs |
| 96 | + mountPath: /etc/ssl/certs |
| 97 | + |
| 98 | + initContainers: |
| 99 | + - name: install-proxy-cert |
| 100 | + image: ghcr.io/apollographql/router:<router-image-version> |
| 101 | + command: ["/bin/bash", "-c"] |
| 102 | + args: |
| 103 | + - | |
| 104 | + cp -r /etc/ssl/certs/* /ca-certs/ |
| 105 | + cp /proxy-cert/proxy-ca.crt /usr/local/share/ca-certificates/ |
| 106 | + update-ca-certificates |
| 107 | + cp -r /etc/ssl/certs/* /ca-certs/ |
| 108 | + securityContext: |
| 109 | + runAsUser: 0 |
| 110 | + volumeMounts: |
| 111 | + - name: proxy-ca-cert |
| 112 | + mountPath: /proxy-cert |
| 113 | + - name: ca-certs |
| 114 | + mountPath: /ca-certs |
| 115 | + ``` |
| 116 | +
|
| 117 | +### Building a custom image for Kubernetes |
| 118 | +
|
| 119 | +Alternatively, build a custom Docker image with the certificate included (as shown above) and reference it in your Helm values: |
| 120 | +
|
| 121 | +```yaml title="values.yaml" |
| 122 | +router: |
| 123 | + image: |
| 124 | + repository: your-registry/router-with-proxy-cert |
| 125 | + tag: <your-tag> |
| 126 | +``` |
| 127 | +
|
| 128 | +## Adding certificates for cloud deployments |
| 129 | +
|
| 130 | +For cloud deployments (AWS ECS, Azure Container Apps, GCP Cloud Run), the recommended approach is to build a custom Docker image that includes your proxy's root certificate, then push that image to your cloud provider's container registry. |
| 131 | +
|
| 132 | +Follow the [custom image instructions above](#option-2-build-a-custom-image-with-the-certificate), then push the image to your registry before deploying. |
| 133 | +
|
| 134 | +## Verifying the certificate is installed |
| 135 | +
|
| 136 | +To verify the certificate is correctly installed, you can check the container's CA store: |
| 137 | +
|
| 138 | +```bash |
| 139 | +docker run --entrypoint /bin/bash -it router-with-proxy-cert -c "ls /etc/ssl/certs | grep proxy" |
| 140 | +``` |
| 141 | + |
| 142 | +Or test connectivity to a service through the proxy: |
| 143 | + |
| 144 | +```bash |
| 145 | +docker run --entrypoint /bin/bash -it router-with-proxy-cert -c "curl -v https://uplink.api.apollographql.com/" |
| 146 | +``` |
| 147 | + |
| 148 | +## Related topics |
| 149 | + |
| 150 | +- [TLS configuration](/graphos/routing/security/tls) - Configure TLS settings for the router |
| 151 | +- [Docker deployment](/graphos/routing/self-hosted/containerization/docker) - Deploy the Apollo Runtime in Docker |
| 152 | +- [Kubernetes deployment](/graphos/routing/self-hosted/containerization/kubernetes/quickstart) - Deploy the router with Helm charts |
0 commit comments