Comment on page

Configuration

Learn how to configure your router.

The router provides three different ways of customization:
1.The config file. This file allows configuring the global behavior of the router. For a full reference of all available options see below. You can either pass environment variables or use a local config.yaml for convenience.
2.The router execution config. This file contains information on how to resolve your federated schema. The engine uses the information to build a highly optimized query planner. The content is fetched by default from the controlplane or CDN but you can also provide this as a file. For more information see wgc router compose to build the file locally for development or wgc router fetch to download the latest production version.
3.Custom Go modules. It is unlikely that we will provide every possible feature as an in-built functionality. For advanced use cases or for more control, you can build Go modules and compile your own router in a few commands. If you are unsure 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 Passing secrets as environment variables and using the config to store everything else is a common and pragmatic approach.
Environment Variables
Many configuration options can be set as environment variables. For a complete list of options, please look at the config file.
Environment variable
Description
Default
Required
FEDERATED_GRAPH_NAME
The name of the federated graph that the router represents. This is the name of the graph you've created with wgc federated-graph create. (Can be empty when providing a static router configuration through ROUTER_CONFIG_PATHbut will disable the default telemetry stack)
""
GRAPH_API_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)
""
CONTROLPLANE_URL
The controlplane url.
"https://cosmo-otel.wundergraph.com"
DEFAULT_TELEMETRY_ENDPOINT
The address to the OTEL collector used when no exporters are defined e.g http://localhost:4318​
"https://cosmo-otel.wundergraph.com"
TELEMETRY_SERVICE_NAME
The OTEL service name.
wundergraph-cosmo-router
TRACING_ENABLED
Enables OTEL tracing instrumentation
true
TRACING_SAMPLING_RATE
The sampling rate. Value between 0-1.
1
TRACING_BATCH_TIMEOUT
The maximum delay allowed before spans are exported.
10s
METRICS_OTLP_ENABLED
Enables OTEL metrics instrumentation
true
PROMETHEUS_ENABLED
Enables prometheus metrics support
true
PROMETHEUS_HTTP_PATH
The HTTP path where metrics are exposed.
"/metrics"
PROMETHEUS_LISTEN_ADDR
The prometheus listener address.
"127.0.0.1:8088"
CORS_ALLOW_HEADERS
Allowed CORS headers.
Origin,Content-Length,Content-Type
CORS_ALLOW_ORIGINS
Allowed CORS origins.
*
CORS_ALLOW_METHODS
Allowed CORS methods.
HEAD,GET,POST
CORS_ALLOW_CREDENTIALS
Allowed CORS credential mode.
true
CORS_MAX_AGE
Maximum time the results of a preflight request can be cached.
5s
LISTEN_ADDR
The server listener address.
localhost:3002
PLAYGROUND_ENABLED
Enables the GraphQL playground on ($LISTEN_ADDR/)
true
INTROSPECTION_ENABLED
Enables the introspection endpoint.
true
LOG_LEVEL
Configures the log level.
info
JSON_LOG
Enables JSON logging.
true
DEV_MODE
Enables pretty log output and allows to use Advanced Request Tracing (ART) without further security protection.
false
SHUTDOWN_DELAY
Maximum time in seconds the server has to shutdown gracefully. Should be higher than GRACE_PERIOD_SECONDS
30s
GRACE_PERIOD
Maximum time in seconds the server has between schema updates to gracefully close client connections. Should be smaller than SHUTDOWN_DELAY_SECONDS
20s
POLL_INTERVAL
The interval of how often the router should check for new schema updates.
10s
HEALTH_CHECK_PATH
Health check path. Returns 200 when the router is alive.
"/health"
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. Return 200 when the router is alive.
"/health/live"
ROUTER_CONFIG_PATH
The path to the Router execution config to test a graph composition locally without a connection to the control plane or CDN. You can obtain the config by using the fetch-config command. The file must be valid JSON. Polling is disabled once you pass a custom path.
""
CONFIG_PATH
The path to the router configuration.
"config.yaml"
REQUIRE_AUTHENTICATION
Whether to require all requests to the router to be authenticated
false
LOCALHOST_FALLBACK_INSIDE_DOCKER
Enable fallback for requests that fail to connect to localhost while running in Docker
true
ENGINE_ENABLE_REQUEST_TRACING
Enables Advanced-Request-Tracing (ART).
true
CDN_URL
Sets the URL to use for the Cosmo CDN.
​https://cosmo-cdn.wundergraph.com​
CDN_CACHE_SIZE
Sets the size for the in-memory cache used by the CDN client.
100MB
Intervals, timeouts, and delays are specified in Go duration syntax e.g 1s, 5m or 1h.
Sizes can be specified in 2MB, 1mib.
Config file
Instead of using environment variables, you can also create a config.yaml in the working directory of the router. Here you can find all configuration options with the corresponding defaults.
version: "1"
​
# General router options
graph:
  name: "production"
  token: ""
​
log_level: "info"
listen_addr: "localhost:3002"
controlplane_url: "https://cosmo-cp.wundergraph.com"
playground_enabled: true
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: ""
​
cors:
  allow_origins: ["*"]
  allow_methods:
    - HEAD
    - GET
    - POST
  allow_headers:
    - Origin
    - Content-Length
    - Content-Type
  allow_credentials: true
  max_age_minutes: 5m
​
# Config for custom modules   
# 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
    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
​
  # 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: []
​
# Config for custom modules   
# See "https://cosmo-docs.wundergraph.com/router/custom-modules" for more information   
modules:
  myModule:
    # Arbitrary values, unmarshalled by the module
    value: 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
​
# 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-.*
​
# 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:
  require_authentication: false # Set to true to disable requests without authentication
     
cdn:
   url: https://cosmo-cdn.wundergraph.com
   cache_size: 100MB
You can also point to a custom config file by overwriting CONFIG_PATH environment variable.
Values specified in the config file have precedence over Environment variables. This also includes empty values so only specify values that should be overwritten.
Expand environment variables
You can expand environment variables in the file like this:
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.

Environment variable	Description	Default
FEDERATED_GRAPH_NAME	The name of the federated graph that the router represents. This is the name of the graph you've created with `wgc federated-graph create`. (Can be empty when providing a static router configuration through `ROUTER_CONFIG_PATH`but will disable the default telemetry stack)	""
GRAPH_API_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)	""
CONTROLPLANE_URL	The controlplane url.	"https://cosmo-otel.wundergraph.com"
DEFAULT_TELEMETRY_ENDPOINT	The address to the OTEL collector used when no exporters are defined e.g `http://localhost:4318`	"https://cosmo-otel.wundergraph.com"
TELEMETRY_SERVICE_NAME	The OTEL service name.	wundergraph-cosmo-router
TRACING_ENABLED	Enables OTEL tracing instrumentation	true
TRACING_SAMPLING_RATE	The sampling rate. Value between 0-1.	1
TRACING_BATCH_TIMEOUT	The maximum delay allowed before spans are exported.	10s
METRICS_OTLP_ENABLED	Enables OTEL metrics instrumentation	true
PROMETHEUS_ENABLED	Enables prometheus metrics support	true
PROMETHEUS_HTTP_PATH	The HTTP path where metrics are exposed.	"/metrics"
PROMETHEUS_LISTEN_ADDR	The prometheus listener address.	"127.0.0.1:8088"
CORS_ALLOW_HEADERS	Allowed CORS headers.	Origin,Content-Length,Content-Type
CORS_ALLOW_ORIGINS	Allowed CORS origins.	*
CORS_ALLOW_METHODS	Allowed CORS methods.	HEAD,GET,POST
CORS_ALLOW_CREDENTIALS	Allowed CORS credential mode.	true
CORS_MAX_AGE	Maximum time the results of a preflight request can be cached.	5s
LISTEN_ADDR	The server listener address.	localhost:3002
PLAYGROUND_ENABLED	Enables the GraphQL playground on (`$LISTEN_ADDR/`)	true
INTROSPECTION_ENABLED	Enables the introspection endpoint.	true
LOG_LEVEL	Configures the log level.	info
JSON_LOG	Enables JSON logging.	true
DEV_MODE	Enables pretty log output and allows to use Advanced Request Tracing (ART) without further security protection.	false
SHUTDOWN_DELAY	Maximum time in seconds the server has to shutdown gracefully. Should be higher than `GRACE_PERIOD_SECONDS`	30s
GRACE_PERIOD	Maximum time in seconds the server has between schema updates to gracefully close client connections. Should be smaller than `SHUTDOWN_DELAY_SECONDS`	20s
POLL_INTERVAL	The interval of how often the router should check for new schema updates.	10s
HEALTH_CHECK_PATH	Health check path. Returns `200` when the router is alive.	"/health"
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. Return 200 when the router is alive.	"/health/live"
ROUTER_CONFIG_PATH	The path to the Router execution config to test a graph composition locally without a connection to the control plane or CDN. You can obtain the config by using the fetch-config command. The file must be valid JSON. Polling is disabled once you pass a custom path.	""
CONFIG_PATH	The path to the router configuration.	"config.yaml"
REQUIRE_AUTHENTICATION	Whether to require all requests to the router to be authenticated	false
LOCALHOST_FALLBACK_INSIDE_DOCKER	Enable fallback for requests that fail to connect to localhost while running in Docker	true
ENGINE_ENABLE_REQUEST_TRACING	Enables Advanced-Request-Tracing (ART).	true
CDN_URL	Sets the URL to use for the Cosmo CDN.	https://cosmo-cdn.wundergraph.com
CDN_CACHE_SIZE	Sets the size for the in-memory cache used by the CDN client.	100MB

Last modified 8d ago