Deployment
Learn how to deploy and start the Router in Production.
Run the Router
The router is a Go application provided as a self-contained Docker container. You can initiate the router by executing a single Docker command:
You can generate a token with the wgc router token create
CLI command.
Health checks
By default, the health check endpoint is exposed at the path /health
. The health check reports if the router is alive.
Kubernetes
If you are on Kubernetes you can make use of our liveness and readiness checks. For convenience, we export both on /health/live
and /health/ready
:
The liveness route returns 200
when the router is up. The readiness handler returns 200
only when the router is ready to serve requests.
Graceful shutdown
Before a Pod is terminated, a SIGTERM signal is sent to the Pod. Afterward, the Pod has 30 seconds to terminate itself (see terminationGracePeriodSeconds). Ensure that the router-specific timeouts are set below this threshold or increase the termination period appropriately.
For example, the following configuration was tested and could serve as a good starting point:
Router
-
GRACE_PERIOD_SECONDS=20
-
SHUTDOWN_DELAY_SECONDS=30
Pod
terminationGracePeriodSeconds=60
With that configuration, your router has 30 seconds to respond to all active connections before forcefully shutting down the server. Kubernetes will not terminate the container until the termination period of 60 seconds is over. Because the readiness endpoint no longer responds 200
and the container is inTERMINATION
state any new traffic from being redirected to the instance is prevented.
GRACE_PERIOD_SECONDS
becomes interesting when the router updates its schema. This is also the time the server has to gracefully shut down old clients before the switch is enforced.
For more information, we recommend the Kubernetes Best Practice Terminating With Grace article.
Kubernetes & Container environments
To make the application reachable within the container network, you need to expose the router on 0.0.0.0
e.g LISTEN_ADDR=0.0.0.0:3002.
This is also required when trying to access Prometheus metrics from outside the docker network. Use PROMETHEUS_LISTEN_ADDR="0.0.0.0:8088"
to make the endpoint accessible.
Logging
Structured logging, also known as JSON logging, is enabled by default and can be controlled using the JSON_LOG
environment variable. For development, we recommend setting this off because the logs are more friendly rendered.
Observability & Operations
The router exposes useful metrics about the process and memory. All metrics can be scraped from the Prometheus metrics endpoint. For more information please visit the dedicated Metrics section.
Tracing Sampling Rate
In scenarios with low traffic, a sampling rate of 1 (100%) is acceptable. However, for high-volume situations, we strongly recommend using a lower sampling rate. For instance, in a project experiencing 60 requests per second, a sampling rate of 0.1 (10% 6 req/s) is sufficient to generate valuable insights.
If you export to Cosmo Cloud, which is enabled by default, a sampling rate based on your subscription will be enforced. If your configured rate exceeds your account limit, a warning will be displayed. Please consider upgrading your plan or contact us for custom limits.
Ensure that your subgraphs use parent-based sampling to inherit the sampling rate. For more information see OTEL instrumentation on Subgraphs.
Configuration recommendations
Advanced Request Tracing(ART) is enabled by default; however, it will only be accessible if you have set DEV_MODE=true
or GRAPH_API_TOKEN
. In the latter case, we will exchange a public key from the control plane to ensure that only authorized requests from the Studio can access ART requests. This enables safe debugging of your router in production.
Therefore DEV_MODE=true
should NOT be set when deploying your router to production.
Recommended resources
The specific resource recommendations depend on your constraints, but we have observed that low to medium-traffic projects benefit from the following setup:
-
3 instances for high availability.
-
Each instance is equipped with 2 CPUs and 1GB of RAM.
Thanks to the utilization of Go and internal optimizations, the router demonstrates strong vertical scalability in relation to CPU and memory.
Custom Config
In Docker and Kubernetes, you can mount configuration files. In that way, you don’t have to build a custom Docker image. By default, the router looks for a config at the location where it starts. This location is /config.yaml
in our official Docker image. You can overwrite the path by setting the CONFIG_PATH
environment variable.
Docker
Here we mount the router config from the host system. Take a closer look at -v
flag.
Kubernetes
In Kubernetes, we have the concepts of volumes and volumeMounts to realize the same behavior as in Docker. Below is a configuration example for the volume only.
Custom Image
In some scenarios, you have to provide a custom Dockerfile, e.g., when you need to build your custom Router binary. Here is an example of how the Dockerfile can look.
If you are wondering about the BUILDPLATFORM
, TARGETOS
, TARGETARCH
arguments, those are needed when building multi-arch images. You can remove them if you don’t need them.