Incoming GraphQL requests are proxied to existing GraphQL backends. These backends can be other GraphQL servers within or outside your Gloo setup.

  • Within your setup, the backend servers can be Kubernetes services or Gloo virtual destinations.
  • Outside your setup, you can represent the backend servers with an external service.

Before you begin

  1. Identify existing GraphQL backend servers to proxy requests to. These servers must comply with the June 2018 GraphQL specification.
  2. If your APIs are external to your cluster, represent the service in your Gloo setup by using ExternalEndpoint and ExternalService CRs.
  3. Make sure that the GraphQL schema definition in your ApiDoc resource matches the schema of your existing GraphQL backend.

Template

Create a Gloo representation of existing GraphQL APIs by specifying the proxied section in a GraphQLSchema Gloo custom resource (CR).

  apiVersion: apimanagement.gloo.solo.io/v2
kind: GraphQLSchema
metadata:
  name: 
  namespace: 
spec:
  # Delegate query execution by proxying requests to existing GraphQL backends
  proxied:
    # List of destinations that can resolve GraphQL requests.
    # The existing GraphQL server must be compliant with the June 2018 GraphQL specification.
    graphqlServers:
      - port:
          number: 
        ref:
          cluster: 
          name: 
          namespace: 
    # Declare any variables for transformations you apply to the
    # GraphQL request in the 'headers' and 'queryParams' fields.
    # For more info, see section "Optional: Define variables for use in transformations"
    variables:
      dynamicMetadata:
      requestHeader:
      json:
    # Map of header name to a transformation on extracted variables which are declared in the variables field.
    # The transformation must result in a string value, or an error is returned.
    headers:
      # Path transformations, such a jq or json
      :path:
    # URL query parameters (key/value) on the request to the destination
    queryParams:
      key: value
    # 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:
    # Set the timeout of the HTTP request to the destination. Default: 5s.
    timeout:

Example

In this example, the music-graphql GraphQLSchema is mapped to the schema definition from the music-schema ApiDoc resource.

  apiVersion: apimanagement.gloo.solo.io/v2
kind: GraphQLSchema
metadata:
  name: music-graphqlschema
  namespace: bookinfo
spec:
  proxied:
    graphqlServers:
    - port:
        number: 8080
      ref:
        cluster: $CLUSTER_NAME
        name: music-graphql
        namespace: bookinfo
    headers:
      :path:
        json: /graphql
  schemaRef:
    clusterName: $CLUSTER_NAME
    name: music-schema
    namespace: bookinfo

Reference

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

Next steps

Set up routing to APIs and apply traffic policies.