diff --git a/.changesets/docs_proxy_certificates.md b/.changesets/docs_proxy_certificates.md new file mode 100644 index 0000000000..50da500d79 --- /dev/null +++ b/.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 diff --git a/docs/source/routing/self-hosted/containerization/aws.mdx b/docs/source/routing/self-hosted/containerization/aws.mdx index 8164a3e2a4..215eed4439 100644 --- a/docs/source/routing/self-hosted/containerization/aws.mdx +++ b/docs/source/routing/self-hosted/containerization/aws.mdx @@ -11,6 +11,12 @@ You will: - Set up an Elastic Cloud Registry and push your router image to it. - Create an ECS task definition for your router and deploy it. + + +If your organization uses a corporate proxy with TLS inspection, [add your proxy's root certificate to the container](proxy-certificates). + + + ## Prerequisites Before you start: diff --git a/docs/source/routing/self-hosted/containerization/azure.mdx b/docs/source/routing/self-hosted/containerization/azure.mdx index 97aba854c2..08ab160885 100644 --- a/docs/source/routing/self-hosted/containerization/azure.mdx +++ b/docs/source/routing/self-hosted/containerization/azure.mdx @@ -11,6 +11,12 @@ You will: - Set up an Azure Container Registry and push your router image to it. - Create and deploy an Azure Container App for your router. + + +If your organization uses a corporate proxy with TLS inspection, [add your proxy's root certificate to the container](proxy-certificates). + + + ## Prerequisites Before you start: diff --git a/docs/source/routing/self-hosted/containerization/docker-router-only.mdx b/docs/source/routing/self-hosted/containerization/docker-router-only.mdx index 625ab691f3..f1ebfa4933 100644 --- a/docs/source/routing/self-hosted/containerization/docker-router-only.mdx +++ b/docs/source/routing/self-hosted/containerization/docker-router-only.mdx @@ -22,6 +22,12 @@ The exact image version to use depends on which release you wish to use. In the This container image only contains the router. Apollo recommends using the [Apollo Runtime container](docker.mdx), which contains all Apollo runtime services. + + +If your organization uses a corporate proxy with TLS inspection, [add your proxy's root certificate to the container](proxy-certificates). + + + ## 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 @@ Usage: build_docker_image.sh [-b [-r ]] [-d] [] 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. diff --git a/docs/source/routing/self-hosted/containerization/docker.mdx b/docs/source/routing/self-hosted/containerization/docker.mdx index cb8136d3d2..ba9b6797b2 100644 --- a/docs/source/routing/self-hosted/containerization/docker.mdx +++ b/docs/source/routing/self-hosted/containerization/docker.mdx @@ -28,6 +28,12 @@ Before you start: + + +If your organization uses a corporate proxy with TLS inspection, [add your proxy's root certificate to the container](proxy-certificates). + + + ## Quick start Run the following command, replacing the `APOLLO_GRAPH_REF` and `APOLLO_KEY` values with your own. diff --git a/docs/source/routing/self-hosted/containerization/gcp.mdx b/docs/source/routing/self-hosted/containerization/gcp.mdx index 6236080198..af53b508d0 100644 --- a/docs/source/routing/self-hosted/containerization/gcp.mdx +++ b/docs/source/routing/self-hosted/containerization/gcp.mdx @@ -11,6 +11,12 @@ You will: - Set up a container registry and push your router image to it. - Create a Cloud Run service and configure it to deploy your router. + + +If your organization uses a corporate proxy with TLS inspection, [add your proxy's root certificate to the container](proxy-certificates). + + + ## Prerequisites Before you start: diff --git a/docs/source/routing/self-hosted/containerization/index.mdx b/docs/source/routing/self-hosted/containerization/index.mdx index fd4ad5125f..faee373a7c 100644 --- a/docs/source/routing/self-hosted/containerization/index.mdx +++ b/docs/source/routing/self-hosted/containerization/index.mdx @@ -29,3 +29,7 @@ This image is recommended only for Kubernetes-based deployments, and is used by - [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 diff --git a/docs/source/routing/self-hosted/containerization/kubernetes/quickstart.mdx b/docs/source/routing/self-hosted/containerization/kubernetes/quickstart.mdx index a6c7afe2ef..32f2bee2fb 100644 --- a/docs/source/routing/self-hosted/containerization/kubernetes/quickstart.mdx +++ b/docs/source/routing/self-hosted/containerization/kubernetes/quickstart.mdx @@ -27,6 +27,12 @@ For more details, see the [Operator workflow patterns](/apollo-operator/workflow + + +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). + + + 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: diff --git a/docs/source/routing/self-hosted/containerization/proxy-certificates.mdx b/docs/source/routing/self-hosted/containerization/proxy-certificates.mdx new file mode 100644 index 0000000000..2df56f7125 --- /dev/null +++ b/docs/source/routing/self-hosted/containerization/proxy-certificates.mdx @@ -0,0 +1,145 @@ +--- +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. + + + +## 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="" \ + --env APOLLO_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: \ + -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: + +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="" \ + --env APOLLO_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" + router: + 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: + 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" +router: + image: + repository: your-registry/router-with-proxy-cert + 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 diff --git a/docs/source/routing/self-hosted/index.mdx b/docs/source/routing/self-hosted/index.mdx index 67e0c1f2da..c75673ca2f 100644 --- a/docs/source/routing/self-hosted/index.mdx +++ b/docs/source/routing/self-hosted/index.mdx @@ -30,6 +30,12 @@ For a more detailed look at production deployment workflows for the full supergr + + +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. + + + ## Kubernetes ### Apollo GraphOS Operator