Configuration
Learn how to configure your router.
The router provides three different ways of customization:
Configure the router runtime: You can specify a
config.yaml
for convenience or pass environment variables. In both ways, you can configure the global behavior of the router. For a full reference of all available options see below or use your IDE of choice.Configure how your graph is served: This file can be provided as config option or is pulled automatically from the cdn. It contains information on how to resolve your federated schema. The engine uses the information to build a highly optimized query planner. For more information see
wgc router compose
to build the file locally for development orwgc router fetch
to download the latest production version.Customize the router programatically through Go modules. It is unlikely that we will provide every possible feature as an in-built functionality. For advanced use cases or more control, you can build Go modules and compile the Router in a few commands. If you are uncertain about if your use case should be implemented as a custom module, don't hesitate to open an issue. We might already have a plan for this or can assist you with the implementation.
Recommendation Create a config file and use environment variable expansion to avoid storing secrets on the file system.
Config file
For convenience, you can create a config.yaml
to specify all router options. Start the router in the same directory or pass the path to the file as a CONFIG_PATH
environment variable.
Values specified in the config file have precedence over Environment variables. This also includes empty values so only specify values that should be overwritten. That means, you can see the config file as a single source of truth.
Expand Environment Variables
You can expand environment variables in the file like this:
This will replace the value of the environment variable LOG_LEVEL
with the value of the key log_level
in your config file. For numeric values, ensure quotes are omitted.
Config Validation & Auto-completion
We know configuration is hard, especially for a software component like the router that can be customized entirely to your needs. In order to simplify this, we use JSON schema to validate the router configuration. This comes with huge benefits, all right at your fingertips:
Auto-completion
Documentation (Usage, Examples)
Detect deprecated fields
Detect typos or invalid values.
Some options require the router to validate them. This requires starting the router. Once your router has started successfully, you can be sure that your configuration is valid.
IDE Configuration
VsCode: Install the YAML extension in your IDE.
JetBrains: Support out of the box but in some circumstances it conflicts with other default mappings. Go to
Languages & Frameworks
->Schemas and DTDs
->JSON Schemas Mappings
configure the mapping yourself.
As the next step, add the following line to the head of your config.yaml
file. This line informs your IDE, to download the correct JSON schema file to validate the config file.
If you want to pin to a specific router version use the following URL:
Now, you should get auto-completion 🌟 .
Environment Variables
Many configuration options can be set as environment variables. For a complete list of options, please look at the Router config tables.
Router
The following sections describe each configuration in detail with all available options and their defaults.
Intervals, timeouts, and delays are specified in Go duration syntax e.g 1s, 5m or 1h.
Sizes can be specified in 2MB, 1mib.
Environment Variable | YAML | Required | Description | Default Value |
---|---|---|---|---|
LISTEN_ADDR | listen_addr | The server listener address. | localhost:3002 | |
CONTROLPLANE_URL | controlplane_url | The controlplane url. Not required when a static execution config is provided. | ||
PLAYGROUND_ENABLED | playground_enabled | Enables the GraphQL playground on ( | true | |
PLAYGROUND_PATH | playground_path | The path where the playground is served | "/" | |
INTROSPECTION_ENABLED | introspection_enabled | true | ||
QUERY_PLANS_ENABLED | query_plans_enabled | The Router can return Query plans as part of the response, which might be useful to understand the execution. | true | |
LOG_LEVEL | log_level | debug / info / warning / error / fatal / panic | info | |
JSON_LOG | json_log | Render the log output in JSON format (true) or human readable (false) | true | |
SHUTDOWN_DELAY | shutdown_delay | Maximum time in seconds the server has to shutdown gracefully. Should be higher than | 60s | |
GRACE_PERIOD | grace_period | Maximum time in seconds the server has between schema updates to gracefully clean up all resources. Should be smaller than | 30s | |
POLL_INTERVAL | poll_interval | The interval of how often the router should check for new schema updates | 10s | |
HEALTH_CHECK_PATH | health_check_path | Health check path. Returns | /health | |
READINESS_CHECK_PATH | readiness_check_path | Readiness check path. Return | /health/ready | |
LIVENESS_CHECK_PATH | liveness_check_path | Liveness check path. Return 200 when the router is alive | /health/live | |
GRAPHQL_PATH | graphql_path | The path where the GraphQL Handler is served | /graphql | |
PLAYGROUND_PATH | playground_path | The path where the playground is served | / | |
LOCALHOST_FALLBACK_INSIDE_DOCKER | localhost_fallback_inside_docker | Enable fallback for requests that fail to connect to localhost while running in Docker | true | |
DEV_MODE | dev_mode | Enables pretty log output and allows to use Advanced Request Tracing (ART) without further security protection. | false | |
INSTANCE_ID | If not specified, a new ID will be generated with each router start. A stable ID ensures that metrics with the same ID are grouped together and the same server can be identified on the platform. |
Example configuration:
Access Logs
For a detailed example, please refer to the Access Logs section.
Environment Variable | YAML | Required | Description | Default Value |
---|---|---|---|---|
access_logs | Enable the access logs. The access logs are used to log the incoming requests. By default, the access logs are enabled and logged to the standard output. | |||
ACCESS_LOGS_ENABLED | access_logs.enabled | Enable the access logs. The access logs are used to log the incoming requests. By default, the access logs are enabled and logged to the standard output. | true | |
access_logs.buffer | The buffer is used to buffer the logs before writing them to the output. | |||
ACCESS_LOGS_BUFFER_ENABLED | access_logs.buffer.enabled | Enable the buffer. | false | |
ACCESS_LOGS_BUFFER_SIZE | access_logs.buffer.size | The size of the buffer. The default value is 256KB. | ||
ACCESS_LOGS_FLUSH_INTERVAL | access_logs.buffer.flush_interval | The interval at which the buffer is flushed. The period is specified as a string with a number and a unit, e.g. 10ms, 1s, 1m, 1h. The supported units are 'ms', 's', 'm', 'h'. | ||
access_logs.output | The log destination. The supported destinations are stdout and file. Only one option can be enabled. The default destination is stdout. | |||
ACCESS_LOGS_OUTPUT_STDOUT_ENABLED | access_logs.output.stdout.enabled | true | ||
ACCESS_LOGS_OUTPUT_FILE_ENABLED | access_logs.output.file.enabled | false | ||
ACCESS_LOGS_FILE_OUTPUT_PATH | access_logs.output.file.path | The path to the log file. The path is used to specify the path to the log file. | ||
access_logs.fields | The fields to add to the logs. The fields are added to the logs as key-value pairs. | [] | ||
access_logs.fields.key | The key of the field to add to the logs. | |||
access_logs.fields.default | The default value of the field. If the value is not set, value_from is used. If both value and value_from are set, value_from has precedence and in case of a missing value_from, the default value is used. | |||
access_logs.value_from | Defines a source for the field value e.g. from a request header. If both default and value_from are set, value_from has precedence. | |||
access_logs.fields.value_from.request_header | The name of the request header from which to extract the value. The value is only extracted when a request context is available otherwise the default value is used. | |||
access_logs.fields.value_from.context_field | The field name of the context from which to extract the value. The value is only extracted when a context is available otherwise the default value is used. One of: [ "operation_name", "operation_type", "operation_service_names", "operation_hash", "persisted_operation_sha256", "operation_sha256", "response_error_message", "graphql_error_codes", "graphql_error_service_names", "operation_parsing_time", "operation_validation_time", "operation_planning_time", "operation_normalization_time" ] |
Example YAML config:
Telemetry
Graph
Overall configuration for the Graph that's configured for this Router.
Environment Variable | YAML | Required | Description | Default Value |
---|---|---|---|---|
GRAPH_API_TOKEN | token | The token permits the router to communicate with the controlplane and export telemetry. Created with |
Example YAML config:
TLS
The Router supports TLS and mTLS for secure communication with your clients and infrastructure components like load balancer.
Server TLS
Environment Variable | YAML | Required | Description | Default Value |
---|---|---|---|---|
TLS_SERVER_ENABLED | enabled | Enables server TLS support. | false | |
TLS_SERVER_CERT_FILE | cert_file | The path to the server certificate file. | ||
TLS_SERVER_KEY_FILE | key_file | The path to the server private key file. |
Example YAML config:
Client Authentication
Environment Variable | YAML | Required | Description | Default Value |
---|---|---|---|---|
TLS_CLIENT_AUTH_CERT_FILE | cert_file | Enables client authentication support. The file to the certificate file used to authenthicate clients. | "" | |
TLS_CLIENT_AUTH_REQUIRED | required | Enforces a valid client certificate to establish a connection. | false |
Example YAML config:
Compliance
The configuration for the compliance. Includes for example the configuration for the anonymization of the IP addresses.
IP Anonymization
Environment Variable | YAML | Required | Description | Default Value |
---|---|---|---|---|
SECURITY_ANONYMIZE_IP_ENABLED | enabled | Enables IP anonymization in traces and logs. | true | |
SECURITY_ANONYMIZE_IP_METHOD | method | The metod to anonymize IP addresses. Can be "hash" or "redact". | "redact" |
Example YAML config:
Cluster
Environment Variable | YAML | Required | Description | Default Value |
---|---|---|---|---|
CLUSTER_NAME | name | The logical name of the router cluster. The name is used for analytic purpose. |
Example YAML config:
Telemetry
Environment Variable | YAML | Required | Description | Default Value |
---|---|---|---|---|
TELEMETRY_SERVICE_NAME | service_name | cosmo-router | ||
resource_attributes | The resource attributes to add to OTEL metrics and traces. The resource attributes identify the entity producing the traces and metrics. | |||
resource_attributes.key | The key of the attribute. | |||
resource_attributes.value | The value of the attribute. | |||
attributes | The attributes to add to OTEL metrics and traces. Because Prometheus metrics rely on the OpenTelemetry metrics, the attributes are also added to the Prometheus metrics. | [] | ||
attributes.key | The key of the attribute. | |||
attributes.default | The value of the attribute. | |||
attributes.value_from | Defines a source for the attribute value e.g. from a request header. If both default and value_from are set, value_from has precedence. | |||
attributes.value_from.request_header | The name of the request header from which to extract the value. The value is only extracted when a request context is available otherwise the default value is used. Don't forget to add the header to your CORS settings. |
Example YAML config:
Tracing
Environment Variable | YAML | Required | Description | Default Value |
---|---|---|---|---|
TRACING_ENABLED | enabled | true | ||
TRACING_SAMPLING_RATE | sampling_rate | The sampling rate for the traces. The value must be between 0 and 1. If the value is 0, no traces will be sampled. If the value is 1, all traces will be sampled. | 1 | |
TRACING_PARENT_BASED_SAMPLER | parent_based_sampler | Enable the parent-based sampler. The parent-based sampler is used to sample the traces based on the parent trace. | true | |
TRACING_BATCH_TIMEOUT | The maximum delay allowed before spans are exported. | 10s | ||
TRACING_EXPORT_GRAPHQL_VARIABLES | export_graphql_variables | Export GraphQL variables as span attribute. Variables may contain sensitive data. | false | |
with_new_root | Starts the root span always at the router. | false |
Example YAML config:
Exporters
Environment Variable | YAML | Required | Description | Default Value |
---|---|---|---|---|
disabled | bool | |||
exporter | one of: http,grpc | |||
endpoint | ||||
path | ||||
headers |
Example YAML config:
Propagation
Environment Variable | YAML | Required | Description | Default Value |
---|---|---|---|---|
trace_context | true | |||
jaeger | ||||
b3 | ||||
baggage |
Example YAML config:
Metrics
OTLP
Environment Variable | YAML | Required | Description | Default Value |
---|---|---|---|---|
METRICS_OTLP_ENABLED | enabled | Enables OTEL metrics instrumentation | true | |
METRICS_OTLP_ROUTER_RUNTIME | router_runtime | true | ||
METRICS_OTLP_EXCLUDE_METRICS | exclude_metrics | The metrics to exclude from the OTEL metrics. Accepts a list of Go regular expressions. Use https://regex101.com/ to test your regular expressions. | [] | |
METRICS_OTLP_EXCLUDE_METRIC_LABELS | exclude_metric_labels | The metric labels to exclude from the OTEL metrics. Accepts a list of Go regular expressions. Use https://regex101.com/ to test your regular expressions. | [] |
Attributes
YAML | Required | Description | Default Value |
---|---|---|---|
attributes | The attributes to add to OTLP Metrics and Prometheus. | [] | |
attributes.key | The key of the field. | ||
attributes.default | The default value of the field. If the value is not set, value_from is used. If both value and value_from are set, value_from has precedence and in case of a missing value_from, the default value is used. | ||
attributes.value_from | Defines a source for the field value e.g. from a request header or request context. If both default and value_from are set, value_from has precedence. | ||
attributes.value_from | Defines a source for the field value e.g. from a request header or request context. If both default and value_from are set, value_from has precedence. | ||
attributes.value_from.request_header | The name of the request header from which to extract the value. The value is only extracted when a request context is available otherwise the default value is used. | ||
attributes.value_from.context_field | The field name of the context from which to extract the value. The value is only extracted when a context is available otherwise the default value is used. | One of: ["operation_service_names", "graphql_error_codes", "graphql_error_service_names", "operation_sha256"] |
Example YAML config:
Prometheus
Environment Variable | YAML | Required | Description | Default Value |
---|---|---|---|---|
PROMETHEUS_ENABLED | enabled | Enables prometheus metrics support | true | |
PROMETHEUS_HTTP_PATH | path | The HTTP path where metrics are exposed. | "/metrics" | |
PROMETHEUS_LISTEN_ADDR | listen_addr | The prometheus listener address | "127.0.0.1:8088" | |
PROMETHEUS_EXCLUDE_METRICS | exclude_metrics | |||
PROMETHEUS_EXCLUDE_METRIC_LABELS | exclude_metric_labels |
Example YAML config:
Exporter
YAML | Required | Description | Default Value |
---|---|---|---|
disabled | |||
exporter | one of: http,grpc | ||
endpoint | |||
path | The path to which the metrics are exported. This is ignored when using 'grpc' as exporter and can be omitted. | ||
headers | |||
temporality | Temporality defines the window that an aggregation is calculated over. one of: delta, cumulative |
Example YAML config:
GraphQL Metrics
Environment Variable | YAML | Required | Description | Default Value |
---|---|---|---|---|
GRAPHQL_METRICS_ENABLED | enabled | true | ||
GRAPHQL_METRICS_COLLECTOR_ENDPOINT | collector_endpoint | Default endpoint |
Example YAML config:
CORS
Environment Variable | YAML | Required | Description | Default Value |
---|---|---|---|---|
CORS_ENABLED | enabled | Set this to enable/disable the CORS middleware. It is enabled by default. When disabled, the rest of the properties for CORS have no effect. | true | |
CORS_ALLOW_ORIGINS | allow_origins | This is a list of origins which are allowed. You can provide origins with wildcards | * | |
CORS_ALLOW_METHODS | allow_methods | HEAD,GET,POST | ||
CORS_ALLOW_HEADERS | allow_headers | Origin,Content-Length,Content-Type | ||
CORS_ALLOW_CREDENTIALS | allow_credentials | true | ||
CORS_MAX_AGE | max_age | 5m |
Example YAML config:
Cache Control Policy
Configure your cache control policy. More information on this feature can be found here: #cache-control-policy
Environment Variable | YAML | Required | Description | Default Value |
---|---|---|---|---|
CACHE_CONTROL_POLICY_ENABLED | enabled | Set this to enable/disable the strict cache control policy. It is false by default | false | |
CACHE_CONTROL_POLICY_VALUE | value | The default value for the cache control policy. It will be applied to all requests, unless a subgraph has a more strict one |
Example YAML Config:
Custom Modules
Configure your custom Modules. More information on this feature can be found here: Custom Modules
Example YAML config:
Headers
Configure Header propagation rules for all Subgraphs or individual Subgraphs by name.
Global Header Rules
Apply to requests/responses to/from "all" Subgraphs. These will be applied globally in the graph
Environment Variable | YAML | Required | Description | Default Value |
---|---|---|---|---|
request | List of Request Header Rules | |||
response | List of Response Header Rules |
Example YAML config:
Request Header Rule
Apply to requests to specific Subgraphs.
Environment Variable | YAML | Required | Description | Default Value |
---|---|---|---|---|
op | oneof=propagate, set | |||
matching | matching is the regex to match the header name against | |||
named | named is the exact header name to match | |||
rename | renames the header's key to the provided value | |||
default | default is the default value to set if the header is not present | |||
name | If | |||
value | If |
Example YAML config:
Response Header Rule
These rules can be applied to all responses, as well as just to specific subgraphs, and used to manipulate and propagate response headers from subgraphs to the client. By configuring the rule, users can define how headers should be handled when multiple subgraphs provide conflicting values for a specific header.
Environment Variable | YAML | Required | Description | Default Value |
---|---|---|---|---|
op | oneof=propagate | |||
algorithm | oneof=first_write, last_write, append | |||
matching | matching is the regex to match the header name against. This | |||
named | named is the exact header name to match | |||
default | default is the default value to set if the header is not present | |||
rename | renames the header's key to the provided value |
Example YAML config:
Storage Providers
The configuration for the storage providers. Storage providers can be used to store the persisted operations and the execution config.
Example YAML config:
Storage Provider Yaml Options
These rules apply to requests being made from the Router to all Subgraphs.
Environment Variable | YAML | Required | Description | Default Value |
---|---|---|---|---|
cdn | CDN storage provider. | |||
cdn.id | Unique ID of the provider. It is used as reference in | |||
cdn.url | "https://cosmo-cdn.wundergraph.com" | |||
redis | Redis storage provider | |||
redis.id | Unique ID of the provider. It is used as a reference in the | |||
redis.url | Redis url, containing port and auth information if necessary | |||
s3 | S3 storage provider | |||
s3.id | Unique ID of the privider. It is used as reference in | |||
s3.endpoint | The endpoint of the S3 bucket. The endpoint is used to specify the endpoint of the S3 bucket. | |||
s3.bucket | The name of the S3 bucket. The S3 bucket is used to store the execution config. | |||
s3.access_key | The access key of the S3 bucket. The access key ID is used to authenticate with the S3 bucket. | |||
s3.secret_key | The secret key of the S3 bucket. The secret access key is used to authenticate with the S3 bucket. | |||
s3.region | The region of the S3 bucket. The region is used to specify the region of the S3 bucket | |||
s3.secure | Enables https in the provided endpoint. Must be set to | true | ||
Persisted Operations
The configuration for the persisted operations allows you to maintain a fixed set of GraphQL operations that can be queried against the router without exposing your entire graph to the public. This approach enhances security and performance.
Example YAML config:
Persisted Operations Configuration Options
These rules apply to requests being made from the Router to all Subgraphs.
Environment Variable | YAML | Required | Description | Default Value |
---|---|---|---|---|
persisted_operations | The configuration for the persisted operations. | |||
persisted_operations.cache | LRU cache for persisted operations. | |||
PERSISTED_OPERATIONS_CACHE_SIZE | persisted_operations.cache.size | The size of the cache in SI unit. | "100MB" | |
persisted_operations.storage | The storage provider for persisted operation. Only one provider can be active. When no provider is specified, the router will fallback to the Cosmo CDN provider to download the persisted operations. | |||
PERSISTED_OPERATIONS_STORAGE_PROVIDER_ID | persisted_operations.storage.provider_id | The ID of the storage provider. The ID must match the ID of the storage provider in the | ||
PERSISTED_OPERATIONS_STORAGE_OBJECT_PREFIX | persisted_operations.storage.object_prefix | The prefix of the object in the storage provider location. The prefix is put in front of the operation SHA256 hash. $prefix/SHA256.json |
Automatic Persisted Queries
The configuration for automatic persisted queries allows you to enable automated caching of select GraphQL operations that can be queried against the router, using both POST and GET requests. This approach enhances performance.
It defaults to using a local cache (with the size defined in cache.size
), but users can optionally use a Redis storage
Example YAML config:
Configuration Options
These rules apply to requests being made from the Router to all Subgraphs.
Environment Variable | YAML | Required | Description | Default Value |
---|---|---|---|---|
automatic_persisted_queries | The configuration for the persisted operations. | |||
automatic_persisted_queries.enabled | Whether or not automatic persisted queries is enabled | True | ||
automatic_persisted_queries.cache | LRU cache for persisted operations. | |||
automatic_persisted_queries.cache.size | The size of the cache in SI unit. | "100MB" | ||
automatic_persisted_queries.cache.ttl | The TTL of the cache, in seconds. Set to 0 to set no TTL | |||
automatic_persisted_queries.storage | The external storage provider (redis) for automatic persisted operation. Only one provider can be active. When no provider is specified, the router will fallback to using a local in-memory cache (configured in the | |||
automatic_persisted_queries.storage.provider_id | The ID of the Redis storage provider. The ID must match the ID of the storage provider in the | |||
automatic_persisted_queries.storage.object_prefix | The prefix of the object in the storage provider location. The prefix is put in front of the operation SHA256 hash. $prefix/SHA256 |
Execution Config
The configuration for the execution setup contains instructions for the router to plan and execute your GraphQL operations. You can specify the storage provider from which the configuration should be fetched.
Example YAML config:
Subgraph Request Rules
These rules apply to requests being made from the Router to all Subgraphs.
Environment Variable | YAML | Required | Description | Default Value |
---|---|---|---|---|
execution_config | The configuration for the execution config. | |||
file | The configuration for the execution config file. The config file is used to load the execution config from the local file system. The file has precedence over the storage provider. | |||
EXECUTION_CONFIG_FILE_PATH | file.path | The path to the execution config file. The path is used to load the execution config from the local file system. | ||
EXECUTION_CONFIG_FILE_WATCH | file.watch | Enable the watch mode. The watch mode is used to watch the execution config file for changes. If the file changes, the router will reload the execution config without downtime. | "true" | |
execution_config.storage | The storage provider for the execution config. Only one provider can be active. When no provider is specified, the router will fallback to the Cosmo CDN provider to download the execution config. | |||
EXECUTION_CONFIG_STORAGE_PROVIDER_ID | execution_config.storage.provider_id | The ID of the storage provider. The ID must match the ID of the storage provider in the | ||
EXECUTION_CONFIG_STORAGE_OBJECT_PATH | execution_config.storage.object_path | The path to the execution config in the storage provider. The path is used to download the execution config from the S3 bucket. | ||
EXECUTION_CONFIG_FALLBACK_STORAGE_ENABLED | execution_config.fallback_storage.enabled | Enable a fallback storage to fetch the execution config in case the above primary source fails. | ||
EXECUTION_CONFIG_FALLBACK_STORAGE_PROVIDER_ID | execution_config.fallback_storage.provider_id | The ID of the storage provider. The ID must match the ID of the storage provider in the | ||
EXECUTION_CONFIG_FALLBACK_STORAGE_OBJECT_PATH | execution_config.fallback_storage.object_path | The path to the execution config in the storage provider. The path is used to download the execution config from the S3 bucket. |
Traffic Shaping
Configure rules for traffic shaping like maximum request body size, timeouts, retry behavior, etc. For more info, check this section in the docs: Traffic shaping