Distributed caching for the Apollo Router

If you have multiple Apollo Router instances, those instances can share a Redis-backed cache for their query plans and automatic persisted queries (APQ). This means that if any of your router instances caches a particular value, all of your instances can look up that value to significantly improve responsiveness. For more details on query plans and APQ, see the article on in-memory caching.

Prerequisites

To use this feature:

• You must have a Redis cluster (or single instance) that your router instances can communicate with.
• You must have a GraphOS Enterprise plan and connect your router to GraphOS.

How it works

Whenever a router instance requires a query plan or APQ query string to resolve a client operation:

1. The router instance checks its own in-memory cache for the required value and uses it if found.
2. If not found, the router instance then checks the distributed Redis cache for the required value and uses it if found. It also then replicates the found value in its own in-memory cache.
3. If not found, the router instance generates the required query plan or requests the full operation string from the client for APQ.
4. The router instance stores the obtained value in both the distributed cache and its in-memory cache.

Redis URL configuration

The distributed caching configuration must contain one or more URLs using different schemes depending on the expected deployment:

• redis - TCP connected to a centralized server.
• rediss - TLS connected to a centralized server.
• redis-cluster - TCP connected to a cluster.
• rediss-cluster - TLS connected to a cluster.
• redis-sentinel - TCP connected to a centralized server behind a sentinel layer.
• rediss-sentinel - TLS connected to a centralized server behind a sentinel layer.

The URLs must have the following format:

One node

1
redis|rediss :// [[username:]password@] host [:port][/database]

Example: redis://localhost:6379

Clustered

1
redis|rediss[-cluster] :// [[username:]password@] host [:port][?[node=host1:port1][&node=host2:port2][&node=hostN:portN]]

or, if configured with multiple URLs:

1
[
2
  "redis|rediss[-cluster] :// [[username:]password@] host [:port]",
3
  "redis|rediss[-cluster] :// [[username:]password@] host1 [:port1]",
4
  "redis|rediss[-cluster] :// [[username:]password@] host2 [:port2]"
5
]

Sentinel

1
redis|rediss[-sentinel] :// [[username1:]password1@] host [:port][/database][?[node=host1:port1][&node=host2:port2][&node=hostN:portN]
2
                            [&sentinelServiceName=myservice][&sentinelUsername=username2][&sentinelPassword=password2]]

or, if configured with multiple URLs:

1
[
2
  "redis|rediss[-sentinel] :// [[username:]password@] host [:port][/database][?[&sentinelServiceName=myservice][&sentinelUsername=username2][&sentinelPassword=password2]]",
3
  "redis|rediss[-sentinel] :// [[username1:]password1@] host [:port][/database][?[&sentinelServiceName=myservice][&sentinelUsername=username2][&sentinelPassword=password2]]"
4
]

Router configuration

Distributed query plan caching

To enable distributed caching of query plans, add the following to your router's YAML config file:

1
supergraph:
2
  query_planning:
3
    cache:
4
      redis: 
5
        urls: ["redis://..."] 

The value of urls is a list of URLs for all Redis instances in your cluster.

All query plan cache entries will be prefixed with plan. within the distributed cache.

Distributed APQ caching

To enable distributed caching of automatic persisted queries (APQ), add the following to your router's YAML config file:

1
apq:
2
  router:
3
    cache:
4
      redis: 
5
        urls: ["redis://..."] 

The value of urls is a list of URLs for all Redis instances in your cluster.

All APQ cache entries will be prefixed with apq followed by a null byte character (referenced by the escape sequence \0 in most programming languages) within the distributed cache.

Common Redis configuration

Redis configuration is done in the same way for APQ caching, query plan caching and entity caching.

1
supergraph:
2
  query_planning:
3
    cache:
4
      redis: 
5
        urls: ["redis://..."] 
6
        username: admin/123 # Optional, can be part of the urls directly, mainly useful if you have special character like '/' in your password that doesn't work in url. This field takes precedence over the username in the URL
7
        password: admin # Optional, can be part of the urls directly, mainly useful if you have special character like '/' in your password that doesn't work in url. This field takes precedence over the password in the URL
8
        timeout: 5ms # Optional, by default: 2ms
9
        ttl: 24h # Optional
10
        namespace: "prefix"  # Optional
11
        #tls:
12
        required_to_start: false # Optional, defaults to false
13
        reset_ttl: true # Optional, defaults to true

Timeout

Connecting and sending commands to Redis are subject to a timeout, set by default to 2ms, that can be overriden.

TTL

The ttl option defines the default global expiration for Redis entries. For APQ caching, the default is no expiration, while for query plan caching, the default expiration is set to 30 days.

Namespace

When using the same Redis instance for multiple puposes, the namespace option defines a prefix for all the keys defined by the router.

TLS

For Redis TLS connections, you can set up a client certificate or override the root certificate authority by configuring tls in your router's YAML config file. For example:

1
apq:
2
  router:
3
    cache:
4
      redis:
5
        urls: [ "rediss://redis.example.com:6379" ]
6
        tls:
7
          certificate_authorities: ${file./path/to/ca.crt}
8
          client_authentication:
9
            certificate_chain: ${file./path/to/certificate_chain.pem}
10
            key: ${file./path/to/key.pem}

Required to start

When active, the required_to_start option will prevent the Router from starting if it cannot connect to Redis. By default, the Router will still start without a connection to Redis, which would result in only using the in-memory cache for APQ and query planning, and entity caching sending the requests to subgraphs undisturbed.

Reset TTL

When this option is active, accessing a cache entry in Redis will reset its expiration.