☰
Navigation :

Route to GraphQL servers

Set up routes to your GraphQL APIs so that clients can send GraphQL queries to your endpoints.

Define routes for GraphQL destinations

Create a RouteTable resource with a graphql destination to reference the GraphQLSchema resource. This route table ensures that all GraphQL queries to a specific path are now handled by the GraphQL server in the gateway. For more information about configuring route tables, see Process and route traffic.

Before you begin: Follow the other GraphQL guides to define an ApiDoc with your GraphQL schema and execute GraphQL requests.

North-south routing

Route requests from clients that are external to your Gloo Gateway setup.

apiVersion: networking.gloo.solo.io/v2
kind: RouteTable
metadata:
  name: 
  namespace: 
spec:
  # Host(s) to apply the route table to
  hosts:
  - 
  http:
  - graphql:
      # Reference to your GraphQLSchema resource
      schema:
        clusterName: 
        name: 
        namespace: 
      options:
        # Include information about the request an response in the Envoy debug logs,
        # which can be helpful for debugging GraphQL. Defaults to false.
        logSensitiveInfo: 
    # Specific matchers for the incoming requests, such as a URI prefix (path matching)
    matchers:
    - uri:
        prefix: 
  virtualGateways:
  - name:

In this example, the reference to the bookinfo-rest-graphqlschema resource ensures that all traffic to www.example.com/graphql is handled by the GraphQL resolvers defined in bookinfo-rest-resolvermap.

apiVersion: networking.gloo.solo.io/v2
kind: RouteTable
metadata:
  name: graphql-bookinfo
  namespace: bookinfo
spec:
  hosts:
  - www.example.com
  http:
  - name: graphql-bookinfo
    labels: 
      route: graphql-bookinfo
      graphql: "true"
    graphql:
      schema:
        clusterName: $CLUSTER_NAME
        name: bookinfo-rest-graphqlschema
        namespace: bookinfo
    matchers:
    - uri:
        prefix: /graphql
  virtualGateways:
  - name: istio-ingressgateway

To test routing to the server:

  1. Get the external IP address of your ingress gateway. 

    export INGRESS_GW_IP=$(kubectl get svc -n gloo-mesh-gateways istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
echo $INGRESS_GW_IP

    export INGRESS_GW_IP=$(kubectl get svc -n gloo-mesh-gateways istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
echo $INGRESS_GW_IP

  2. Send a request with a query to the GraphQL endpoint to verify that the request is successfully resolved by the gateway. This example command sends the request to the /graphql path and includes a query for the Bookinfo example. 

    curl -vik --resolve www.example.com:80:${INGRESS_GW_IP} http://www.example.com:80/graphql \
-d '{"query":"query { productsForHome { title ratings {reviewer numStars}} }"}'

    curl -vik --resolve www.example.com:443:${INGRESS_GW_IP} https://www.example.com:443/graphql \
-d '{"query":"query { productsForHome { title ratings {reviewer numStars}} }"}'

East-west routing

Route requests from clients that are internal to your Gloo Gateway setup, such as if you use Gloo Mesh. Note that because the GraphQL destination references a GraphQLSchema resource instead of a service, the value of hosts is arbitrary, as long as the request from the client app matches the host. 

apiVersion: networking.gloo.solo.io/v2
kind: RouteTable
metadata:
  name: 
  namespace: 
spec:
  # Internal hostname that you want to assign to the GraphQL endpoint
  hosts:
  - 
  # Applies to requests sent by the client app
  workloadSelectors:
  - selector:
      labels:
        app: 
  http:
  - graphql:
      # Reference to your GraphQLSchema resource
      schema:
        clusterName: 
        name: 
        namespace: 
      options:
        # Include information about the request an response in the Envoy debug logs,
        # which can be helpful for debugging GraphQL. Defaults to false.
        logSensitiveInfo: 
    # Specific matchers for the incoming requests, such as a URI prefix (path matching)
    matchers:
    - uri:
        prefix:

In this example, the reference to the bookinfo-rest-graphqlschema resource ensures that all traffic from client-app to graphql-bookinfo.internal.com/graphql is handled by the GraphQL resolvers defined in bookinfo-rest-resolvermap.

apiVersion: networking.gloo.solo.io/v2
kind: RouteTable
metadata:
  name: graphql-bookinfo
  namespace: bookinfo
spec:
  hosts:
  - graphql-bookinfo.internal.com
  workloadSelectors:
  - selector:
      labels:
        app: client-app
  http:
  - name: graphql-bookinfo
    labels: 
      route: graphql-bookinfo
      graphql: "true"
    graphql:
      schema:
        clusterName: $CLUSTER_NAME
        name: bookinfo-rest-graphqlschema
        namespace: bookinfo
    matchers:
    - uri:
        prefix: /graphql

To test routing to the server, choose one of the following options:

Allow only specific GraphQL queries

You can prevent malicious requests to your GraphQL servers by specifying a list of allowed queries. For example, you might know that clients send only a limited set of GraphQL queries to your servers. To prevent your GraphQL servers from resolving potentially malicious requests, you specify that list of expected queries so that the servers immediately return an error for queries that are not in that list.

To get started, create a GraphQLAllowedQueryPolicy for a GraphQL route.

Cache request queries

To improve network performance for large query strings, the GraphQL filter supports automatic persisted queries. A persisted query consists of the query string and the query's hash that are cached on the GraphQL server side. When you enable query caching, a client can then send the query hash instead of the full query string, which reduces request sizes. Responses are unaffected. Persisted queries are especially effective when clients send queries as GET requests, because clients can take advantage of the browser cache and integrate with a CDN.

To get started, create a GraphQLPersistedQueryCachePolicy for a GraphQL route.

Apply authentication and rate limit policies

Because GraphQL is fully integrated with Gloo Gateway, you can apply other Gloo policies to your GraphQL setup, such as protecting your GraphQL route with external authentication and authorization or controlling the rate of requests to your route. To get started, see the external authentication and authorization and rate limiting policy guides.

Reference

For more information, see the Gloo Gateway API reference for the RouteTable CR.