gRPC resolvers
Define schema in a gRPC ApiDoc
, define gRPC resolvers in your Gloo environment to resolve schema fields, and map schema to resolvers.
Step 1: gRPC schema
Start by defining your schema in an ApiDoc
Gloo custom resource (CR).
Define the protobuf descriptors that represent the gRPC services provided by your API, encoded in base64. For more information, see the protobuf reference for FileDescriptorSet
.
apiVersion: apimanagement.gloo.solo.io/v2
kind: ApiDoc
metadata:
name:
namespace:
spec:
grpc:
descriptors: <base64_encoded_file_descriptor_set>
In this example for a basic user service app, the base64-encoded descriptor includes a set of fields that are defined for various queries, such as UserSearch
and UserByCountry
.
apiVersion: apimanagement.gloo.solo.io/v2
kind: ApiDoc
name: bookinfo-grpc-apidoc
namespace: bookinfo
spec:
grpc:
descriptors: CqIDChd1c2VyX3NlcnZpY2UvdXNlci5wcm90bxIEdXNlciKBAQoEVXNlchIdCgpmaXJzdF9uYW1lGAEgASgJUglmaXJzdE5hbWUSGwoJbGFzdF9uYW1lGAIgASgJUghsYXN0TmFtZRIaCgh1c2VybmFtZRgDIAEoCVIIdXNlcm5hbWUSIQoMY291bnRyeV9jb2RlGAUgASgJUgtjb3VudHJ5Q29kZSIoCgpVc2VyU2VhcmNoEhoKCHVzZXJuYW1lGAEgASgJUgh1c2VybmFtZSIyCg1Vc2VyQnlDb3VudHJ5EiEKDGNvdW50cnlfY29kZRgBIAEoCVILY291bnRyeUNvZGUiKQoFVXNlcnMSIAoFdXNlcnMYASADKAsyCi51c2VyLlVzZXJSBXVzZXJzMmwKC1VzZXJTZXJ2aWNlEicKB0dldFVzZXISEC51c2VyLlVzZXJTZWFyY2gaCi51c2VyLlVzZXISNAoQR2V0VXNlckJ5Q291bnRyeRITLnVzZXIuVXNlckJ5Q291bnRyeRoLLnVzZXIuVXNlcnNiBnByb3RvMw==
Step 2: gRPC resolvers
Define gRPC resolver servers for each query type in a GraphQLResolverMap
Gloo CR.
apiVersion: apimanagement.gloo.solo.io/v2
kind: GraphQLResolverMap
metadata:
name:
namespace:
spec:
# Resolver map
types:
Query:
fields:
# Replace 'nameOfField' with the name of the field that you
# previously defined for this query
<nameOfField>:
# Configuration for generating outgoing requests to a gRPC API
resolvers:
# See section "Optional: Apply jq filters"
- resolverResultTransform:
jq:
grpcResolver:
# Reference to the upstream destination associated with the gRPC API
destinations:
- port:
number:
ref:
cluster:
name:
namespace:
request:
# Optional: The ':authority' header to set on the gRPC request
authority:
# The gRPC method to call
method:
# The gRPC request body, which is a JSON object that is marshalled
# into the gRPC request. Can be templated using variables
# from the variables field. For example, see section
# "Optional: Apply jq filters"
outgoingMessage:
jq:
# The gRPC service to call
service:
# Static metadata to be added to the gRPC request. For more info, see
# https://grpc.io/docs/what-is-grpc/core-concepts/#metadata
requestMetadata:
# The span name for the upstream gRPC request, used for tracing.
# If unset, the request span name is set to the upstream cluster name
spanName:
# The timeout of the HTTP request to the gRPC service (default: 5s)
timeout:
# Declare any variables for transformations applied to the GraphQL request or response
# in the 'resolverResultTransform', 'headers', and 'queryParams' fields.
# For more info, see section "Optional: Define variables for use in resolvers"
variables:
For further information about how resolvers can apply transformations on the requests to or responses from services:
In this example resolver map, a gRPC resolver is defined for the GetUser
field of the top-level query type. This resolver references the users-grpc
service in the cluster.
apiVersion: apimanagement.gloo.solo.io/v2
kind: GraphQLResolverMap
metadata:
name: bookinfo-grpc-resolvermap
namespace: bookinfo
spec:
types:
Query:
fields:
GetUser:
resolvers:
- grpcResolver:
destinations:
- port:
number: 8080
ref:
name: users-grpc
namespace: bookinfo
request:
method: GetUser
outgoingMessage:
jq: .userInputArg
service: user.UserService
variables:
userInputArg:
graphqlArg: user
Optional: Define variables for use in resolvers
You can define variables that you want to use in the variables
section of a resolver in the resolver map. For example, you might define variables for the following uses:
- Schema arguments: Define variables to retrieve arguments defined in your schema.
- Authorization: Define common authorization variables, such as
requestHeader: "Authorization"
. jq
filters: Define variables in this section that you want to use injq
filters for the resolver request or result. For more information, see Applyingjq
filters.
Note that some variables have defined names and guidelines for values. For more information about each type of variable, see the API documentation for resolver variables.
For example, you might define the following variables for the Reviews
service:
...
Product:
fields:
reviews:
variables:
parentVar:
graphqlParent: {}
authorizationVar:
requestHeader: "Authorization"
In the same resolver map resource, you can then call these variables in the resolver request headers or body, such as the following headers. Note that you can also specify individual values that are not declared in variables.
...
resolvers:
- restResolver:
destinations:
...
request:
headers:
Authorization:
variable: authorizationVar
:path:
variable: parentVar
value: "[1,2,3]"
Optional: Apply jq filters
To transform the JSON content of a GraphQL resolver request or result, you can provide jq filters in your GraphQL resolver map.
You can define variables that you want to use in the jq transformation filter in the variables
section of a resolver in the resolver map. For example, a variable named “userIdHeader” can be used in a jq filter as .userIdHeader
. Then, you can apply jq filters to resolver requests (resolver.restResolver.request
) or results (resolver.restResolver.resolverResultTransform
) that call these variables.
For more information, see the API documentation for jq
transformation. For information about jq syntax and how to construct your jq filter, see the jq development manual.
For example, you might define the following variables for the Reviews
service:
...
Product:
fields:
reviews:
variables:
parentVar:
graphqlParent: {}
authorizationVar:
requestHeader: "Authorization"
You can then call these variables in the resolver request headers or body:
...
resolvers:
- restResolver:
destinations:
...
request:
headers:
:path:
jq: '"/reviews/" + .parentVar.id'
customAuth:
jq: '"Bearer " + .authorizationVar'
You can also use variables in jq filters for resolver results. For example, if the data that the resolver fetched from your upstream API is not formatted in a way that the client can understand according to your schemas, you can apply a jq filter to the result data.
The fetched data from your API might be formatted like the following:
{ "userIdHeader": "john_doe123", "resolverResultVar": { "data": {"name": "John Doe"} } }
First, you define the following variables.
...
variables:
userIdHeader:
requestHeader: x-user-id
resolverResultVar:
resolverResult: {}
You then call those variables in a resolver.resolverResultTransform
jq filter. Note that the resolverResultVar
variable can only be used in the resolverResultTransform
field, and not in a request field.
...
resolvers:
- restResolver:
destinations:
...
request:
...
resolverResultTransform:
jq: '"User: " + .userIdHeader + ", Name: " + .resolverResultVar.data.name'
The result of the jq transformation is as follows:
"User: john_doe123, Name: John Doe"
jq filters must only result in one value. For example, for the input [1,2,3]
, the jq filter .[]
is not a valid jq filter as it results in multiple jq results. However, the jq filter '. | join(",")'
is valid as it results in only one result: “1,2,3”. Refer to the jq manual for jq syntax and tips.
Step 3: 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-grpc-resolvermap
are mapped to the schema definition from bookinfo-grpc-apidoc
.
apiVersion: apimanagement.gloo.solo.io/v2
kind: GraphQLSchema
metadata:
name: bookinfo-grpc-graphqlschema
namespace: bookinfo
spec:
resolved:
options: {}
resolverMapRefs:
- clusterName: $CLUSTER_NAME
name: bookinfo-grpc-resolvermap
namespace: bookinfo
schemaRef:
clusterName: $CLUSTER_NAME
name: bookinfo-grpc-apidoc
namespace: bookinfo
Reference
For more information, see the Gloo Gateway API reference for the following CRs: