docs: add proxy certificate instructions for containerized deployments

.changesets/docs_proxy_certificates.md

@@ -0,0 +1,11 @@
+### Add documentation for adding proxy root certificates to router containers ([PR #8823](https://github.com/apollographql/router/pull/8823))
+
+Adds documentation explaining how to add corporate proxy root certificates to Apollo Router containers. This is necessary for enterprise environments where TLS inspection proxies intercept HTTPS traffic.
+
+The new documentation includes:
+- Instructions for Docker deployments (runtime mount and custom image approaches)
+- Instructions for Kubernetes deployments (init container and custom image approaches)
+- Guidance for cloud deployments (AWS, Azure, GCP)
+- Links added to all containerization deployment guides
+
+By [@the-gigi-apollo](https://github.com/the-gigi-apollo) in https://github.com/apollographql/router/pull/8823

docs/source/_sidebar.yaml

@@ -279,6 +279,8 @@ items:
         children:
           - label: "Google Cloud Run"
             href: "./self-hosted/containerization/gcp"
+      - label: "Proxy Certificates"
+        href: "./self-hosted/containerization/proxy-certificates"
       - label: "Managed Hosting"
         children:
           - label: "Railway"

docs/source/routing/self-hosted/containerization/aws.mdx

@@ -11,6 +11,12 @@
 - Set up an Elastic Cloud Registry and push your router image to it.
 - Create an ECS task definition for your router and deploy it.
 
+<Note>
+
+If your organization uses a corporate proxy with TLS inspection, [add your proxy's root certificate to the container](proxy-certificates).
+
+</Note>
+
 ## Prerequisites
 
 Before you start:

docs/source/routing/self-hosted/containerization/azure.mdx

@@ -11,6 +11,12 @@
 - Set up an Azure Container Registry and push your router image to it.
 - Create and deploy an Azure Container App for your router.
 
+<Note>
+
+If your organization uses a corporate proxy with TLS inspection, [add your proxy's root certificate to the container](proxy-certificates).
+
+</Note>
+
 ## Prerequisites
 
 Before you start:

docs/source/routing/self-hosted/containerization/docker-router-only.mdx

@@ -22,6 +22,12 @@
 
 <Note>This container image only contains the router. Apollo recommends using the [Apollo Runtime container](docker.mdx), which contains all Apollo runtime services.</Note>
 
+<Note>
+
+If your organization uses a corporate proxy with TLS inspection, [add your proxy's root certificate to the container](proxy-certificates).
+
+</Note>
+
 ## Basic example running router in Docker
 
 To run the router, set the [`APOLLO_GRAPH_REF`](/graphos/routing/configuration/envvars#apollo_graph_ref) and [`APOLLO_KEY`](/graphos/routing/configuration/envvars#apollo_key) environment variables in your Docker container to your graph ref and API key.
@@ -198,4 +204,4 @@
 		build_docker_image.sh -d v0.9.1
 ```
 
-The example uses [debian:bookwork-slim image](https://hub.docker.com/_/debian/) for the final image build. Feel free to modify the script to use images which better suit your own needs, but be careful if using the `-d` flag because it makes the assumption that there is a `heaptrack` package available to install.
+The example uses the [debian:bookworm-slim image](https://hub.docker.com/_/debian/) for the final image build. Modify the script to use images that better suit your needs. When you use the `-d` flag, ensure a `heaptrack` package is available to install.

docs/source/routing/self-hosted/containerization/docker.mdx

@@ -28,6 +28,12 @@
 
 <ElasticNotice />
 
+<Note>
+
+If your organization uses a corporate proxy with TLS inspection, [add your proxy's root certificate to the container](proxy-certificates).
+
+</Note>
+
 ## Quick start
 
 Run the following command, replacing the `APOLLO_GRAPH_REF` and `APOLLO_KEY` values with your own.

docs/source/routing/self-hosted/containerization/gcp.mdx

@@ -11,6 +11,12 @@
 - Set up a container registry and push your router image to it.
 - Create a Cloud Run service and configure it to deploy your router.
 
+<Note>
+
+If your organization uses a corporate proxy with TLS inspection, [add your proxy's root certificate to the container](proxy-certificates).
+
+</Note>
+
 ## Prerequisites
 
 Before you start:

docs/source/routing/self-hosted/containerization/index.mdx

@@ -29,3 +29,7 @@
 - [Azure using Azure Container Apps](/graphos/routing/self-hosted/containerization/azure)
 - [GCP using Google Cloud Run](/graphos/routing/self-hosted/containerization/gcp)
 - [Kubernetes](/router/containerization/kubernetes/)
+
+## Additional configuration
+
+- [Proxy certificates](/graphos/routing/self-hosted/containerization/proxy-certificates): Add your proxy's root certificate for TLS inspection environments

docs/source/routing/self-hosted/containerization/kubernetes/quickstart.mdx

@@ -27,6 +27,12 @@
 
 <ElasticNotice />
 
+<Note>
+
+If your organization uses a corporate proxy with TLS inspection, [add your proxy's root certificate to the container](/graphos/routing/self-hosted/containerization/proxy-certificates).
+
+</Note>
+
 This guide uses Helm charts to deploy a self-hosted router in Kubernetes. Using Helm is suitable for quick deployments, testing, or when you prefer direct Helm chart management.
 
 This guide shows how to:

docs/source/routing/self-hosted/containerization/proxy-certificates.mdx

@@ -0,0 +1,143 @@
+---
+title: Add Proxy Certificates to Router Containers
+subtitle: Configure trust for your proxy's root certificate
+description: Add your corporate proxy's root certificate to Apollo Router containers to enable TLS inspection in enterprise environments.
+---
+
+import ElasticNotice from '../../../../shared/elastic-notice.mdx';
+
+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.
+
+<ElasticNotice />
+
+## 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.
+
+```bash title="Docker"
+docker run -p 4000:4000 \
+  --env APOLLO_GRAPH_REF="<your-graph-ref>" \
+  --env APOLLO_KEY="<your-graph-api-key>" \
+  -v /path/to/proxy-ca.crt:/usr/local/share/ca-certificates/proxy-ca.crt:ro \
+  --user root \
+  --entrypoint /bin/bash \
+  ghcr.io/apollographql/router:<router-image-version> \
+  -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.
+
+```dockerfile title="Dockerfile"
+FROM ghcr.io/apollographql/router:<router-image-version>
+
+USER root
+COPY proxy-ca.crt /usr/local/share/ca-certificates/proxy-ca.crt
+RUN update-ca-certificates
+USER router
+```
+
+Build and run the custom image.
+
+```bash
+docker build -t router-with-proxy-cert .
+docker run -p 4000:4000 \
+  --env APOLLO_GRAPH_REF="<your-graph-ref>" \
+  --env APOLLO_KEY="<your-graph-api-key>" \
+  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
+    kubectl 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 title="values.yaml"
+    extraVolumes:
+      - name: proxy-ca-cert
+        configMap:
+          name: proxy-ca-cert
+      - name: ca-certs
+        emptyDir: {}
+
+    extraVolumeMounts:
+      - name: ca-certs
+        mountPath: /etc/ssl/certs
+
+    initContainers:
+      - name: install-proxy-cert
+        image: ghcr.io/apollographql/router:<router-image-version>
+        command: ["/bin/bash", "-c"]
+        args:
+          - |
+            cp -r /etc/ssl/certs/* /ca-certs/
+            cp /proxy-cert/proxy-ca.crt /usr/local/share/ca-certificates/
+            update-ca-certificates
+            cp -r /etc/ssl/certs/* /ca-certs/
+        securityContext:
+          runAsUser: 0
+        volumeMounts:
+          - name: proxy-ca-cert
+            mountPath: /proxy-cert
+          - name: ca-certs
+            mountPath: /ca-certs
+    ```
+
+### Building a custom image for Kubernetes
+
+Build a custom Docker image with the certificate as described in [Building a custom image](#building-a-custom-image) and reference it in your Helm values.
+
+```yaml title="values.yaml"
+image:
+  repository: your-registry/router-with-proxy-cert
+  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](#building-a-custom-image), then push the image to your registry before you deploy.
+
+## Verifying the certificate installation
+
+Check the container's CA store:
+
+```bash
+docker run --entrypoint /bin/bash -it router-with-proxy-cert -c "ls /etc/ssl/certs | grep proxy"
+```
+
+Test connectivity to a service through the proxy:
+
+```bash
+docker run --entrypoint /bin/bash -it router-with-proxy-cert -c "curl -v https://uplink.api.apollographql.com/"
+```
+
+## Related Topics
+
+- [TLS configuration](/graphos/routing/security/tls): Configure TLS settings for Apollo Router
+- [Docker deployment](/graphos/routing/self-hosted/containerization/docker): Deploy Apollo Runtime using Docker
+- [Kubernetes deployment](/graphos/routing/self-hosted/containerization/kubernetes/quickstart): Deploy Apollo Router using Helm

docs/source/routing/self-hosted/index.mdx

@@ -30,6 +30,12 @@
 
 </Note>
 
+<Note>
+
+If your organization uses a transparent or egress proxy (such as Zscaler or Netskope), [add your proxy's root CA certificate to your container image](/graphos/routing/self-hosted/containerization/proxy-certificates). Without it, the router can't establish TLS connections to Apollo Uplink, resulting in certificate validation errors or "invalid license" failures.
+
+</Note>
+
 ## Kubernetes
 
 ### Apollo GraphOS Operator