Route to GraphQL servers
Set up routes to your GraphQL servers so that clients can send GraphQL queries to your endpoints
- Map the fields from your schema definition to the resolvers in a
GraphQLSchema
Gloo CR, so that the resolver services can access the field information for each type. - Define the hosts and paths on which clients can access GraphQL servers in a Gloo
RouteTable
resource.
Then, you can apply additional Gloo policies to the routes.
- Prevent malicious requests to your GraphQL servers by specifying a list of allowed queries in a Gloo
GraphQLAllowedQueryPolicy
policy. - Improve network performance by caching GraphQL queries in a Gloo
GraphQLPersistedQueryCachePolicy
policy. - Control the rate of requests to your API and set up external authentication and authorization to protect your API by applying Gloo authentication and rate limit policies.
Step 1: Map schema to resolvers
Map the types and fields from your schema definition (ApiDoc
) to the resolver servers (GraphQLResolverMap
) in a GraphQLSchema
Gloo CR. The GraphQLSchema
CR ensures that the GraphQL resolver services can access the field information for each type.
apiVersion: apimanagement.gloo.solo.io/v2
kind: GraphQLSchema
metadata:
name:
namespace:
spec:
# Allow GraphQL servers that you define in GraphQLResolverMap CRs to resolve queries locally
resolved:
# Additional options on the schema
options:
# Enable introspection for the schema. Defaults to false.
enableIntrospection:
# Limit the maximum nesting on a query that runs against this schema.
# Any GraphQL operation that queries past the max depth adds an error message to the response and returns as null.
# If not configured, or the value is 0, the query depth is unbounded.
maxDepth:
# References to GraphQLResolverMap resources for resolvers.
# Resolver maps that are higher in this list have a higher priority
# over lower items when tie-breaking field resolver configurations exist.
resolverMapRefs:
- clusterName:
name:
namespace:
# Reference to ApiDoc resource for schema definitions
schemaRef:
clusterName:
name:
namespace:
In this example GraphQLSchema
resource, the resolvers from bookinfo-rest-resolvermap
are mapped to the schema definition from bookinfo-rest-apidoc
.
apiVersion: apimanagement.gloo.solo.io/v2
kind: GraphQLSchema
metadata:
name: bookinfo-rest-graphqlschema
namespace: bookinfo
spec:
resolved:
options: {}
resolverMapRefs:
- clusterName: $CLUSTER_NAME
name: bookinfo-rest-resolvermap
namespace: bookinfo
schemaRef:
clusterName: $CLUSTER_NAME
name: bookinfo-rest-apidoc
namespace: bookinfo
Step 2: 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.
North-south routing
To route requests from clients that are external to your Gloo Gateway setup, you can use the following route table template.
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, which maps schema definitions to resolvers
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:
-
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
-
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:443:${INGRESS_GW_IP} https://www.example.com:443/graphql \ -d '{"query":"query { productsForHome { title ratings {reviewer numStars}} }"}'
East-west routing
To route requests from clients that are internal to your Gloo Gateway setup, such as if you use Gloo Mesh, you can use the following route table template. 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, which maps schema definitions to resolvers
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, you can log in to your client app and send a request to the host and path, such as graphql-bookinfo.internal.com/graphql
in the example route table, to verify that the GraphQL server is reachable through the route.
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 GraphQLResolverMap
CR and RouteTable
CR.