Cloud Router Configuration
Learn how to configure cloud routers in GraphOS Studio
After you create a cloud supergraph, you can manage its router configuration from the Cloud Router page in GraphOS Studio.
The General tab shows the following information:
The URL of your router's GraphQL endpoint
Every cloud router's URL is on a subdomain of
apollographos.net
.
Your router's current status and launch history
From the Configuration tab, you can manage the following:
Your router's YAML-based configuration
Managing secrets
You can store secret string values that you can then use in your router's YAML configuration. For example, you might store an authorization token that the router needs to include in each of its request to a subgraph.
To add a new secret, click Save a secret.
In the dialog that appears, enter a name and value for your secret. You can't view a secret's value after you save it, so make sure that the value is correct before saving. When you're ready, click Save secret.
Your secret is encrypted and stored. You can then use the secret's value in your router's YAML configuration.
The following example YAML configuration uses the value of a secret named MY_SECRET
:
1headers:
2 all:
3 request:
4 - insert:
5 name: 'subgraph-token'
6 value: '${env.MY_SECRET}'
Router configuration YAML
You can configure your router's behavior in Router configuration YAML on the Cloud Router tab or page.
On the Serverless plan, you can configure:
HTTP headers that the router sends to your subgraphs
CORS rules for browser-based applications connecting to the router
Subgraph error inclusion to expose subgraph errors to querying clients (including the Apollo Explorer)
Introspection to allow resolving introspection queries.
Dedicated and Enterprise plans offer a wider variety of configurations.
If you require more advanced router customization,
to learn about your about Dedicated and Enterprise plan options.HTTP header rules
You can configure which HTTP headers your router includes in its requests to each of your subgraphs. You can define per-subgraph header rules, along with rules that apply to all subgraphs.
You define header rules in your Router configuration YAML, like so:
1# ...other configuration...
2headers:
3 all: # Header rules for all subgraphs
4 request:
5 - propagate:
6 matching: ^upstream-header-.*
7 - remove:
8 named: 'x-legacy-account-id'
9 subgraphs:
10 products: # Header rules for just the products subgraph
11 request:
12 - insert:
13 name: 'router-subgraph-name'
14 value: 'products'
Supported header rules
Cloud routing supports the following types of header rules:
propagate
Enables you to selectively pass along headers that were included in the client's request to the router.
You can specify which headers to propagate based on a matching regular expression pattern:
1- propagate:
2 matching: .*
Content-Length
, when propagating by pattern.Alternatively, you can provide a static string via the named
option. These named
configurations have additional flexibility, because they support the following options:
default
: A value to set if no value was sent by the clientrename
: Renames the header's key to the provided value
1- propagate:
2 named: 'x-user-id'
3 default: 'abc123'
4 rename: 'account-id'
remove
Enables you to selectively remove headers that were included in the client's request to the router. Like propagate
, this option can match either a static string or a regular expression.
1# Do not send this subgraph the "Cookie" header.
2- remove:
3 named: 'Cookie'
4- remove:
5 # Remove headers that include the legacy 'x-' prefix.
6 matching: ^x-.*$
insert
Enables you to add custom headers to requests going to a specific subgraph. These headers are always static strings that originate in the router, instead of originating in the client.
1- insert:
2 name: 'sent-from-our-apollo-router'
3 value: 'indeed'
Rule ordering
Header rules are applied in the same order they're declared, and later rules can override the effects of earlier rules. Consider this example:
❌
1headers:
2 all:
3 request:
4 - remove:
5 named: 'test'
6 - propagate:
7 matching: .*
In this example, first any header named test
is removed from the list of headers to propagate. However, the list of headers to propagate is currently empty! Next, the propagate
rule adds all headers to the propagation list, including test
.
To correctly remove a header from the propagation list, make sure to define your remove
rule after any propagate
rules:
✅
1headers:
2 all:
3 request:
4 - propagate:
5 matching: .*
6 - remove:
7 named: 'test'
With this ordering, first all headers are added to the propagation list, then the test
header is removed.
Example
Here's a complete example that demonstrates all supported headers
configuration options:
1headers:
2 # Header rules for all subgraphs
3 all:
4 request:
5 # Propagate matching headers
6 - propagate:
7 matching: ^upstream-header-.*
8 # Propagate matching headers
9 - propagate:
10 named: 'some-header'
11 default: 'default-value'
12 rename: 'destination-header'
13 # Remove the "x-legacy-account-id" header
14 - remove:
15 named: 'x-legacy-account-id'
16 # Remove matching headers
17 - remove:
18 matching: ^x-deprecated-.*
19 # Insert the 'my-company' header
20 - insert:
21 name: 'my-company'
22 value: 'acme'
23 # Subgraph-specific header rules
24 subgraphs:
25 products:
26 request:
27 # Calls to the products subgraph have the "router-subgraph-name" header set to `products`.
28 - insert:
29 name: 'router-subgraph-name'
30 value: 'products'
31 accounts:
32 request:
33 # Calls to the accounts subgraph have the "router-subgraph-name" header set to `accounts`.
34 - insert:
35 name: 'router-subgraph-name'
36 value: 'accounts'
CORS settings
By default, the router enables only GraphOS Studio to initiate browser connections to it. If your supergraph serves data to other browser-based applications, you need to do one of the following in the cors
section of your Router configuration YAML:
Add the origins of those web applications to the router's list of allowed
policies
.Use this option if there is a known, finite list of web applications that consume your cloud supergraph.
Add a regular expression that matches the origins of those web applications to the router's list of allowed
policies
.This option comes in handy if you want to match origins against a pattern, see the example below that matches subdomains of a specific namespace.
Enable the
allow_any_origin
option.Use this option if your supergraph is a public API with arbitrarily many web app consumers.
With this option enabled, the router sends the wildcard (
*
) value for theAccess-Control-Allow-Origin
header. This enables any website to initiate browser connections to it (but they can't provide cookies or other credentials).
You must use policies with
origins
+match_origins
if clients need to authenticate their requests with cookies.
The following snippet includes an example of each option (use either allow_any_origin
, or policies
with specific origins):
1cors:
2 # Set to true to allow any origin
3 # (Defaults to false)
4 allow_any_origin: true
5
6 # List of CORS policies with specific origins and settings
7 # (Ignored if allow_any_origin is true)
8 # (Defaults to allowing GraphOS Studio: `https://studio.apollographql.com`)
9 #
10 # An origin is a combination of scheme, hostname and port.
11 # It does not have any path section, so no trailing slash.
12 policies:
13 - origins:
14 - https://www.your-app.example.com
15 - https://studio.apollographql.com # Keep this so GraphOS Studio can run queries against your router
16 - origins:
17 - https://api.example.com
18 match_origins:
19 - 'https://([a-z0-9]+[.])*api[.]example[.]com' # any host that uses https and ends with .api.example.com
You can also disable CORS entirely by setting policies
to an empty list:
1cors:
2 policies: []
Passing credentials
If your router requires requests to include a user's credentials (for example, via cookies), you need to modify your CORS configuration to tell the browser those credentials are allowed.
You can enable credentials with CORS by setting the Access-Control-Allow-Credentials
HTTP header to true
.
origins
to support credentialed requests. If your router configuration specifies allow_any_origin
, your browser will refuse to send credentials.To allow browsers to pass credentials to your router, set allow_credentials
to true
, like so:
1cors:
2 policies:
3 - origins:
4 - https://www.your-app.example.com
5 - https://studio.apollographql.com
6 allow_credentials: true
For examples of sending cookies and authorization headers from Apollo Client, see Authentication.
All cors
options
The following snippet shows all CORS configuration defaults for your router:
1#
2# CORS (Cross Origin Resource Sharing)
3#
4cors:
5 # Set to true to allow any origin
6 allow_any_origin: false
7
8 # Global settings that apply to all policies unless overridden
9 allow_credentials: false
10 methods:
11 - GET
12 - POST
13 - OPTIONS
14 allow_headers: []
15 expose_headers: []
16 max_age: null
17
18 # List of CORS policies with specific origins and settings
19 # (Ignored if allow_any_origin is set to true)
20 #
21 # An origin is a combination of scheme, hostname and port.
22 # It does not have any path section, so no trailing slash.
23 policies:
24 - origins:
25 - https://studio.apollographql.com # Keep this so GraphOS Studio can still run queries against your router
26 # Each policy can override global settings:
27 # allow_credentials: false # Override global setting for this policy
28 # methods: [GET, POST] # Override global methods for this policy
29 # allow_headers: [] # Override global headers for this policy
30 # expose_headers: [] # Override global expose headers for this policy
31 # max_age: "3600s" # Override global max age for this policy
32 # match_origins: # Regex patterns for dynamic origin matching
33 # - "^https://.*\\.example\\.com$"
Response Vary
header
A plugin may set a response Vary
header. If, after all plugins are processed, there is no response Vary
header, then the router will add one with a value of origin
.
Subgraph error inclusion
By default, your cloud supergraph redacts the details of subgraph errors in its responses to clients. The router instead returns a default error with the following message:
1Subgraph errors redacted
This redaction prevents potential leaks of sensitive information to clients.
If you instead want to propagate subgraph errors to clients, you can add the include_subgraph_errors
key to your router's YAML configuration, like so:
1include_subgraph_errors:
2 all: true # Propagate errors from all subraphs
3 subgraphs:
4 products: false # Do not propagate errors from the products subgraph
Any configuration under the subgraphs
key takes precedence over configuration under the all
key. In the example above, subgraph errors are included from all subgraphs except the products
subgraph.
Introspection
By default, your cloud supergraph does not resolve introspection queries. You can enable introspection like so:
1# Do not enable introspection for production workloads!
2supergraph:
3 introspection: true