Configuration

Learn how to configure your router.

The router provides three different ways of customization:

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

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

  3. 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 VariableYAMLRequiredDescriptionDefault Value

LISTEN_ADDR

listen_addr

The server listener address.

localhost:3002

CONTROLPLANE_URL

controlplane_url

The controlplane url. Not required when a static execution config is provided.

PLAYGROUND_ENABLED

playground_enabled

Enables the GraphQL playground on ($LISTEN_ADDR/)

true

PLAYGROUND_PATH

playground_path

The path where the playground is served

"/"

INTROSPECTION_ENABLED

introspection_enabled

true

QUERY_PLANS_ENABLED

query_plans_enabled

The Router can return Query plans as part of the response, which might be useful to understand the execution.

true

LOG_LEVEL

log_level

debug / info / warning / error / fatal / panic

info

JSON_LOG

json_log

Render the log output in JSON format (true) or human readable (false)

true

SHUTDOWN_DELAY

shutdown_delay

Maximum time in seconds the server has to shutdown gracefully. Should be higher than 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

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

Access Logs

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

Environment VariableYAMLRequiredDescriptionDefault Value

access_logs

Enable the access logs. The access logs are used to log the incoming requests. By default, the access logs are enabled and logged to the standard output.

ACCESS_LOGS_ENABLED

access_logs.enabled

Enable the access logs. The access logs are used to log the incoming requests. By default, the access logs are enabled and logged to the standard output.

true

access_logs.buffer

The buffer is used to buffer the logs before writing them to the output.

ACCESS_LOGS_BUFFER_ENABLED

access_logs.buffer.enabled

Enable the buffer.

false

ACCESS_LOGS_BUFFER_SIZE

access_logs.buffer.size

The size of the buffer. The default value is 256KB.

ACCESS_LOGS_FLUSH_INTERVAL

access_logs.buffer.flush_interval

The interval at which the buffer is flushed. The period is specified as a string with a number and a unit, e.g. 10ms, 1s, 1m, 1h. The supported units are 'ms', 's', 'm', 'h'.

access_logs.output

The log destination. The supported destinations are stdout and file. Only one option can be enabled. The default destination is stdout.

ACCESS_LOGS_OUTPUT_STDOUT_ENABLED

access_logs.output.stdout.enabled

true

ACCESS_LOGS_OUTPUT_FILE_ENABLED

access_logs.output.file.enabled

false

ACCESS_LOGS_FILE_OUTPUT_PATH

access_logs.output.file.path

The path to the log file. The path is used to specify the path to the log file.

access_logs.fields

The fields to add to the logs. The fields are added to the logs as key-value pairs.

[]

access_logs.fields.key

The key of the field to add to the logs.

access_logs.fields.default

The default value of the field. If the value is not set, value_from is used. If both value and value_from are set, value_from has precedence and in case of a missing value_from, the default value is used.

access_logs.value_from

Defines a source for the field value e.g. from a request header. If both default and value_from are set, value_from has precedence.

access_logs.fields.value_from.request_header

The name of the request header from which to extract the value. The value is only extracted when a request context is available otherwise the default value is used.

access_logs.fields.value_from.context_field

The field name of the context from which to extract the value. The value is only extracted when a context is available otherwise the default value is used. One of: [ "operation_name", "operation_type", "operation_service_names", "operation_hash", "persisted_operation_sha256", "operation_sha256", "response_error_message", "graphql_error_codes", "graphql_error_service_names", "operation_parsing_time", "operation_validation_time", "operation_planning_time", "operation_normalization_time" ]

Example YAML config:

config.yaml
version: "1"

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

Telemetry

Graph

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

Environment VariableYAMLRequiredDescriptionDefault 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_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 VariableYAMLRequiredDescriptionDefault 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 VariableYAMLRequiredDescriptionDefault 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 VariableYAMLRequiredDescriptionDefault 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 VariableYAMLRequiredDescriptionDefault Value

CLUSTER_NAME

name

The logical name of the router cluster. The name is used for analytic purpose.

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

TELEMETRY_SERVICE_NAME

service_name

cosmo-router

resource_attributes

The resource attributes to add to OTEL metrics and traces. The resource attributes identify the entity producing the traces and metrics.

resource_attributes.key

The key of the attribute.

resource_attributes.value

The value of the attribute.

attributes

The attributes to add to OTEL metrics and traces. Because Prometheus metrics rely on the OpenTelemetry metrics, the attributes are also added to the Prometheus metrics.

[]

attributes.key

The key of the attribute.

attributes.default

The value of the attribute.

attributes.value_from

Defines a source for the attribute value e.g. from a request header. If both default and value_from are set, value_from has precedence.

attributes.value_from.request_header

The name of the request header from which to extract the value. The value is only extracted when a request context is available otherwise the default value is used. Don't forget to add the header to your CORS settings.

Example YAML config:

config.yaml
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 VariableYAMLRequiredDescriptionDefault Value

TRACING_ENABLED

enabled

true

TRACING_SAMPLING_RATE

sampling_rate

The sampling rate for the traces. The value must be between 0 and 1. If the value is 0, no traces will be sampled. If the value is 1, all traces will be sampled.

1

TRACING_PARENT_BASED_SAMPLER

parent_based_sampler

Enable the parent-based sampler. The parent-based sampler is used to sample the traces based on the parent trace.

true

TRACING_BATCH_TIMEOUT

The maximum delay allowed before spans are exported.

10s

TRACING_EXPORT_GRAPHQL_VARIABLES

export_graphql_variables

Export GraphQL variables as span attribute. Variables may contain sensitive data.

false

with_new_root

Starts the root span always at the router.

false

Example YAML config:

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

Environment VariableYAMLRequiredDescriptionDefault Value

disabled

bool

exporter

one of: http,grpc

endpoint

path

headers

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

trace_context

true

jaeger

b3

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

OTLP

Environment VariableYAMLRequiredDescriptionDefault Value

METRICS_OTLP_ENABLED

enabled

Enables OTEL metrics instrumentation

true

METRICS_OTLP_ROUTER_RUNTIME

router_runtime

true

METRICS_OTLP_EXCLUDE_METRICS

exclude_metrics

The metrics to exclude from the OTEL metrics. Accepts a list of Go regular expressions. Use https://regex101.com/ to test your regular expressions.

[]

METRICS_OTLP_EXCLUDE_METRIC_LABELS

exclude_metric_labels

The metric labels to exclude from the OTEL metrics. Accepts a list of Go regular expressions. Use https://regex101.com/ to test your regular expressions.

[]

Attributes

YAMLRequiredDescriptionDefault Value

attributes

The attributes to add to OTLP Metrics and Prometheus.

[]

attributes.key

The key of the field.

attributes.default

The default value of the field. If the value is not set, value_from is used. If both value and value_from are set, value_from has precedence and in case of a missing value_from, the default value is used.

attributes.value_from

Defines a source for the field value e.g. from a request header or request context. If both default and value_from are set, value_from has precedence.

attributes.value_from

Defines a source for the field value e.g. from a request header or request context. If both default and value_from are set, value_from has precedence.

attributes.value_from.request_header

The name of the request header from which to extract the value. The value is only extracted when a request context is available otherwise the default value is used.

attributes.value_from.context_field

The field name of the context from which to extract the value. The value is only extracted when a context is available otherwise the default value is used.

One of: ["operation_service_names", "graphql_error_codes", "graphql_error_service_names", "operation_sha256"]

Example YAML config:

config.yaml
# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:
  metrics:
    otlp:
      enabled: true
      router_runtime: 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 VariableYAMLRequiredDescriptionDefault 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:
  metrics:
    # Expose OpenTelemetry metrics for scraping
    prometheus:
      enabled: true
      path: "/metrics"
      listen_addr: "127.0.0.1:8088"
      exclude_metrics: []
      exclude_metric_labels: []

Exporter

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

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

GRAPHQL_METRICS_ENABLED

enabled

true

GRAPHQL_METRICS_COLLECTOR_ENDPOINT

collector_endpoint

Default endpoint

Example YAML config:

config.yaml
version: "1"

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

CORS

Environment VariableYAMLRequiredDescriptionDefault 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:

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

Cache Control Policy

Configure your cache control policy. More information on this feature can be found here: #cache-control-policy

Environment VariableYAMLRequiredDescriptionDefault 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:

config.yaml
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:

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/responses to/from "all" Subgraphs. These will be applied globally in the graph

Environment VariableYAMLRequiredDescriptionDefault Value

request

List of Request Header Rules

response

List of Response Header Rules

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-.*
      - op: "set"
        name: "X-API-Key"
        value: "my-secret-value"
    response:
      - op: "propagate"
        algorithm: "append"
        named: "X-Custom-Header"

Request Header Rule

Apply to requests to specific Subgraphs.

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

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

op

oneof=propagate

algorithm

oneof=first_write, last_write, append

matching

matching is the regex to match the header name against. This

named

named is the exact header name to match

default

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

rename

renames the header's key to the provided value

Example YAML config:

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

The configuration for the storage providers. Storage providers can be used to store the persisted operations and the execution config.

Example YAML config:

version: "1"

storage_providers:
  cdn:
    - url: https://cosmo-cdn.wundergraph.com
      id: cdn
  s3:
    - id: "s3"
      endpoint: "localhost:10000"
      bucket: "cosmo"
      access_key: "key"
      secret_key: "secret"
      region: us-east-1
      secure: false
  redis:
    - id: "my-redis"
      url: "redis://localhost:6379"

Storage Provider Yaml Options

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

Environment VariableYAMLRequiredDescriptionDefault Value

cdn

CDN storage provider.

cdn.id

Unique ID of the provider. It is used as reference in persisted_operations and execution_config sections.

cdn.url

"https://cosmo-cdn.wundergraph.com"

redis

Redis storage provider

redis.id

Unique ID of the provider. It is used as a reference in the automatic_persisted_queries section

redis.url

Redis url, containing port and auth information if necessary

s3

S3 storage provider

s3.id

Unique ID of the privider. It is used as reference in persisted_operations and execution_config sections.

s3.endpoint

The endpoint of the S3 bucket. The endpoint is used to specify the endpoint of the S3 bucket.

s3.bucket

The name of the S3 bucket. The S3 bucket is used to store the execution config.

s3.access_key

The access key of the S3 bucket. The access key ID is used to authenticate with the S3 bucket.

s3.secret_key

The secret key of the S3 bucket. The secret access key is used to authenticate with the S3 bucket.

s3.region

The region of the S3 bucket. The region is used to specify the region of the S3 bucket

s3.secure

Enables https in the provided endpoint. Must be set to false when accessing http endpoints

true

Persisted Operations

The configuration for the persisted operations allows you to maintain a fixed set of GraphQL operations that can be queried against the router without exposing your entire graph to the public. This approach enhances security and performance.

Example YAML config:

version: "1"

persisted_operations:
  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 VariableYAMLRequiredDescriptionDefault 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

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.

Environment VariableYAMLRequiredDescriptionDefault 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:

version: "1"

execution_config:
  storage:
    provider_id: s3
    object_path: /prod

Subgraph Request Rules

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

Environment VariableYAMLRequiredDescriptionDefault Value

execution_config

The configuration for the execution config.

file

The configuration for the execution config file. The config file is used to load the execution config from the local file system. The file has precedence over the storage provider.

EXECUTION_CONFIG_FILE_PATH

file.path

The path to the execution config file. The path is used to load the execution config from the local file system.

EXECUTION_CONFIG_FILE_WATCH

file.watch

Enable the watch mode. The watch mode is used to watch the execution config file for changes. If the file changes, the router will reload the execution config without downtime.

"true"

execution_config.storage

The storage provider for the execution config. Only one provider can be active. When no provider is specified, the router will fallback to the Cosmo CDN provider to download the execution config.

EXECUTION_CONFIG_STORAGE_PROVIDER_ID

execution_config.storage.provider_id

The ID of the storage provider. The ID must match the ID of the storage provider in the 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.

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
  all: # Rules are applied to all subgraph requests.
    # Subgraphs transport options
    request_timeout: 60s
    dial_timeout: