Serverless GraphQL Federation Router for AWS Lambda

This guide is for teams running GraphQL Federation who want to deploy a federation router on AWS Lambda using a serverless architecture.

WunderGraph released an officially supported Serverless GraphQL Federation Router for AWS Lambda . The router allows teams to run a federated GraphQL gateway on Lambda using an event-driven serverless architecture with built-in OpenTelemetry support, schema analytics, and GraphQL Federation support.

The router is designed for small deployment size, fast cold starts, and integration with AWS Lambda execution patterns.

A GraphQL gateway, also known as a GraphQL router, acts as a single access point that aggregates data from multiple sources, orchestrating responses to GraphQL queries. It provides a unified GraphQL schema from different microservices, databases, or APIs, streamlining query processing and schema management. By routing requests to the appropriate services and merging the responses, a GraphQL gateway simplifies client-side querying, enabling seamless data retrieval from a variety of back-end services and systems. This architectural design enhances scalability, maintainability, and the ability to evolve API landscapes without impacting client applications.

In order to scale out a federated Graph, you need more than just a Gateway, though. You should have a Schema Registry, Analytics, Schema Usage Metrics, breaking change detection, and a lot more. For that, we've built Cosmo which is a complete platform to manage your federated Graph. Check out Cosmo on GitHub if you're interested, it's fully open-source (Apache 2.0 licensed).

In this article, the terms GraphQL gateway and GraphQL router are used interchangeably to describe the federated entry point handling GraphQL requests.

AWS Lambda provides a serverless computing service, offering a hassle-free solution where concerns about server provisioning, scaling, and infrastructure management are handled by AWS. This allows you to concentrate solely on your business logic. Although it might sound like a jargon-filled proposition, the practical benefits for companies are substantial. Operating gateway services is inherently complex and challenging, but AWS Lambda simplifies this process. It stands out as the most popular and mature serverless computing service, available in all regions and featuring an exceptionally generous free tier. These attributes make AWS Lambda an ideal choice for our specific needs.

The router runs as an AWS Lambda function using an event-driven execution model. Instead of running a continuously active HTTP server, AWS Lambda invokes the router handler for each request event.

This allows the GraphQL Federation router to integrate with AWS services and serverless infrastructure patterns in a serverless deployment model.

Due to the architecture of Lambda, we had to make our router event-driven. AWS Lambda functions are invoked by events. You can't simply run an http server. Instead, you have to register a handler function that is invoked by an event. This is a huge difference to traditional servers. Luckily, the community already built a lot of adapters to make this process as easy as possible. We decided to use the akrylysov/algnhsa to handle the event and response handling for us. This allows us to make our router compatible with only a few lines of code "simplified".

As a side effect, our Router can now be integrated into the existing AWS ecosystem. For example, we can run a GraphQL mutation through an SQS or S3 event. This allows us to build a very flexible and scalable system.

That's it! Of course not, there is a lot more going on under the hood. We down-shrink the router binary to 19MB to advance a small footprint and therefore fast cold starts. We also went a different route to report metrics and traces to our collectors. We will talk about this in the next section.

Our Router has built-in support for OpenTelemetry for tracing and metrics. We also collect schema usage data of your GraphQL operations to give you insights into your schema usage. In that way, we can identify if a schema change is safe to deploy or not.

• Lambda functions cannot continue background work after a response is sent.
• Traditional SIGTERM-based flushing patterns do not fit the Lambda execution model.
• Metrics and traces must be flushed synchronously after each request.

• Metrics and traces are sent in parallel.
• Traces are sampled to reduce overhead.
• Writes do not wait for acknowledgement from collectors.
• Added latency was measured at under 75ms.

In the AWS Lambda handler, you can't do work after the response was sent. If you are thinking in servers, we looked for a way to do arbitrary work in the background and on SIGTERM #Issue . This does not fit into the serverless mindset. Maybe your function will never shutdown, so you have to find another way. We have to flush the metrics and traces synchronously after each request. This is tricky, because it adds latency to the response. It is much better than it sounds, because we optimized the flushing process to be as fast as possible. All metrics and traces are sent in parallel without write acknowledgement to the collectors and traces are sampled to reduce the overhead. This adds less than 75ms of latency to the response. This is a very small price to pay for the benefits you get.

AWS Lambda includes a free tier of 1 million requests per month. If you exceed the free tier, you pay $2.28 per 1 million requests. We assume that each request takes 1 second to process. This plan uses the 128MB memory size model which is the cheapest and less powerful one. The CPU power scales proportionally with the memory size.

Our tests showed that the Router handles subsequent requests with this plan very well but at the cost of much higher cold start times. We recommend using the 1536MB memory size model. This is the sweet spot of good cold starts and low costs. We were able to wake up the Router and making a subgraph request in 641ms. The initialization time of the lambda function took just 300ms.

Once the Lambda function is initialized warm, it can handle subsequent requests in 80ms. In this scenario, we made a Subgraph request to the Employees API which is hosted on fly.io in the US West (LAX) region. This is a very good result and shows that our Router performs very well on AWS Lambda.

Additionally, we tested the performance of the router with 100 concurrent users over a period of 60 seconds. We warmed the functions with 2 pre-runs. Due to simplicity, I didn't redeploy the router near my location. Instead, I used the same setup as above. The router was deployed in the US West (Oregon) region while I'm located in Germany. We will definitely see better results if we deploy the router and subgraphs near my location, but I think the results already speak for themselves.

The router was able to handle all requests with p95 of 480ms. This is a very good result and shows that our router scales well on AWS Lambda.

I want to call out @codetalkio who does a fantastic job with their repository to unmistify the landscape of supported GraphQL Federated Gateways on AWS Lambda. It gave us the inspiration to support AWS Lambda as a first-class citizen.

As you might know, we love Open Source! You can find the source code of the Serverless Router on GitHub . We manage separate releases for the AWS Lambda router. You can find the releases here .

You don't have to build the router yourself. You can download the latest release and follow the instructions below.

Deployment requires:

• the Lambda router binary
• a router.json configuration file
• a zip archive containing both files

1. Download the Lambda Router binary from the official Router Releases page.

2. Create a .zip archive with the binary and the router.json file. You can download the latest router.json with wgc federated-graph fetch . The .zip archive should look like this:

   bash . └── myFunction.zip/ ├── bootstrap # Extracted from the Router release archive └── router.json # Downloaded with `wgc federated-graph fetch`

3. Deploy the .zip archive to AWS Lambda. You can use SAM CLI or the AWS console. Alternatively, you can use your IaC tool of choice.

Before taking traffic in production, see integration testing patterns for the Cosmo Router — the same federation behaviors apply to the Lambda build.

• The router runs GraphQL Federation on AWS Lambda using an event-driven architecture.
• OpenTelemetry tracing, metrics, and schema usage analytics are built in.
• The router binary was optimized for smaller deployment size and improved cold starts.
• Warm requests averaged around 80ms in testing.
• Deployment requires packaging the Lambda router binary together with a router.json configuration file.

AWS Lambda allows teams to deploy and scale a GraphQL Federation router using a serverless architecture.

If you are a company and want to use our router in production, please reach out to us . We are happy to help you with the setup process and provide you with support.

Frequently Asked Questions (FAQ)