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 or wgc 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.

config.yaml

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:

config.yaml

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.

config.yaml

# 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:

config.yaml

# 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 Required Description Default Value

Environment Variable	YAML	Description	Default Value
LISTEN_ADDR	listen_addr	The server listener address.	localhost:3002
CONTROLPLANE_URL	controlplane_url	The controlplane url.	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		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 `GRACE_PERIOD`	60s
GRACE_PERIOD	grace_period	Maximum time in seconds the server has between schema updates to gracefully close client connections. Should be smaller than `SHUTDOWN_DELAY`	20s
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 `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		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.

LISTEN_ADDR

listen_addr

The server listener address.

localhost:3002

CONTROLPLANE_URL

controlplane_url

The controlplane url.

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

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 GRACE_PERIOD

60s

GRACE_PERIOD

grace_period

Maximum time in seconds the server has between schema updates to gracefully close client connections. Should be smaller than SHUTDOWN_DELAY

20s

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 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

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:

config.yaml

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: ""

Graph

Overall configuration for the Graph that's configured for this Router.

Environment Variable YAML Required Description Default Value

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

GRAPH_API_TOKEN

token

The token permits the router to communicate with the controlplane and export telemetry. Created with wgc router token create. (Can be empty when providing a static router configuration through ROUTER_CONFIG_PATHbut will disable the default telemetry stack)

Example YAML config:

config.yaml

version: "1"

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

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.

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:

config.yaml

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

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:

config.yaml

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"

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:

config.yaml

version: "1"
 
compliance:
  anonymize_ip:
    enabled: true
    method: redact # hash or redact

Cluster

Environment Variable	YAML	Required	Description	Default Value
CLUSTER_NAME	name

Environment Variable

YAML

Required

Description

Default Value

CLUSTER_NAME

name

Example YAML config:

config.yaml

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

Telemetry

Environment Variable	YAML	Required	Description	Default Value
TELEMETRY_SERVICE_NAME	service_name			cosmo-router

Environment Variable

YAML

Required

Description

Default Value

TELEMETRY_SERVICE_NAME

service_name

cosmo-router

Example YAML config:

config.yaml

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

Tracing

Environment Variable	YAML	Description	Default Value
TRACING_ENABLED	enabled		true
TRACING_SAMPLING_RATE	sampling_rate	min 0.0 max 1.0	1
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

Environment Variable

YAML

Required

Description

Default Value

TRACING_ENABLED

enabled

true

TRACING_SAMPLING_RATE

sampling_rate

min 0.0

max 1.0

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:

config.yaml

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

Example YAML config:

config.yaml

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

Environment Variable

YAML

Required

Description

Default Value

trace_context

true

jaeger

baggage

Example YAML config:

config.yaml

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

Metrics

OLTP

Environment Variable	YAML	Required	Description	Default Value
METRICS_OTLP_ENABLED	enabled		Enables OTEL metrics instrumentation	true
METRICS_OTLP_ROUTER_RUNTIME	router_runtime			true

Environment Variable

YAML

Required

Description

Default Value

METRICS_OTLP_ENABLED

enabled

Enables OTEL metrics instrumentation

true

METRICS_OTLP_ROUTER_RUNTIME

router_runtime

true

Example YAML config:

config.yaml

version: "1"

# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:
  # OpenTelemetry Metrics
  metrics:
    otlp:
      enabled: true
      router_runtime: true

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 prometheus listener address	"127.0.0.1:8088"
PROMETHEUS_EXCLUDE_METRICS	exclude_metrics
PROMETHEUS_EXCLUDE_METRIC_LABELS	exclude_metric_labels

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:

config.yaml

version: "1"

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

Exporter

Example YAML config:

config.yaml

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
          # 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

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:

config.yaml

version: "1"

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

CORS

Environment Variable	YAML	Default Value
CORS_ALLOW_ORIGINS	allow_origins	*
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

Environment Variable

YAML

Required

Description

Default Value

CORS_ALLOW_ORIGINS

allow_origins

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

Example YAML config:

config.yaml

version: "1"

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

Custom Modules

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

Example YAML config:

config.yaml

version: "1"

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

Headers

Configure Header propagation rules for all Subgraphs or individual Subgraphs by name.

Global Header Rules

Apply to requests to "all" Subgraphs

Environment Variable	YAML	Required	Description	Default Value
	request		Request Header Rule

Environment Variable

YAML

Required

Description

Default Value

request

Request Header Rule

Example YAML config:

config.yaml

version: "1"

# Header manipulation
# See "https://cosmo-docs.wundergraph.com/router/proxy-capabilities" for more information
headers:
  all: # Header rules for all origin requests.
    request:
      - op: "propagate"
        named: X-Test-Header
      - op: "propagate"
        matching: (?i)^x-deprecated-.*

Request Header Rule

Apply to requests to specific Subgraphs.

Environment Variable

YAML

Required

Description

Default Value

oneof=propagate

matching

matching is the regex to match the header name against

named

named is the exact header name to match

default

default is the default value to set if the header is not present

Example YAML config:

config.yaml

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

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
  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: 0s
    keep_alive_probe_interval: 30s
    # 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

Subgraph Request Rules

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

Environment Variable

YAML

Required

Description

Default Value

retry

#traffic-shaping-jitter-retry

request_timeout

60s

dial_timeout

30s

response_header_timeout

expect_continue_timeout

tls_handshake_timeout

10s

keep_alive_idle_timeout

keep_alive_probe_interval

30s

Jitter Retry

Client Request Request Rules

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

Environment Variable	YAML	Required	Description	Default Value
	max_request_body_size			5mb

Environment Variable

YAML

Required

Description

Default Value

max_request_body_size

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
WEBSOCKETS_FORWARD_UPGRADE_HEADERS	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	true
WEBSOCKETS_FORWARD_UPGRADE_QUERY_PARAMS	forward_upgrade_query_params	Forward all query parameters from the Upgrade Request in the extensions field when subscribing on a Subgraph	true
WEBSOCKETS_FORWARD_INITIAL_PAYLOAD	forward_initial_payload	Forward the initial payload from a client subscription in the extensions field when subscribing on a Subgraph	true

Environment Variable

YAML

Required

Description

Default Value

WEBSOCKETS_ENABLED

enabled

true

absinthe_protocol

Absinthe Protocol Configuration

WEBSOCKETS_FORWARD_UPGRADE_HEADERS

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

true

WEBSOCKETS_FORWARD_UPGRADE_QUERY_PARAMS

forward_upgrade_query_params

Forward all query parameters from the Upgrade Request in the extensions field when subscribing on a Subgraph

true

WEBSOCKETS_FORWARD_INITIAL_PAYLOAD

forward_initial_payload

Forward the initial payload from a client subscription in the extensions field when subscribing on a Subgraph

true

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

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

Example WebSocket YAML config:

config.yaml

version: "1"

websocket:
  enabled: true
  absinthe_protocol:
    enabled: true
    handler_path: /absinthe/socket
  forward_initial_payload: true
  forward_upgrade_headers: true
  forward_upgrade_query_params: true

Authentication

Configure different authentication providers.

Provider

Environment Variable

YAML

Required

Description

Default Value

name

Name of the provider

jwks

JWK Provider

Environment Variable

YAML

Required

Description

Default Value

url

header_names

header_value_prefixes

refresh_interval

Example YAML config:

config.yaml

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

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:

config.yaml

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	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

Environment Variable

YAML

Required

Description

Default Value

CDN_URL

url

The URL of the CDN where the Router will fetch its Config

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:

config.yaml

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).

Currently, we only support to use a single Event Source (NATS) with more to come in the future.

config.yaml

version: "1"

events:
  sources:
    - provider: NATS
      url: "nats://localhost:4222"

Event Source

Environment Variable

YAML

Required

Description

Default Value

provider

one of: NATS

url

The URL of the event source, e.g. "nats://localhost:4222"

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.	1024
ENGINE_ENABLE_WEBSOCKET_EPOLL_KQUEUE	enable_websocket_epoll_kqueue	Use Epoll/Kqueue to handle WebSocket connections efficiently.	true
ENGINE_EPOLL_KQUEUE_POLL_TIMEOUT	epoll_kqueue_poll_timeout	Define the polling timeout for Epoll / Kqueue.	1s
ENGINE_EPOLL_KQUEUE_CONN_BUFFER_SIZE	epoll_kqueue_conn_buffer_size	Epoll / Kqueue polling uses a buffer. This number should match the number of potential client messages per polling interval.	128
ENGINE_WEBSOCKET_READ_TIMEOUT	websocket_read_timeout		5s
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.	10000

Environment Variable

YAML

Required

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.

1024

ENGINE_ENABLE_WEBSOCKET_EPOLL_KQUEUE

enable_websocket_epoll_kqueue

Use Epoll/Kqueue to handle WebSocket connections efficiently.

true

ENGINE_EPOLL_KQUEUE_POLL_TIMEOUT

epoll_kqueue_poll_timeout

Define the polling timeout for Epoll / Kqueue.

ENGINE_EPOLL_KQUEUE_CONN_BUFFER_SIZE

epoll_kqueue_conn_buffer_size

Epoll / Kqueue polling uses a buffer. This number should match the number of potential client messages per polling interval.

128

ENGINE_WEBSOCKET_READ_TIMEOUT

websocket_read_timeout

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.

10000

Example YAML config:

config.yaml

version: "1"

engine:
  enable_single_flight: true
  enable_request_tracing: true
  enable_execution_plan_cache_response_header: false
  max_concurrent_resolvers: 1024
  enable_websocket_epoll_kqueue: true
  epoll_kqueue_poll_timeout: "1s"
  epoll_kqueue_conn_buffer_size: 128
  websocket_read_timeout: "1s"
  execution_plan_cache_size: 10000

Debug Configuration

Environment Variable	YAML	Required	Description	Default Value
	report_websocket_connections		Report the number of WebSocket Connections and active Subscriptions in regular intervals to the log	false
	report_memory_usage		Report the Memory usage of Cosmo Router to the log in regular intervals	false

Environment Variable

YAML

Required

Description

Default Value

report_websocket_connections

Report the number of WebSocket Connections and active Subscriptions in regular intervals to the log

false

report_memory_usage

Report the Memory usage of Cosmo Router to the log in regular intervals

false

Example YAML config:

config.yaml

version: "1"

engine:
  debug:
    report_websocket_connections: false
    report_memory_usage: 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.

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	simple
	simple_strategy	The configuration for the simple strategy
	storage	Redis connection settings.

Environment Variable

YAML

Required

Description

Default Value

RATE_LIMIT_ENABLED

enabled

Enable / Disable rate limiting globally

false

RATE_LIMIT_STRATEGY

strategy

The rate limit strategy

simple

simple_strategy

The configuration for the simple strategy

storage

Redis connection settings.

Storage

Environment Variable	YAML	Required	Description	Default Value
RATE_LIMIT_REDIS_URL	addr		The connection URL.	redis://localhost:6379
RATE_LIMIT_REDIS_KEY_PREFIX	key_prefix		This prefix is used to namespace the ratelimit keys	cosmo_rate_limit

Environment Variable

YAML

Required

Description

Default Value

RATE_LIMIT_REDIS_URL

addr

The connection URL.

redis://localhost:6379

RATE_LIMIT_REDIS_KEY_PREFIX

key_prefix

This prefix is used to namespace the ratelimit keys

cosmo_rate_limit

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

Environment Variable

YAML

Required

Description

Default Value

RATE_LIMIT_SIMPLE_RATE

rate

Allowed request rate (number)

RATE_LIMIT_SIMPLE_BURST

burst

Allowed burst rate (number) - max rate per one request

RATE_LIMIT_SIMPLE_PERIOD

period

The rate limiting period, e.g. "10s", "1m", etc...

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

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 (default), 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 (default: false), 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 (default: false), Subgraph Response status codes will be propagated to the client in the errors.extensions.code field.	false

Environment Variable

YAML

Required

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 (default), 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 (default: false), 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 (default: false), Subgraph Response status codes will be propagated to the client in the errors.extensions.code field.

false

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

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. If the value is true, the mutations are blocked.	false
SECURITY_BLOCK_SUBSCRIPTIONS	block_subscriptions	Block subscription Operations. If the value is true, the subscriptions are blocked.	false
SECURITY_BLOCK_NON_PERSISTED_OPERATIONS	block_non_persisted_operations	Block non-persisted Operations. If the value is true, the non-persisted operations are blocked.	false

Environment Variable

YAML

Required

Description

Default Value

SECURITY_BLOCK_MUTATIONS

block_mutations

Block mutation Operations. If the value is true, the mutations are blocked.

false

SECURITY_BLOCK_SUBSCRIPTIONS

block_subscriptions

Block subscription Operations. If the value is true, the subscriptions are blocked.

false

SECURITY_BLOCK_NON_PERSISTED_OPERATIONS

block_non_persisted_operations

Block non-persisted Operations. If the value is true, the non-persisted operations are blocked.

false

Example YAML Configuration

version: "1"

security:
    block_mutations: true
    block_subscriptions: true
    block_non_persisted_operations: true

PreviousDownload & Install NextCustom Modules

Last updated 12 days ago