Announcing Gloo GraphQL Support in Gloo Mesh
With the release of Gloo Mesh 2.1 and Gloo Gateway 2.1, Gloo GraphQL can now be used to build GraphQL APIs for north-south and east-west service architectures in Gloo Platform. This release builds on the foundation of our GA release of Gloo Edge GraphQL earlier this year, while offering first-class integration with the new Gloo Mesh 2.x APIs, Gloo Platform management UI, and some exciting new features that supercharge our declarative approach to building GraphQL APIs with no coding. Let’s get right into the details!
New Look API in Gloo Mesh
The Gloo GraphQL API represents the front door to the features of our full-blown GraphQL server implementation in Envoy. Implemented as an Envoy filter, our GraphQL server implementation is the same whether Gloo GraphQL is running in Gloo Edge or Gloo Mesh, but the API is designed to fit the specific use cases for the underlying product. Adding support for Gloo GraphQL in Gloo Mesh provided an opportunity to take advantage of unique aspects of the Gloo Mesh 2.x APIs, while also incorporating feedback and experience from existing customer usage. The resulting API centers around three key resources: ApiSchema, GraphQLResolverMap, and RouteTable.
ApiSchema
A schema definition conforming to the GraphQL Schema Definition Language (SDL) represents the contract between GraphQL clients and a GraphQL API. We’re big proponents of a schema-first approach and our API reflects that with ApiSchema as a top-level resource definition. A nice improvement in the latest API is the ability to define the schema of our GraphQL API as a reusable resource, opening up the possibility of defining multiple resolver implementations for that API. This is a great way to take advantage of advanced Mesh features like selective routing (e.g., different resolvers for different clients) or managing canary upgrades to resolver implementations.
apiVersion: apimanagement.gloo.solo.io/v2 kind: ApiSchema metadata: name: user-schema namespace: frontend spec: graphql: schemaDefinition: |- type Query { me: User } type User { id: ID name: String }
GraphQLResolverMap
Similar to the more modular approach with schema definitions, resolver configuration is now its own top-level resource, GraphQLResolverMap. This allows you to encapsulate the definition of how upstream APIs map to fields in a GraphQL schema, promoting reuse for resolution logic with common data types. Additionally, this flexibility allows you to provide alternative configurations in a canary or blue-green approach to updating resolver definitions.
apiVersion: apimanagement.gloo.solo.io/v2
kind: GraphQLResolverMap
metadata:
name: user-resolvers
namespace: frontend
spec:
types:
Query:
fields:
me:
resolvers:
- restResolver:
destinations:
- port:
number: 9080
ref:
name: user-service
namespace: backend
request:
headers:
:path:
jq: ‘"/api/v1/users"’
RouteTable
RouteTable is where the magic happens with GraphQL in Gloo Mesh. Existing Gloo Mesh users will note that RouteTable is an existing API resource in the Gloo Mesh and not something new with Gloo GraphQL. This was a deliberate design decision to leverage the power and flexibility of the core routing abstraction in Gloo Mesh and simply enrich it with GraphQL configuration when a route is servicing GraphQL APIs. Take the following example for our Users GraphQL API:
apiVersion: networking.gloo.solo.io/v2 kind: RouteTable metadata: name: users-example-rt namespace: frontend spec: hosts: - users.example.com http: - graphql: executableSchema: local: options: {} resolverMapRefs: - name: user-resolvers namespace: frontend schemaRef: name: user-schema namespace: frontend matchers: - uri: prefix: /graphql virtualGateways: - name: istio-ingressgateway
The new graphql field collects the composable ApiSchema and GraphQLResolverMap definitions, and associates them with a matcher definition. As a GraphQL API matures, matchers may route specific clients to different compositions of the API based on client-specific criteria, or possibly compose different versions of resolver implementations for controlled upgrades. Further, all of the Gloo Mesh capabilities that interact with RouteTable resources (e.g. AccessPolicy) are available for GraphQL API routes as well!
Note that this new API is specific to Gloo Mesh and Gloo Gateway, so existing Gloo GraphQL customers on Gloo Edge will not be impacted at all. Our goal here is to provide the best API possible in the context of each product component.
Supercharging Declarative Configuration with jq
Our customers love the fact that they can create, compose, and federate GraphQL APIs using a simple yet powerful declarative configuration syntax that requires no coding or separate GraphQL server deployment. As we see more and more examples of declarative configuration in the context of customer use cases, it became clear that customers would benefit from a more powerful data transformation language when mapping data between a GraphQL API and the upstream APIs it integrates with. To address this need, we have added support for the amazing JQ framework for data access and transformation within resolver configurations.
In a nutshell, using JQ involves two steps:
- You define the variables from the request context you are interested in. Some common examples would be the parent of the current field being resolved, a field argument, or an HTTP header from the client request.
- You define a JQ filter inline in the request or resolverResultTransform fields in your resolver configuration to map request or response data respectively.
The great thing about JQ is that basic filter expressions are short and easy to craft, yet the filter language scales to handle really complex use cases quite easily. Check out the JQ section of the Gloo GraphQL documentation for details on the syntax and some examples.
Visualizing GraphQL in the Gloo Platform UI
Starting with Gloo Mesh 2.1, you’ll notice a new APIs tab in the left-hand menu in the Gloo Platform UI that provides a single point of access for all GraphQL APIs provided by Gloo.
The API details page for each GraphQL API allows you to browse the queries, mutations, and user-defined types in each schema in addition to viewing the SQL for the API. You can also view upstream services used in resolvers, gateways used to expose the GraphQL API to external clients, and GraphQL settings like introspection on a per-API basis.
But Wait, There’s More!
We’re very excited about this initial support for Gloo GraphQL in Gloo Mesh, but there are some big things coming up in Gloo Mesh 2.2 as well:
- Support for gRPC and Mock resolvers. These features almost made the cut for Gloo Mesh and Gloo Gateway 2.1, but we wanted to take a little extra time to dial in the final version of the API. This will be ready almost immediately in 2.2 beta builds, so check it out there to kick the tires.
- Discovery and generation of GraphQL from existing REST and gRPC APIs. This feature in Gloo GraphQL for Gloo Edge is incredibly popular with customers. Our view of autogeneration has always been that it’s a great development-time tool, but the generated resources should always be committed to Git and deployed to downstream environments with GitOps. We’re working on integration with the Gloo Mesh CLI (meshctl) to discover and automatically generate Gloo GraphQL custom resources. You can choose to directly apply those for quick turnaround or check them into Git and deploy via continuous delivery.
- Explorer in Gloo Platform UI. Gloo Mesh and Gloo Gateway 2.1 add support for a read-only GraphQL UI without the embedded GraphQL Explorer based on GraphiQL. We’re already working on adding Explorer along with some nice UX enhancements based on our experience with Explorer in the Gloo Edge UI.
- Schema Stitching. Schema stitching continues to be our approach to creating unified GraphQL APIs from individual GraphQL subgraphs. The stitching implementation is already complete in our Envoy filter, and Gloo Mesh and Gloo Gateway 2.2 will add the associated control plane API.
Learn more about Gloo GraphQL.
- Get your hands on GraphQL– request a demo today.
- Join the conversation on the Solo.io Slack.
