Router Configuration - WunderGraph

The router provides three different ways of customization:

Configure the router runtime: You can specify a 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 to build the file locally for development or 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.

version: "1"

graph:
  token: "${GRAPH_API_TOKEN}"

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:

version: "1"

log_level: "${LOG_LEVEL}"

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.yamlfile. This line informs your IDE, to download the correct JSON schema file to validate the config file.

# yaml-language-server: $schema=https://raw.githubusercontent.com/wundergraph/cosmo/main/router/pkg/config/config.schema.json

version: "1"

If you want to pin to a specific router version use the following URL:

# yaml-language-server: $schema=https://raw.githubusercontent.com/wundergraph/cosmo/router%400.67.0/router/pkg/config/config.schema.json

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	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.	https://cosmo-cp.wundergraph.com
PLAYGROUND_ENABLED	playground_enabled	Enables the GraphQL playground on (`$LISTEN_ADDR/`)	true
PLAYGROUND_PATH	playground_path	The path where the playground is served	”/“
INTROSPECTION_ENABLED	introspection_enabled	Enables the GraphQL introspection	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	The log level to use.	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 `GRACE_PERIOD`	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 `SHUTDOWN_DELAY`	30s
POLL_INTERVAL	poll_interval	The interval of how often the router should check for new schema updates	10s
POLL_JITTER	poll_jitter	The maximum delay added to the poll interval to mitigate thundering herd issues in router fleets scenarios.	5s
HEALTH_CHECK_PATH	health_check_path	Health check path. Returns `200` when the router is alive	/health
READINESS_CHECK_PATH	readiness_check_path	Readiness check path. Return `200` when the router is ready to accept traffic, otherwise `503`	/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	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.
DEMO_MODE	demo_mode	Launch the router in demo mode. If no execution config is found, the router will start with a demo execution config and deploy a demo federated graph that can be used for testing purposes.

Example configuration:

version: "1"

log_level: "info"
listen_addr: "localhost:3002"
controlplane_url: "https://cosmo-cp.wundergraph.com"
playground_enabled: true
playground_path: "/"
introspection_enabled: true
json_log: true
shutdown_delay: 15s
grace_period: 20s
poll_interval: 10s
health_check_path: "/health"
readiness_check_path: "/health/ready"
liveness_check_path: "/health/live"
router_config_path: ""

Config watcher hot reloading

The router is capable of reloading itself using an updated config without a full process restart. You can trigger a reload in one of two ways:

Sending a SIGHUP signal to the router process.
Configuring the watch_config section to automatically check the configuration for changes at regular intervals.

config.yaml

watch_config:
  enabled: true
  interval: "10s"

  startup_delay:
    enabled: false
    maximum: "10s"

`watch_config` options

Environment Variable	YAML	Description	Default Value
WATCH_CONFIG_ENABLED	watch_config.enabled	Enable automatic configuration reloading at regular intervals.	false
WATCH_CONFIG_INTERVAL	watch_config.interval	The interval at which the router checks for configuration changes.	10s
WATCH_CONFIG_STARTUP_DELAY_ENABLED	watch_config.startup_delay.enabled	Enable a random delay before the first configuration check to avoid thundering herd problems in clusters.	false
WATCH_CONFIG_STARTUP_DELAY_MAXIMUM	watch_config.startup_delay.maximum	The maximum random delay before the first configuration check.	10s

Hot reloading has some limitations:

Changes to the watch_config section are not hot-reloaded.
Changes to flags and environment variables are not possible.
watch_config based reloads are based on the filesystem’s modification time, edits that somehow circumvent this mechanism will not trigger a reload.

Access Logs

For a detailed example, please refer to the Access Logs section.

Environment Variable	YAML	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.router	The configuration for access logs for the router.
	access_logs.router.fields	The fields to add to the access logs for router. The fields are added to the logs as key-value pairs.	[]
	access_logs.router.fields.key	The key of the field to add to the logs.
	access_logs.router.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.router.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.router.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.router.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” ]
	access_logs.subgraphs	The subgraph access logs configuration
	access_logs.subgraphs.enabled	Enable the subgraphs access logs.	false
	access_logs.subgraphs.fields	The fields to add to the logs when printing subgraph access logs. The fields are added to the logs as key-value pairs.
	access_logs.subgraphs.fields.key	The key of the field to add to the logs.
	access_logs.subgraphs.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.subgraphs.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.subgraphs.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.subgraphs.value_from.response_header	The name of the response 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.subgraphs.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”, “operation_parsing_time”, “operation_validation_time”, “operation_planning_time”, “operation_normalization_time” ]

Example YAML config:

version: "1"

access_logs:
  enabled: true
  buffer:
    enabled: false
    size: 256KB
    flush_interval: 10s
  output:
    file:
      enabled: true
      path: "access.log"
  router:
    fields:
      - key: "service"
        value_from:
          request_header: "x-service"
      - key: "operationName"
        value_from:
          context_field: operation_name
  subgraphs:
    fields:
      - key: "service"
        value_from:
          request_header: "x-service"
      - key: "response-service"
        value_from:
          response_header: "x-response-service"
      - key: "operationName"
        value_from:
          context_field: operation_name

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 . (Can be empty when providing a static router configuration through `ROUTER_CONFIG_PATH`but will disable the default telemetry stack)

Example YAML config:

version: "1"

graph:
  token: "<your-graph-token>"

MCP (Model Context Protocol)

The Model Context Protocol (MCP) server allows AI models to discover and interact with your GraphQL API in a secure way.

Environment Variable	YAML	Description	Default Value
MCP_ENABLED	mcp.enabled	Enable or disable the MCP server	false
MCP_SERVER_LISTEN_ADDR	mcp.server.listen_addr	The address and port where the MCP server will listen for requests	localhost:5025
MCP_SERVER_BASE_URL	mcp.server.base_url	The base URL of the MCP server. This is the URL advertised to the LLM clients when SSE is used as primary transport.	-
MCP_ROUTER_URL	mcp.router_url	Custom URL to use for the router GraphQL endpoint in MCP. Use this when your router is behind a proxy. Purely metadata for AI model.	-
MCP_STORAGE_PROVIDER_ID	mcp.storage.provider_id	The ID of a storage provider to use for loading GraphQL operations. Only file_system providers are supported.	-
MCP_GRAPH_NAME	mcp.graph_name	The name of the graph to be used by the MCP server	mygraph
MCP_EXCLUDE_MUTATIONS	mcp.exclude_mutations	Whether to exclude mutation operations from being exposed	false
MCP_ENABLE_ARBITRARY_OPERATIONS	mcp.enable_arbitrary_operations	Whether to allow arbitrary GraphQL operations to be executed. Security risk: Should only be enabled in secure, internal environments.	false
MCP_EXPOSE_SCHEMA	mcp.expose_schema	Whether to expose the full GraphQL schema. Security risk: Should only be enabled in secure, internal environments.	false

Example YAML config:

version: "1"

mcp:
  enabled: true
  server:
    listen_addr: "localhost:5025"
  router_url: "https://your-public-router-url.example.com/graphql" # Optional: Use when router is behind a proxy. Purely metadata for the AI model.
  storage:
    provider_id: "mcp" # References a file_system provider defined below
  graph_name: "my-graph"
  exclude_mutations: true
  enable_arbitrary_operations: false
  expose_schema: false

# Configure storage providers
storage_providers:
  file_system:
    - id: "mcp"
      path: "operations" # Relative to the router binary

For more details on how to use the MCP server, see the MCP Integration documentation.

TLS

The Router supports TLS and mTLS for secure communication with your clients and infrastructure components like load balancer.

Server TLS

Environment Variable	YAML	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:

version: "1"

tls:
  server:
    enabled: true
    key_file: ../your/key.pem
    cert_file: ../your/cert.pem

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:

version: "1"

tls:
  server:
    enabled: true # Required for client_auth
    key_file: ../your/key.pem
    cert_file: ../your/cert.pem
    client_auth:
      required: true
      cert_file: ../your/cert.pem

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:

version: "1"

compliance:
  anonymize_ip:
    enabled: true
    method: redact # hash or redact

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:

version: "1"

# See "https://cosmo-docs.wundergraph.com/studio/cluster-management" for more information
cluster:
  name: "us-central1-cosmo-cloud "

Telemetry

Environment Variable	YAML	Description	Default Value
TELEMETRY_SERVICE_NAME	service_name	The name of the service.	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:

version: "1"

# Only needed when setting attributes based on a request header
cors:
  allow_headers:
    - "x-service"

# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:
  # Common options
  service_name: "cosmo-router"
  resource_attributes:
    - key: env
      value: "prod"
  attributes:
    - key: service
      default: "static"
      value_from:
        request_header: "x-service"

Tracing

Environment Variable	YAML	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. For managed plans, the trace sampling rate will not exceed the rate imposed by the organization limit of the plan.	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	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:

version: "1"

# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:
  # Common options
  service_name: "cosmo-router"
  # uses https://cosmo-otel.wundergraph.com for tracing and metrics

  # OpenTelemetry Tracing
  tracing:
    enabled: true
    sampling_rate: 1
    batch_timeout: "10s"
    export_graphql_variables: false
    with_new_root: false

Exporters

Environment Variable	YAML	Required	Description	Default Value
	diabled		bool
	exporter		one of: http,grpc
	endpoint
	path
	headers

Example YAML config:

version: "1"

# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:
  tracing:
    enabled: true
    exporters:
      # If no exporters are defined, the default one is used
      - exporter: http # or grpc
        disabled: false
        endpoint: https://my-otel-collector.example.com
        # headers: {Authorization: Bearer <my-token>}
        batch_timeout: 10s
        export_timeout: 30s

Propagation

YAML	Description	Default Value
trace_context		true
jaeger
b3
baggage
datadog	Enable Datadog trace propagation	false

Example YAML config:

version: "1"

# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:
  # OpenTelemetry Tracing
  tracing:
    propagation:
      # https://www.w3.org/TR/trace-context/
      trace_context: true
      # https://www.w3.org/TR/baggage/
      baggage: false
      # https://www.jaegertracing.io/ (compliant with opentracing)
      jaeger: false
      # https://github.com/openzipkin/b3-propagation (zipkin)
      b3: false
      # https://docs.datadoghq.com/tracing/trace_collection/trace_context_propagation/?tab=java#datadog-format
      datadog: false

Metrics

OTLP

Environment Variable	YAML	Description	Default Value
METRICS_OTLP_ENABLED	enabled	Enables OTEL metrics instrumentation	true
METRICS_OTLP_ROUTER_RUNTIME	router_runtime	Enable the collection of metrics for the router runtime.	true
METRICS_OTLP_GRAPHQL_CACHE	graphql_cache	Enable the collection of metrics for the GraphQL operation router caches.	false
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	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.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:

# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:
  metrics:
    otlp:
      enabled: true
      router_runtime: true
      graphql_cache: true
      exclude_metrics: []
      exclude_metric_labels: []
    attributes:
      - key: "x-new-attribute"
        default: "foo"
        value_from:
          request_header: "X-Request-ID"

      - key: "error_codes"
        value_from:
          context_field: graphql_error_codes

Prometheus

Environment Variable	YAML	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 address to listen on for the prometheus metrics endpoint.	”127.0.0.1:8088”
PROMETHEUS_GRAPHQL_CACHE	graphql_cache	Enable the collection of metrics for the GraphQL operation router caches.	false
PROMETHEUS_EXCLUDE_METRICS	exclude_metrics
PROMETHEUS_EXCLUDE_METRIC_LABELS	exclude_metric_labels
PROMETHEUS_EXCLUDE_SCOPE_INFO	exclude_scope_info	Exclude scope info from Prometheus metrics.	false

Example YAML config:

version: "1"

# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:
  metrics:
    # Expose OpenTelemetry metrics for scraping
    prometheus:
      enabled: true
      path: "/metrics"
      listen_addr: "127.0.0.1:8088"
      graphql_cache: true
      exclude_metrics: []
      exclude_metric_labels: []
      exclude_scope_info: false

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:

version: "1"

# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:
  # Common options
  service_name: "cosmo-router"
  # uses https://cosmo-otel.wundergraph.com for tracing and metrics

  # OpenTelemetry Metrics
  metrics:
    otlp:
      enabled: true
      # If no exporters are defined, the default one is used
      exporters:
        - exporter: http # or grpc
          disabled: false
          endpoint: https://my-otel-collector.example.com
          temporality: delta # or cumulative
          # headers: {Authorization: Bearer <my-token>}

    # Expose OpenTelemetry metrics for scraping
    prometheus:
      enabled: true
      path: "/metrics"
      listen_addr: "127.0.0.1:8088"
      exclude_metrics: []
      exclude_metric_labels: []

GraphQL Metrics

Environment Variable	YAML	Required	Description	Default Value
GRAPHQL_METRICS_ENABLED	enabled			true
GRAPHQL_METRICS_COLLECTOR_ENDPOINT	collector_endpoint		Default endpoint	https://cosmo-metrics.wundergraph.com

Example YAML config:

version: "1"

graphql_metrics:
  enabled: true
  collector_endpoint: "https://cosmo-metrics.wundergraph.com"

CORS

Environment Variable	YAML	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:

version: "1"

cors:
  allow_origins: ["*"]
  allow_methods:
    - HEAD
    - GET
    - POST
  allow_headers:
    - Origin
    - Content-Length
    - Content-Type
  allow_credentials: true
  max_age: 5m

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:

version: "1"

cache_control_policy:
  enabled: true
  value: "max-age=180, public"
  subgraphs:
    - name: "products"
      value: "max-age=60, public"
    - name: "pricing"
      value: "no-cache"

Custom Modules

Configure your custom Modules. More information on this feature can be found here: Custom Modules

Example YAML config:

version: "1"

modules:
  myModule:
    # Arbitrary values, unmarshalled by the module
    value: 1

gRPC Plugins

The configuration for the router gRPC plugins. To learn more about the gRPC plugins, see the gRPC plugins documentation.

Environment Variable	YAML	Required	Description	Default Value
PLUGINS_ENABLED	enabled		Enable the router plugins. If the value is true, the router plugins are enabled.	false
PLUGINS_PATH	path		The path to the plugins directory. The plugins directory is used to load the plugins.	plugins

Example YAML config:

config.yaml

version: "1"

plugins:
  enabled: true
  path: "plugins"

Headers

Configure Header propagation rules for all Subgraphs or individual Subgraphs by name. When Cookieis a propagated header, you may want to filter the keys that are forwarded to the subgraph from the client, you can do this via the cookie_whitelistoption, which is a list of string cookie keys that will not be discarded. An empty value means allow all. If you’d like to block all cookies, disable the header propagation entirely.

The cookie whitelist can also affect custom modules that read request cookies, even if propagation is disabled for the Cookie header. This is because the whitelisting happens very early in the request lifecycle, before it reaches subgraphs or custom modules.

Example YAML config:

version: "1"

# Header manipulation
# See "https://cosmo-docs.wundergraph.com/router/proxy-capabilities" for more info
headers:
  cookie_whitelist:
   - "authorization"
   - "my-cookie-key"
  all:
    request:
      - op: "propagate"
        named: Cookie

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:

version: "1"

# Header manipulation
# See "https://cosmo-docs.wundergraph.com/router/proxy-capabilities" for more info
headers:
  all: # Header rules for all origin requests.
    request:
      - op: "propagate"
        named: X-Test-Header
      - op: "propagate"
        matching: (?i)^x-deprecated-.*
      - op: "set"
        name: "X-API-Key"
        value: "my-secret-value"
    response:
      - op: "propagate"
        algorithm: "append"
        named: "X-Custom-Header"

Header Rule Example Using Template Expression:

This example sets the X-User-ID header based on the sub claim from the JWT token, if the user is authenticated. Learn more about template expressions.

version: "1"

headers:
  all:
    request:
      - op: "set"
        name: "X-User-ID"
        # Sets the header only if the user is authenticated
        expression: "request.auth.isAuthenticated ? request.auth.claims.sub : ''"

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 `op` is `set`, `name` is the name of the desired header to set
	value		If `op` is `set`, `value` is the value of the desired header to set
	expression		If `op` is `set`, `expression` is the expression to evaluate to get the value of the desired header to set

Example YAML config:

version: "1"

# Header manipulation
# See "https://cosmo-docs.wundergraph.com/router/proxy-capabilities" for more information
headers:
  subgraphs:
    product: # Header rules for the "product" Subgraph
      request:
        - op: "propagate"
          named: X-Test-Header
        - op: "set"
          name: "X-API-Key"
          value: "my-secret-value"

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, set
	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:

version: "1"

# Header manipulation
# See "https://cosmo-docs.wundergraph.com/router/proxy-capabilities" for more information
headers:
  subgraphs:
    product: # Header rules for the "product" Subgraph
      response:
        - op: "propagate"
          algorithm: "append"
          named: "X-Test-Header"
        - op: "propagate"
          algorithm: "last_write"
          named: "X-Test2-Header"
        - op: "set"
          name: "X-User-Key"
          value: "my-user-value"

Storage Providers

Storage providers allow you to configure different backends for persisted operations, router execution config and MCP operations.

Example YAML config:

version: "1"

storage_providers:
  s3:
    - id: "s3-provider"
      endpoint: "s3.amazonaws.com"
      access_key: "${AWS_ACCESS_KEY_ID}"
      secret_key: "${AWS_SECRET_ACCESS_KEY}"
      bucket: "my-bucket"
      region: "us-east-1"
      secure: true
  redis:
    - id: "redis-provider"
      urls:
        - "redis://localhost:6379"
      cluster_enabled: false
  file_system:
    - id: "fs-provider"
      path: "/path/to/files"
  cdn:
    - id: "cdn-provider"
      url: "https://cosmo-cdn.wundergraph.com"

Storage Provider Types

File System Storage Provider

This provider allows you to load files from the local file system. This is particularly useful for the MCP server to load GraphQL operations.

Environment Variable	YAML	Required	Description	Default Value
STORAGE_PROVIDER_FS_ID	id		The ID of the provider to reference in other configurations
STORAGE_PROVIDER_FS_PATH	path		The path on the file system where files should be loaded from

The file system storage provider is currently only supported by the MCP feature. It cannot be used for persisted operations or execution configurations.

Redis Storage Provider

Used for distributed caching like automatic persisted queries.

Environment Variable	YAML	Description	Default Value
STORAGE_PROVIDER_REDIS_ID	id	The ID of the provider to reference in other configurations
STORAGE_PROVIDER_REDIS_URLS	urls	List of Redis URLs to connect to. If cluster_enabled is true, these are the seeds to discover the cluster
STORAGE_PROVIDER_REDIS_CLUSTER_ENABLED	cluster_enabled	Whether to use the Redis Cluster client	false

S3 Storage Provider

For storing operations and configs in S3-compatible storage.

YAML	Description	Default Value
id	The ID of the provider to reference in other configurations
endpoint	The endpoint of the S3 service
access_key	The access key for the S3 service
secret_key	The secret key for the S3 service
bucket	The bucket where objects will be stored
region	The region of the S3 bucket
secure	Whether to use HTTPS for S3 connections	true

CDN Provider

For connecting to the Cosmo CDN.

Environment Variable	YAML	Required	Description	Default Value
	id		The ID of the provider to reference in other configurations
	url		The URL of the CDN	https://cosmo-cdn.wundergraph.com

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:

version: "1"

persisted_operations:
log_unknown: false
safelist:
  enabled: false
cache:
  size: 100MB
storage:
  provider_id: s3
  object_prefix: wundergraph

Persisted Operations Configuration Options

These rules apply to requests being made from the Router to all Subgraphs.

Environment Variable	YAML	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 `storage_providers` section.
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
PERSISTED_OPERATIONS_LOG_UNKNOWN	persisted_operations.log_unknown	Log operations (sent with the operation body) which haven’t yet been persisted. If the value is true, all operations not yet persisted are logged to the router logs.	false
PERSISTED_OPERATIONS_SAFELIST_ENABLED	persisted_operations.safelist.enabled	Only allows persisted operations (sent with operation body). If the value is true, all operations not explicitly added to the safelist are blocked.	false

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:

version: "1"

automatic_persisted_queries:
enabled: true
cache:
  size: 10MB # This is only relevant for an in-memory cache that we maintain
  ttl: 900 # in seconds, set both for a local and a remote KV
storage:
  provider_id: "my_redis"
  object_prefix: cosmo_apq

Configuration Options

These rules apply to requests being made from the Router to all Subgraphs.

YAML	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.cache` options)
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 `storage_providers.redis` section.
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:

config.yaml

version: "1"

execution_config:
  storage:
    provider_id: s3
    object_path: /prod

config.yaml

version: "1"

execution_config:
  file:
    path: "./__schemas/config.json"
    watch: true
    watch_interval: "1s"

Execution config options

Environment Variable	YAML	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_FILE_WATCH_INTERVAL	file.watch_interval	The interval at which the file is checked for changes.	1s
	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 `storage_providers` section.
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.	false
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 `storage_providers` section.
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

Example YAML config:

version: "1"

# Traffic configuration
# See "https://cosmo-docs.wundergraph.com/router/traffic-shaping" for more information
traffic_shaping:
  # Apply to all requests from clients to the router
  router:
    # Is the maximum size of the request body in MB, mib
    max_request_body_size: 5MB
    max_header_bytes: 1MiB
    decompression_enabled: true
  all: # Rules are applied to all subgraph requests.
    # Subgraphs transport options
    request_timeout: 60s
    dial_timeout: 30s
    tls_handshake_timeout: 0s
    response_header_timeout: 0s
    expect_continue_timeout: 0s
    keep_alive_idle_timeout: 90s
    keep_alive_probe_interval: 30s
    max_idle_conns: 1024
    max_conns_per_host: 100
    max_idle_conns_per_host: 20
    # Retry
    retry: # Rule is only applied to GraphQL operations of type "query"
      enabled: true
      algorithm: "backoff_jitter"
      max_attempts: 5
      interval: 3s
      max_duration: 10s
  subgraphs: # allows you to create subgraph specific traffic shaping rules
    products: # Will only affect this subgraph, and override the options in "all" for that subgraph
      request_timeout: 60s
      dial_timeout: 30s
      keep_alive_idle_timeout: 0s
      keep_alive_probe_interval:
      tls_handshake_timeout: 10s
      response_header_timeout: 0s
      expect_continue_timeout: 0s
      max_idle_conns: 1024
      max_conns_per_host: 100
      max_idle_conns_per_host: 20

Subgraph Request Rules

These rules apply to requests being made from the Router to all Subgraphs.

YAML	Description	Default Value
retry	#traffic-shaping-jitter-retry
request_timeout		60s
dial_timeout		30s
response_header_timeout		0s
expect_continue_timeout		0s
tls_handshake_timeout		10s
keep_alive_idle_timeout		90s
keep_alive_probe_interval		30s
max_idle_conns		1024
max_conns_per_host		100
max_idle_conns_per_host		20

Subgraph specific request rules

In addition to the general traffic shaping rules, we also allow users to set subgraph specific timeout options, overriding the default traffic rules defined in all(if present)

Environment Variable	YAML	Required	Description	Default Value
	request_timeout			60s
	dial_timeout			30s
	response_header_timeout			0s
	expect_continue_timeout			0s
	keep_alive_idle_timeout			90s
	keep_alive_probe_interval			30s
	max_idle_conns			1024
	max_conns_per_host			100
	max_idle_conns_per_host			20

Jitter Retry

Environment Variable	YAML	Description	Default Value
RETRY_ENABLED	enabled		true
	algorithm	backoff_jitter	backoff_jitter
	max_attempts
	max_duration
	interval

Client Request Request Rules

These rules apply to requests being made from clients to the Router.

Environment Variable	YAML	Description	Default Value
	max_request_body_size		5mb
MAX_HEADER_BYTES	max_header_bytes	Minimum Router version: 0.156.0 The maximum size of the request headers. Setting this to 0 uses the default value from the http standard lib, which is 1MiB.	1mib
	decompression_enabled	When enabled, the router will check incoming requests for a ‘Content-Encoding’ header and decompress the body accordingly Note: Currently only “gzip” is supported	true
5mb

WebSocket

Configure WebSocket handlers, protocols, and more.

WebSocket Configuration

Environment Variable	YAML	Description	Default Value
WEBSOCKETS_ENABLED	enabled		true
	absinthe_protocol	Absinthe Protocol Configuration
	forward_upgrade_headers	Forward all useful Headers from the Upgrade Request, like User-Agent or Authorization in the extensions field when subscribing on a Subgraph
	forward_upgrade_query_params	Forward all query parameters from the Upgrade Request in the extensions field when subscribing on a Subgraph
	forward_initial_payload	Forward the initial payload from a client subscription in the extensions field when subscribing on a Subgraph	true
	client_info_from_initial_payload	WebSocket Client Info Configuration

Absinthe Protocol Configuration

Legacy WebSocket clients that use the Absinthe protocol might not be able to send a Subprotocol Header. For such clients, you can use the Absinthe Endpoint which automatically chooses the Subprotocol for them so that no Subprotocol Header needs to be set.

Environment Variable	YAML	Required	Description	Default Value
WEBSOCKETS_ABSINTHE_ENABLED	enabled			true
WEBSOCKETS_ABSINTHE_HANDLER_PATH	handler_path		The path to mount the Absinthe handler on	/absinthe/socket

WebSocket Authentication

It’s possible that Authentication for a WebSocket connection is not possible at the HTTP layer. In such a case, you can enable Authentication “from_initial_payload”. This will extract a value from the “initial_payload” field in the first WebSocket message which is responsible for negotiating the protocol between client and server. In addition, it’s possible to export the extracted value into a Request Header, which allows the Router to propagate it using Header Propagation Rules in subsequent Subgraph Requests.

WebSocket Client Info Configuration

Configure how to extract client info from the initial WebSocket payload. This allows you to set client name and version information from the initial connection payload, which can then be forwarded to request headers if needed.

Environment Variable	YAML	Description	Default Value
WEBSOCKETS_CLIENT_INFO_FROM_INITIAL_PAYLOAD_ENABLED	enabled	Enable extracting client info from initial payload	true
WEBSOCKETS_CLIENT_INFO_FROM_INITIAL_PAYLOAD_NAME_FIELD	name_field	The field name in the initial payload to extract the client name from
WEBSOCKETS_CLIENT_INFO_FROM_INITIAL_PAYLOAD_VERSION_FIELD	version_field	The field name in the initial payload to extract the client version from
WEBSOCKETS_CLIENT_INFO_FROM_INITIAL_PAYLOAD_FORWARD_TO_REQUEST_HEADERS_ENABLED	forward_to_request_headers.enabled	Enable forwarding extracted client info to request headers	true
WEBSOCKETS_CLIENT_INFO_FROM_INITIAL_PAYLOAD_NAME_TARGET_HEADER	forward_to_request_headers.name_target_header	The header name to forward the client name to
WEBSOCKETS_CLIENT_INFO_FROM_INITIAL_PAYLOAD_VERSION_TARGET_HEADER	forward_to_request_headers.version_target_header	The header name to forward the client version to

Example WebSocket YAML config:

version: "1"

websocket:
  enabled: true
  absinthe_protocol:
    enabled: true
    handler_path: /absinthe/socket
  forward_initial_payload: true
  forward_upgrade_headers:
    enabled: true
    allow_list: # an empty list allows all headers
      - "Authorization" # forward only the Authorization Header
  forward_upgrade_query_params:
    enabled: true
    allow_list:
      - "Authorization"
  client_info_from_initial_payload:
    # enable extracting client info from initial payload
    enabled: true
    # the field name in the initial payload to extract the client name from
    name_field: "graphql-client-name"
    # the field name in the initial payload to extract the client version from
    version_field: "graphql-client-version"
    # enable forwarding extracted client info to request headers
    forward_to_request_headers:
      # enable forwarding extracted client info to request headers
      enabled: true
      # the header name to forward the client name to
      name_target_header: "GraphQL-Client-Name"
      # the header name to forward the client version to
      version_target_header: "GraphQL-Client-Version"
  authentication:
    # enable authentication from the initial payload
    from_initial_payload:
      enabled: false
      # which key to use one the initial payload to "extract" the Authorization value
      key: "authorization"
      export_token:
        export_token: false
        # to enable Subgraph authentication, we can export the value into a Header
        header_key: "Authorization"

Authentication

Configure different authentication providers.

New Authentication Config (Router Version ≥ 0.169.0)

JWKS

YAML	Required	Default Value
	url	The URL of the JWKs. The JWKs are used to verify the JWT (JSON Web Token). The URL is specified as a string with the format ‘scheme://host:port’.
	refresh_interval	The interval at which the JWKs are refreshed. 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’.	1m
	algorithms	The allowed algorithms for the keys that are retrieved from the JWKs. An empty list means that all algorithms are allowed. The following algorithms are supported “HS256”, “HS384”, “HS512”, “RS256”, “RS384”, “RS512”, “ES256”, “ES384”, “ES512”, “PS256”, “PS384”, “PS512”, “EdDSA”	[] (all allowed)
The URL of the JWKs. The JWKs are used to verify the JWT (JSON Web Token). The URL is specified as a string with the format ‘scheme://host:port’.

JWT

YAML	Required	Description	Default Value
header_name		The name of the header. The header is used to extract the token from the request. The default value is ‘Authorization’.	Authorization
header_value_prefix		The prefix of the header value. The prefix is used to extract the token from the header value. The default value is ‘Bearer’.	Bearer

Header Sources

YAML	Description	Default Value
type	The type of the source. The only currently supported type is ‘header’.	header
name	The name of the header. The header is used to extract the token from the request. The default value is ‘Authorization’.	Authorization
value_prefixes	The prefixes of the header value. The prefixes are used to extract the token from the header value. The default value is ‘Bearer’.	Bearer

Example YAML config V2:

authentication:
  jwt:
    jwks:
      - url: "https://example.com/.well-known/jwks.json"
        refresh_interval: 1m
        # Leaving algorithms empty will allow all supported algorithms from the config docs
      - url: "https://example2.com/.well-known/jwks.json"
        refresh_interval: 2m
        # optional list of allowed algorithms per JWKS
        algorithms: ["RS256", "EdDSA", "HS512"]
    header_name: Authorization # This is the default value
    header_value_prefix: Bearer # This is the default value
    header_sources:
      - type: header
        name: X-Auth-Token
        value_prefixes: [Token, MyToken]
      - type: header
        name: X-Authorization

Old Authentication Config (Router Version < 0.XXX.X)

Provider

Environment Variable	YAML	Required	Description	Default Value
	name		Name of the provider	My Auth Provider
	jwks		JWKS Provider

JWK Provider

Environment Variable	YAML	Required	Description	Default Value
	url
	header_names
	header_value_prefixes
	refresh_interval			1m

Example YAML config:

version: "1"

# Authentication and Authorization
# See https://cosmo-docs.wundergraph.com/router/authentication-and-authorization for more information
authentication:
  providers:
    - name: My Auth Provider # Optional, used for error messages and diagnostics
      jwks: # JWKS provider configuration
        url: https://example.com/.well-known/jwks.json # URL to load the JWKS from
        header_name: Authorization # Optional
        header_value_prefix: Bearer # Optional

Authorization

Environment Variable	YAML	Required	Description	Default Value
REQUIRE_AUTHENTICATION	require_authentication		Set to true to disallow unauthenticated requests	false
REJECT_OPERATION_IF_UNAUTHORIZED	reject_operation_if_unauthorized		If enabled, the Router will return 401 with no response data when the evaluation of field-based permissions (@authenticatedor @requiresScopesfails)	false

Example YAML config:

version: "1"

authorization:
  require_authentication: false
  reject_operation_if_unauthorized: false

CDN

Environment Variable	YAML	Required	Description	Default Value
CDN_URL	url		The URL of the CDN where the Router will fetch its Config. Not required when a static execution config is provided.	https://cosmo-cdn.wundergraph.com
CDN_CACHE_SIZE	cache_size		Cosmo Router caches responses from the CDN in memory, this defines the cache size.	100MB

Example YAML config:

version: "1"

cdn:
  url: https://cosmo-cdn.wundergraph.com
  cache_size: 100MB

Events

The Events section lets you define Event Sources for Event-Driven Federated Subscriptions (EDFS). We support NATS and Kafka as event bus provider.

version: "1"

events:
  providers:
    nats:
      - id: default
        url: "nats://localhost:4222"
        authentication:
          token: "token" # or
          user_info:
            username: "username"
            password: "password"
    kafka:
      - id: my-kafka
        tls:
          enabled: true
        authentication:
          sasl_plain:
            password: "password"
            username: "username"
        brokers:
          - "localhost:9092"

Provider

Environment Variable	YAML	Required	Description	Default Value
	providers		one of: nats, kafka

NATS Provider

Environment Variable	YAML	Required	Description	Default Value
	id		The ID of the provider. This have to match with the ID specified in the subgraph schema.
	url		NATS Connection string
	authentication		Authentication configuration for the NATS provider.
	authentication.token		Token based authentication.
	authentication.user_info		User-Info based authentication.
	authentication.user_info.username		Username.
	authentication.user_info.password		Password.

Kafka Provider

YAML	Description	Default Value
id	The ID of the provider. This have to match with the ID specified in the subgraph schema.	[]
brokers	A list of broker URLs.
authentication	Authentication settings
authentication.sasl_plain	SASL/Plain Authentication method
authentication.sasl_plain.username	SASL/Plain Username
authentication.sasl_plain.password	SASL/Plain Password
tls	TLS configuration for the Kafka provider. If enabled, it uses SystemCertPool for RootCAs by default.
tls.enabled	Enable the TLS.

Nats Provider

Router Engine Configuration

Configure the GraphQL Execution Engine of the Router.

Environment Variable	YAML	Description	Default Value
ENGINE_ENABLE_SINGLE_FLIGHT	enable_single_flight	Deduplicate exactly the same in-flight origin request	true
ENGINE_ENABLE_REQUEST_TRACING	enable_request_tracing	Enable Advanced Request Tracing (ART)This config is not correlated to OTEL tracing.	true
ENGINE_ENABLE_EXECUTION_PLAN_CACHE_RESPONSE_HEADER	enable_execution_plan_cache_response_header	Usually only required for testing. When enabled, the Router sets the response Header “X-WG-Execution-Plan-Cache” to “HIT” or “MISS”	false
ENGINE_MAX_CONCURRENT_RESOLVERS	max_concurrent_resolvers	Use this to limit the concurrency in the GraphQL Engine. A high number will lead to more memory usage. A number too low will slow down your Router.	32
ENGINE_ENABLE_NET_POLL	enable_net_poll	Enables the more efficient poll implementation for all WebSocket implementations (client, server) of the router. This is only available on Linux and MacOS. On Windows or when the host system is limited, the default synchronous implementation is used.	true
ENGINE_WEBSOCKET_CLIENT_POLL_TIMEOUT	websocket_client_poll_timeout	The timeout for the poll loop of the WebSocket client implementation. The period is specified as a string with a number and a unit	1s
ENGINE_WEBSOCKET_CLIENT_CONN_BUFFER_SIZE	websocket_client_conn_buffer_size	The buffer size for the poll buffer of the WebSocket client implementation. The buffer size determines how many connections can be handled in one loop.	128
ENGINE_WEBSOCKET_CLIENT_READ_TIMEOUT	websocket_client_read_timeout	The timeout for the websocket read of the WebSocket client implementation.	5s
ENGINE_WEBSOCKET_CLIENT_WRITE_TIMEOUT	websocket_client_write_timeout	The timeout for the websocket write of the WebSocket client implementation.	10s
ENGINE_WEBSOCKET_CLIENT_PING_INTERVAL	websocket_client_ping_interval	The Websocket client ping interval to the subgraph. Defines how often the router will ping the subgraph to signal that the connection is still alive. Timeout needs to be coordinated with the subgraph. The timeout 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’.	15s
ENGINE_WEBSOCKET_CLIENT_PING_TIMEOUT	websocket_client_ping_timeout	The Websocket client ping timeout to the subgraph. Defines how long the router will wait for a ping response from the subgraph. The timeout 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’.	30s
ENGINE_WEBSOCKET_CLIENT_FRAME_TIMEOUT	websocket_client_frame_timeout	The Websocket client frame timeout to the subgraph. Defines how long the router will wait for a frame response from the subgraph. The timeout 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’.	100ms
ENGINE_EXECUTION_PLAN_CACHE_SIZE	execution_plan_cache_size	Define how many GraphQL Operations should be stored in the execution plan cache. A low number will lead to more frequent cache misses, which will lead to increased latency.	1024
ENGINE_MINIFY_SUBGRAPH_OPERATIONS	minify_subgraph_operations	Minify the subgraph operations. If the value is true, GraphQL Operations get minified after planning. This reduces the amount of GraphQL AST nodes the Subgraph has to parse, which ultimately saves CPU time and memory, resulting in faster response times.	false
ENGINE_ENABLE_PERSISTED_OPERATIONS_CACHE	enable_persisted_operations_cache	Enable the persisted operations cache. The persisted operations cache is used to cache normalized persisted operations to improve performance.	true
ENGINE_ENABLE_NORMALIZATION_CACHE	enable_normalization_cache	Enable the normalization cache. The normalization cache is used to cache normalized operations to improve performance.	true
ENGINE_NORMALIZATION_CACHE_SIZE	normalization_cache_size	The size of the normalization cache.	1024
ENGINE_PARSEKIT_POOL_SIZE	parsekit_pool_size	The size of the ParseKit pool. The ParseKit pool provides re-usable Resources for parsing, normalizing, validating and planning GraphQL Operations. Setting the pool size to a value much higher than the number of CPU Threads available will not improve performance, but only increase memory usage.	8
ENGINE_RESOLVER_MAX_RECYCLABLE_PARSER_SIZE	resolver_max_recyclable_parser_size	Limits the size of the Parser that can be recycled back into the Pool. If set to 0, no limit is applied. This helps keep the Heap size more maintainable if you regularly perform large queries.	32768
ENGINE_ENABLE_VALIDATION_CACHE	enable_validation_cache	Enable the validation cache. The validation cache is used to cache results of validating GraphQL Operations.	true
ENGINE_VALIDATION_CACHE_SIZE	validation_cache_size	The size of the validation cache.	1024
ENGINE_DISABLE_EXPOSING_VARIABLES_CONTENT_ON_VALIDATION_ERROR	disable_exposing_variables_content_on_validation_error	Disables exposing the variables content in the error response. This is useful to avoid leaking sensitive information in the error response.	false
ENGINE_ENABLE_SUBGRAPH_FETCH_OPERATION_NAME	enable_subgraph_fetch_operation_name	Enable appending the operation name to subgraph fetches. This will ensure that the operation name will be included in the corresponding subgraph requests using the following format: $operationName\_\_$ subgraphName__$sequenceID.	true
ENGINE_SUBSCRIPTION_FETCH_TIMEOUT	subscription_fetch_timeout	The maximum time a subscription fetch can take before it is considered timed out.	30s

Example YAML config:

version: "1"

engine:
  enable_single_flight: true
  enable_request_tracing: true
  enable_execution_plan_cache_response_header: false
  max_concurrent_resolvers: 32
  enable_websocket_epoll_kqueue: true
  epoll_kqueue_poll_timeout: "1s"
  epoll_kqueue_conn_buffer_size: 128
  websocket_client_read_timeout: "1s"
  websocket_client_write_timeout: "5s"
  websocket_client_ping_interval: "15s"
  websocket_client_ping_timeout: "30s"
  websocket_client_frame_timeout: "100ms"
  execution_plan_cache_size: 10000
  minify_subgraph_operations: true
  enable_persisted_operations_cache: true
  enable_normalization_cache: true
  normalization_cache_size: 1024
  parsekit_pool_size: 8
  enable_validation_cache: true
  validation_cache_size: 1024
  disable_exposing_variables_content_on_validation_error: false
  enable_subgraph_fetch_operation_name: true
  subscription_fetch_timeout: 30s

Debug Configuration

Environment Variable	YAML	Description	Default Value
ENGINE_DEBUG_PRINT_OPERATION_TRANSFORMATIONS	print_operation_transformations	Print the operation transformations.	false
ENGINE_DEBUG_PRINT_OPERATION_ENABLE_AST_REFS	print_operation_enable_ast_refs	Print the operation enable AST refs.	false
ENGINE_DEBUG_PRINT_PLANNING_PATHS	print_planning_paths	Print the planning paths.	false
ENGINE_DEBUG_PRINT_QUERY_PLANS	print_query_plans	Print the query plans.	false
ENGINE_DEBUG_PRINT_NODE_SUGGESTIONS	print_node_suggestions	Print the node suggestions.	false
ENGINE_DEBUG_CONFIGURATION_VISITOR	configuration_visitor	Print the configuration visitor.	false
ENGINE_DEBUG_PLANNING_VISITOR	planning_visitor	Print the planning visitor.	false
ENGINE_DEBUG_DATASOURCE_VISITOR	datasource_visitor	Print the datasource visitor.	false
ENGINE_DEBUG_REPORT_WEBSOCKET_CONNECTIONS	report_websocket_connections	Print the websocket connections.	false
ENGINE_DEBUG_REPORT_MEMORY_USAGE	report_memory_usage	Print the memory usage.	false
ENGINE_DEBUG_ENABLE_RESOLVER_DEBUGGING	enable_resolver_debugging	Enable verbose debug logging for the Resolver.	false
ENGINE_DEBUG_ENABLE_PERSISTED_OPERATIONS_CACHE_RESPONSE_HEADER	enable_persisted_operations_cache_response_header	Enable the persisted operations cache response header. The persisted operations cache response header is used to cache the persisted operations in the client.	false
ENGINE_DEBUG_ENABLE_NORMALIZATION_CACHE_RESPONSE_HEADER	enable_normalization_cache_response_header	Enable the normalization cache response header. The normalization cache response header is used to cache the normalized operations in the client.	false
ENGINE_DEBUG_ALWAYS_INCLUDE_QUERY_PLAN	always_include_query_plan	Always include the query plan in the response.	false
ENGINE_DEBUG_ALWAYS_SKIP_LOADER	always_skip_loader	Always skip the loader. This will return no data but only render response extensions, e.g. to expose the query plan.	false

Example YAML config:

version: "1"

engine:
  debug:
    print_operation_transformations: false
    print_operation_enable_ast_refs: false
    print_planning_paths: false
    print_query_plans: false
    print_node_suggestions: false
    configuration_visitor: false
    planning_visitor: false
    datasource_visitor: false
    report_websocket_connections: false
    report_memory_usage: false
    enable_resolver_debugging: false
    enable_persisted_operations_cache_response_header: false
    enable_normalization_cache_response_header: false
    always_include_query_plan: false
    always_skip_loader: false

Rate Limiting

Configures a rate limiter on the outgoing subgraphs requests. When enabled, a rate of 10 req/s with a burst of 10 requests is configured.

The rate limiter requires Redis version 3.2 or newer since it relies on replicate_commands feature. ElastiCache for Redis only works in non-clustered mode. You can enable a failover instance to achieve high availability.

Key Suffix Expression

As you can see in the config table below, you can define an expression to generate the a rate limiting key suffix. The evaluation of the expression must return a string, which will be appended to the key prefix. Using a key suffix expression, you’re able to dynamically choose a rate limiting key, e.g. based on the user authentication, a header, or a combination. Here’s an example expression that uses the sub claim if available, and a Header as the fallback.

request.auth.claims.sub ?? request.header.Get('X-Forwarded-For')

For mor information on how to use the expression language, please refer to the Template Expressions section.

General Rate Limiting Configuration

Environment Variable	YAML	Description	Default Value
RATE_LIMIT_ENABLED	enabled	Enable / Disable rate limiting globally	false
RATE_LIMIT_STRATEGY	strategy	The rate limit strategy to use	simple
	simple_strategy	[
Rate Limiting Simple Strategy](/router/configuration#rate-limiting-simple-strategy)	simple
	storage	Rate Limiting Redis Storage
RATE_LIMIT_KEY_SUFFIX_EXPRESSION	key_suffix_expression	The expression to define a key suffix for the rate limit, e.g. by using request headers, claims, or a combination of both with a fallback strategy. The expression is specified as a string and needs to evaluate to a string. Please see https://expr-lang.org/ for more information.
	error_extension_code
Rate Limit Error Extension Code

Rate Limiting Redis Storage

Environment Variable	YAML	Description	Default Value
RATE_LIMIT_REDIS_URLS	urls	List of the connection URL(s).	[redis://localhost:6379]
RATE_LIMIT_REDIS_CLUSTER_ENABLED	cluster_enabled	If the Redis instance is a Redis cluster	false
RATE_LIMIT_REDIS_KEY_PREFIX	key_prefix	This prefix is used to namespace the ratelimit keys	cosmo_rate_limit

Rate Limiting Simple Strategy

Environment Variable	YAML	Description	Default Value
RATE_LIMIT_SIMPLE_RATE	rate	Allowed request rate (number)	10
RATE_LIMIT_SIMPLE_BURST	burst	Allowed burst rate (number) - max rate per one request	10
RATE_LIMIT_SIMPLE_PERIOD	period	The rate limiting period, e.g. ”10s”, “1m”, etc…	1s
RATE_LIMIT_SIMPLE_REJECT_EXCEEDING_REQUESTS	reject_exceeding_requests	Reject the complete request if a sub-request exceeds the rate limit. If set to false, partial responses are possible.	false
RATE_LIMIT_SIMPLE_HIDE_STATS_FROM_RESPONSE_EXTENSION	hide_stats_from_response_extension	Hide the rate limit stats from the response extension. If the value is true, the rate limit stats are not included in the response extension.	false

Rate Limit Error Extension Code

Environment Variable	YAML	Required	Description	Default Value
RATE_LIMIT_ERROR_EXTENSION_CODE_ENABLED	enabled		If enabled, a code will be added to the extensions.code field of error objects related to rate limiting. This allows clients to easily identify if an error happened due to rate limiting.	true
RATE_LIMIT_ERROR_EXTENSION_CODE	code		The code to add to the extensions.code field of error objects related to rate limiting.	RATE_LIMIT_EXCEEDED

Rate Limiting Example YAML configuration

rate_limit:
    enabled: true
    strategy: "simple"
    simple_strategy:
        rate: 10
        burst: 10
        period: 1s
        reject_exceeding_requests: false
        reject_status_code: 200
        hide_stats_from_response_extension: false
    storage:
        cluster_enabled: false
        urls:
         - "redis://localhost:6379"
        key_prefix: "cosmo_rate_limit"
    debug: false
    key_suffix_expression: ""
    error_extension_code:
        enabled: true
        code: "RATE_LIMIT_EXCEEDED"

Subgraph Error Propagation

The configuration for the subgraph error propagation. Errors can be exposed to the client in a “wrapped” form to hide Subgraph internals, or it’s possible to “pass-through” Subgraph errors directly to the client.

Environment Variable	YAML	Description	Default Value
SUBGRAPH_ERROR_PROPAGATION_ENABLED	enabled	Enable error propagation. If the value is true (default: false), Subgraph errors will be propagated to the client.	false
SUBGRAPH_ERROR_PROPAGATION_MODE	mode	The mode of error propagation. The supported modes are ‘wrapped’ (default) and ‘pass-through’. The ‘wrapped’ mode wraps the error in a custom error object to hide internals. The ‘pass-through’ mode returns the error as is from the Subgraph.	wrapped
SUBGRAPH_ERROR_PROPAGATION_REWRITE_PATHS	rewrite_paths	Rewrite the paths of the Subgraph errors. If the value is true (default), the paths of the Subgraph errors will be rewritten to match the Schema of the Federated Graph.	true
SUBGRAPH_ERROR_PROPAGATION_OMIT_LOCATIONS	omit_locations	Omit the location field of Subgraph errors. If the value is true, the location field of Subgraph errors will be omitted. This is useful because the locations of a Subgraph error is internal to the Subgraph and not relevant to the client.	true
SUBGRAPH_ERROR_PROPAGATION_OMIT_EXTENSIONS	omit_extensions	Omit the extensions field of Subgraph errors. If the value is true, the extensions field of Subgraph errors will be omitted. This is useful in case you want to avoid leaking internal information to the client. Some users of GraphQL leverage the errors.extensions.code field to implement error handling logic in the client, in which case you might want to set this to false.	false
SUBGRAPH_ERROR_PROPAGATION_STATUS_CODES	propagate_status_codes	Propagate Subgraph status codes. If the value is true, Subgraph Response status codes will be propagated to the client in the errors.extensions.code field.	false
SUBGRAPH_ERROR_PROPAGATION_ALLOWED_FIELDS	allowed_fields	In passthrough mode, by default only message and path is propagated. You can specify additional fields here.
SUBGRAPH_ERROR_PROPAGATION_DEFAULT_EXTENSION_CODE	default_extension_code	The default extension code. The default extension code is used to specify the default code for the Subgraph errors when the code is not present.	DOWNSTREAM_SERVICE_ERROR
SUBGRAPH_ERROR_PROPAGATION_ATTACH_SERVICE_NAME	attach_service_name	Attach the service name to each Subgraph error. If the value is true, the service name will be attached to the Subgraph errors.	true
SUBGRAPH_ERROR_PROPAGATION_ALLOWED_EXTENSION_FIELDS	allowed_extension_fields	The allowed extension fields. The allowed extension fields are used to specify which fields of the Subgraph errors are allowed to be propagated to the client.	[“code”]

Example YAML configuration:

version: "1"

subgraph_error_propagation:
  enabled: true
  propagate_status_codes: false
  mode: "wrapped"
  rewrite_paths: true
  omit_locations: true
  omit_extensions: false
  default_extension_code: DOWNSTREAM_SERVICE_ERROR
  attach_service_name: true
  allowed_extension_fields:
    - "code"

Security

The configuration for the security. The security is used to configure the security settings for the Router.

Environment Variable	YAML	Description	Default Value
SECURITY_BLOCK_MUTATIONS	block_mutations	Block mutation Operations.
SECURITY_BLOCK_MUTATIONS_ENABLED	block_mutations.enabled	If the value is true, the mutations are blocked.	false
SECURITY_BLOCK_MUTATIONS_CONDITION	block_mutations.condition	The expression to evaluate if the operation should be blocked.
SECURITY_BLOCK_SUBSCRIPTIONS	block_subscriptions	Block subscription Operations.
	block_subscriptions.enabled	If the value is true, the subscriptions are blocked.	false
	block_subscriptions.condition	The expression to evaluate if the operation should be blocked.
SECURITY_BLOCK_NON_PERSISTED_OPERATIONS	block_non_persisted_operations	Block non-persisted Operations.
SECURITY_BLOCK_NON_PERSISTED_OPERATIONS_ENABLED	block_non_persisted_operations.enabled	If the value is true, the non-persisted operations are blocked.	false
SECURITY_BLOCK_NON_PERSISTED_OPERATIONS_CONDITION	block_non_persisted_operations.condition	The expression to evaluate if the operation should be blocked.
	complexity_calculation_cache	Complexity Cache configuration
	complexity_limits	Complexity limits configuration

Example YAML Configuration

version: "1"

security:
  block_mutations:
    enabled: false
    condition: "request.header.Get('x-block-mutation') == 'yes'"
  block_subscriptions:
    enabled: false
  block_non_persisted_operations:
    enabled: false
  complexity_calculation_cache: # This is for a local in-memory cache, to persist the calculation results
    enabled: true
    size: 1024
  complexity_limits:
    depth: # the equivalent of `security.depth_limit` prevoiusly
      enabled: true
      limit: 7
      ignore_persisted_operations: true
    total_fields:
      enabled: true
      limit: 128
      ignore_persisted_operations: true
    root_fields:
      enabled: true
      limit: 3
      ignore_persisted_operations: true
    root_field_aliases:
      enabled: false
      limit: 3
      ignore_persisted_operations: true

Query Depth is now deprecated. We recommend using the security.complexity_calculation_cache and security.complexity_limits configurations instead, which provide that functionality.

Complexity Calculation Cache

The configuration for the in-memory complexity cache, to help speed up the calculation process in the event of a recurring query

Environment Variable	YAML	Required	Description	Default Value
SECURITY_COMPLEXITY_CACHE_ENABLED	enabled		Enable the complexity cache	false
SECURITY_COMPLEXITY_CACHE_SIZE	size		The size of the complexity cache	1024

Complexity Limits

The configuration for adding a complexity limits for queries. We currently expose 4 limits:

Query Depth - How many nested levels you can have in a query. This limit prevents infinite querying, and also limits the size of the data returned.
Total Fields in Query
Root Fields in Query
Root Field Aliases in Query

For all of the limits, if the limit is 0, or enabled isn’t true, the limit isn’t applied. All of them have the same configuration fields:

YAML	Description	Default Value
enabled	Enable the specific limit. If the value is true (default: false), and a valid limit value is set, the limit will be applied	false
limit	The limit amount for query. If the limit is 0, this limit isn’t applied	0
ignore_persisted_operations	Disable the limit for persisted operations. Since persisted operations are stored intentionally, users may want to disable the limit to consciously allow nested persisted operations	false

File Upload

The configuration for file upload. Configure whether it should be enabled along with file size and number of files.

Environment Variable	YAML	Description	Default Value
FILE_UPLOAD_ENABLED	enabled	Whether the feature is enabled or not	true
FILE_UPLOAD_MAX_FILE_SIZE	max_file_size	The maximum size of a file that can be uploaded. The size is specified as a string with a number and a unit, e.g. 10KB, 1MB, 1GB. The supported units are ‘KB’, ‘MB’, ‘GB’.	50MB
FILE_UPLOAD_MAX_FILES	max_files	The maximum number of files that can be uploaded per request.	2

Example YAML Configuration

version: "1"

file_upload:
  enabled: true
  max_file_size: 1GB
  max_files: 2

Client Header

The configuration for custom names for client name and client version headers.

Environment Variable	YAML	Required	Description	Default Value
	name		The custom name of the client name header.
	version		The custom name of the client version header.

Example YAML Configuration

version: "1"

client_header:
  name: "Client-Name"
  version: "Client-Version"

By default, we support Graphql-Client-Name , Graphql-Client-Version, Apollo-Graphql-Client-Name, Apollo-Graphql-Client-Version. The custom names are given more precedence.

Apollo Compatibility Flags

This configuration is used to enable full compatibility with Apollo Federation, Apollo Gateway and Apollo Router, you can enable certain compatibility flags, allowing you to use Cosmo Router as a drop-in replacement for Apollo.

Apollo Compatibility Value Completion

Invalid __typename values will be returned in extensions.valueCompletion instead of errors.

Apollo Compatibility Truncate Floats

Truncate floats like 1.0 to 1, 2.0 to 2, etc.. Values like 1.1 or 2.2 will not be truncated.

Apollo Compatibility Suppress Fetch Errors

Suppresses fetch errors. When enabled, only the ‘data’ object is returned, suppressing errors. If disabled, fetch errors are included in the ‘errors’ array.

Apollo Compatibility Replace Undefined Op Field Errors

Produces the same error message as Apollo when an invalid operation field is included in an operation selection set. Extension code: “GRAPHQL_VALIDATION_FAILED” Status code: 400

Apollo Compatibility Replace Invalid Var Errors

Produces the same error message as Apollo when an invalid variable is supplied. Extension code: “BAD_USER_INPUT”

Apollo Compatibility Replace Validation Error Status

Produces the same error status as Apollo when validation fails. Error status: 400 Bad Request Minimum router version: 0.175.0

Environment Variable	YAML	Description	Default Value
APOLLO_COMPATIBILITY_ENABLE_ALL	apollo_compatibility_flags: enable_all: <bool>	Enables all the options of Apollo Compatibility.	false
APOLLO_COMPATIBILITY_VALUE_COMPLETION_ENABLED	value_completion: enabled: <bool>	Enables value completion.	false
APOLLO_COMPATIBILITY_TRUNCATE_FLOATS_ENABLED	truncate_floats: enabled: <bool>	Enables truncate floats.	false
APOLLO_COMPATIBILITY_SUPPRESS_FETCH_ERRORS_ENABLED	suppress_fetch_errors: enabled: <bool>	Enables suppress fetch errors.	false
APOLLO_COMPATIBILITY_REPLACE_UNDEFINED_OP_FIELD_ERRORS_ENABLED	replace_undefined_op_field_errors: enabled: <bool>	Replaces undefined operation field errors.	false
APOLLO_COMPATIBILITY_REPLACE_INVALID_VAR_ERRORS_ENABLED	replace_invalid_var_errors: enabled: <bool>	Replaces invalid variable errors.	false
APOLLO_COMPATIBILITY_REPLACE_VALIDATION_ERROR_STATUS_ENABLED	replace_validation_error_status_enabled: <bool>	Replaces validation error status with 400.	false
APOLLO_COMPATIBILITY_SUBSCRIPTION_MULTIPART_PRINT_BOUNDARY_ENABLED	subscription_multipart_print_boundary: enabled: <bool>	Prints the multipart boundary right after the message in multipart subscriptions. Without this flag, the Apollo client wouldn’t parse a message until the next one is pushed.	false

Example YAML Configuration

version: "1"

apollo_compatibility_flags:
  enable_all: false
  value_completion:
    enabled: true
  truncate_floats:
    enabled: false
  suppress_fetch_errors:
    enabled: true
  replace_undefined_op_field_errors:
    enabled: true
  replace_invalid_var_errors:
    enabled: true
  replace_validation_error_status:
    enabled: false

Apollo Router Compatibility Flags

Apollo Router Compatibility Flags can be enabled alongside Apollo Compatibility Flags, but some will override their counterpart’s functionality. This means you can safely use enable_all: true alongside these flags.

Apollo Router Compatibility Replace Invalid Var Errors

Produces the same error messages as Apollo Router when an invalid variable is supplied. Extension code: “VALIDATION_INVALID_TYPE_VARIABLE”

Environment Variable	YAML	Required	Description	Default Value
APOLLO_ROUTER_COMPATIBILITY_REPLACE_INVALID_VAR_ERRORS_ENABLED	replace_invalid_var_errors		Replaces invalid variable errors.	false

Example YAML Configuration

version: "1"

apollo_router_compatibility_flags:
  replace_invalid_var_errors:
    enabled: true

Cache warmer

YAML	Description	Default Value
enabled	Enable the cache warmer.	false
workers	The number of workers for the cache warmup to run in parallel. Higher numbers decrease the time to warm up the cache but increase the load on the system.	8
items_per_second	The number of cache warmup items to process per second. Higher numbers decrease the time to warm up the cache but increase the load on the system.	50
timeout	The timeout for warming up the cache. This can be used to limit the amount of time cache warming will block deploying a new config. 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’.	30s
source	The source of the cache warmup items. Only one can be specified. If empty, the cache warmup source is the Cosmo CDN and it requires a graph to be set.

Example YAML config:

version: "1"

cache_warmup:
  enabled: true
  workers: 8
  items_per_second: 50
  timeout: 30s

Source

The source of the cache warmup items. Only one can be specified. If empty, the cache warmup source is the Cosmo CDN and it requires a graph to be set.

Environment Variable	YAML	Required	Description	Default Value
	path		The path to the directory containing the cache warmup items.

Example YAML config:

version: "1"

cache_warmup:
  enabled: true
  workers: 8
  items_per_second: 50
  timeout: 30s
  source:
    path: "./cache-warmer/operations"

Template ExpressionsUsing Template Expressions for Request and Configuration Control

⌘I

​Config file

​Expand Environment Variables

​Config Validation & Auto-completion

​IDE Configuration

​Environment Variables

​Router

​Example configuration:

​Config watcher hot reloading

​watch_config options

​Access Logs

​Example YAML config:

​Telemetry

​Graph

​MCP (Model Context Protocol)

​TLS

​Server TLS

​Example YAML config:

​Client Authentication

​Example YAML config:

​Compliance

​IP Anonymization

​Example YAML config:

​Cluster

​Example YAML config:

​Telemetry

​Example YAML config:

​Tracing

​Example YAML config:

​Exporters

​Example YAML config:

​Propagation

​Example YAML config:

​Metrics

​OTLP

​Attributes

​Example YAML config:

​Prometheus

​Example YAML config:

​Exporter

​Example YAML config:

​GraphQL Metrics

​Example YAML config:

​CORS

​Example YAML config:

​Cache Control Policy

​Example YAML Config:

​Custom Modules

​Example YAML config:

​gRPC Plugins

​Example YAML config:

​Headers

​Cookie Whitelist

​Global Header Rules

​Example YAML config:

​Header Rule Example Using Template Expression:

​Request Header Rule

​Example YAML config:

​Response Header Rule

​Example YAML config:

​Storage Providers

​Example YAML config:

​Storage Provider Types

​File System Storage Provider

​Redis Storage Provider

​S3 Storage Provider

​CDN Provider

​Persisted Operations

​Example YAML config:

​Persisted Operations Configuration Options

​Automatic Persisted Queries

​Example YAML config:

​Configuration Options

​Execution Config

​Example YAML config:

​Execution config options

​Traffic Shaping

​Example YAML config:

​Subgraph Request Rules

​Subgraph specific request rules

​Jitter Retry

Config file

Expand Environment Variables

Config Validation & Auto-completion

IDE Configuration

Environment Variables

Router

Example configuration:

Config watcher hot reloading

`watch_config` options

Access Logs

Example YAML config:

Telemetry

Graph

MCP (Model Context Protocol)

TLS

Server TLS

Example YAML config:

Client Authentication

Example YAML config:

Compliance

IP Anonymization

Example YAML config:

Cluster

Example YAML config:

Telemetry

Example YAML config:

Tracing

Example YAML config:

Exporters

Example YAML config:

Propagation

Example YAML config:

Metrics

OTLP

Attributes

Example YAML config:

Prometheus

Example YAML config:

Exporter

Example YAML config:

GraphQL Metrics

Example YAML config:

CORS

Example YAML config:

Cache Control Policy

Example YAML Config:

Custom Modules

Example YAML config:

gRPC Plugins

Example YAML config:

Headers

Cookie Whitelist

Global Header Rules

Example YAML config:

Header Rule Example Using Template Expression:

Request Header Rule

Example YAML config:

Response Header Rule

Example YAML config:

Storage Providers

Example YAML config:

Storage Provider Types

File System Storage Provider

Redis Storage Provider

S3 Storage Provider

CDN Provider

Persisted Operations

Example YAML config:

Persisted Operations Configuration Options

Automatic Persisted Queries

Example YAML config:

Configuration Options

Execution Config

Example YAML config:

Execution config options

Traffic Shaping

Example YAML config:

Subgraph Request Rules

Subgraph specific request rules

Jitter Retry