Deploying with AWS Lambda

AWS Lambda is a service that allows users to run code without provisioning or managing servers. Cost is based on the compute time that is consumed, and there is no charge when code is not running.

This guide explains how to setup Apollo Server 2 to run on AWS Lambda using Serverless Framework. To use CDK and SST instead, follow this tutorial.

Prerequisites

The following must be done before following this guide:

• Setup an AWS account
• Install the AWS CLI
• Configure the AWS CLI with user credentials
• Install the serverless framework from NPM
  • npm install -g serverless

Setting up your project

Setting up a project to work with Lambda isn't that different from a typical NodeJS project.

First, install the apollo-server-lambda package:

1
npm install apollo-server-lambda graphql

Next, set up the schema's type definitions and resolvers, and pass them to the ApolloServer constructor like normal. Here, ApolloServer must be imported from apollo-server-lambda. It's also important to note that this file must be named graphql.js, as the config example in a later step depends on the filename.

1
// graphql.js
2

3
const { ApolloServer, gql } = require('apollo-server-lambda');
4

5
// Construct a schema, using GraphQL schema language
6
const typeDefs = gql`
7
  type Query {
8
    hello: String
9
  }
10
`;
11

12
// Provide resolver functions for your schema fields
13
const resolvers = {
14
  Query: {
15
    hello: () => 'Hello world!',
16
  },
17
};
18

19
const server = new ApolloServer({
20
  typeDefs,
21
  resolvers,
22
  csrfPrevention: true,
23
  cache: 'bounded',
24
});
25

26
exports.graphqlHandler = server.createHandler();

Finally, pay close attention to the last line. This creates an export named graphqlHandler with a Lambda function handler.

Deploying with the Serverless Framework

Serverless is a framework that makes deploying to services like AWS Lambda simpler.

Configuring the Serverless Framework

Serverless uses a config file named serverless.yml to determine what service to deploy to and where the handlers are.

For the sake of this example, the following file can just be copied and pasted into the root of your project.

1
# serverless.yml
2

3
service: apollo-lambda
4
provider:
5
  name: aws
6
  runtime: nodejs14.x
7
functions:
8
  graphql:
9
    # this is formatted as <FILENAME>.<HANDLER>
10
    handler: graphql.graphqlHandler
11
    events:
12
    - http:
13
        path: /
14
        method: post
15
        cors: true
16
    - http:
17
        path: /
18
        method: get
19
        cors: true

Running Locally

Using the serverless CLI, we can invoke our function locally to make sure it is running properly. As with any GraphQL "server", we need to send an operation for the schema to run as an HTTP request. You can store a mock HTTP request locally in a query.json file:

1
{
2
  "httpMethod": "POST",
3
  "path": "/",
4
  "headers": {
5
    "content-type": "application/json"
6
  },
7
  "requestContext": {},
8
  "body": "{\"operationName\": null, \"variables\": null, \"query\": \"{ hello }\"}"
9
}

1
serverless invoke local -f graphql -p query.json

Deploying the Code

After configuring the Serverless Framework, all you have to do to deploy is run serverless deploy

If successful, serverless should output something similar to this example:

1
> serverless deploy
2
Serverless: Packaging service...
3
Serverless: Excluding development dependencies...
4
Serverless: Uploading CloudFormation file to S3...
5
Serverless: Uploading artifacts...
6
Serverless: Uploading service .zip file to S3 (27.07 MB)...
7
Serverless: Validating template...
8
Serverless: Updating Stack...
9
Serverless: Checking Stack update progress...
10
..............
11
Serverless: Stack update finished...
12
Service Information
13
service: apollo-lambda
14
stage: dev
15
region: us-east-1
16
stack: apollo-lambda-dev
17
api keys:
18
  None
19
endpoints:
20
  POST - https://ujt89xxyn3.execute-api.us-east-1.amazonaws.com/dev/
21
  GET - https://ujt89xxyn3.execute-api.us-east-1.amazonaws.com/dev/
22
functions:
23
  graphql: apollo-lambda-dev-graphql

What does serverless do?

First, it builds the functions, zips up the artifacts, and uploads the artifacts to a new S3 bucket. Then, it creates a Lambda function with those artifacts, and if successful, outputs the HTTP endpoint URLs to the console.

Managing the resulting services

The resulting S3 buckets and Lambda functions can be viewed and managed after logging in to the AWS Console.

• To find the created S3 bucket, search the listed services for S3. For this example, the bucket created by Serverless was named apollo-lambda-dev-serverlessdeploymentbucket-1s10e00wvoe5f
• To find the created Lambda function, search the listed services for Lambda. If the list of Lambda functions is empty, or missing the newly created function, double check the region at the top right of the screen. The default region for Serverless deployments is us-east-1 (N. Virginia)

If you changed your mind, you can remove everything from your AWS account with npx serverless remove.

Customizing HTTP serving

apollo-server-lambda is built on top of apollo-server-express. It combines the HTTP server framework express with a package called @vendia/serverless-express that translates between Lambda events and Express requests. By default, this is entirely behind the scenes, but you can also provide your own express app with the expressAppFromMiddleware option to createHandler:

1
const { ApolloServer } = require('apollo-server-lambda');
2
const express = require('express');
3

4
exports.handler = server.createHandler({
5
  expressAppFromMiddleware(middleware) {
6
    const app = express();
7
    app.use(someOtherMiddleware);
8
    app.use(middleware);
9
    return app;
10
  }
11
});

Configuring the underlying Express integration

Because apollo-server-lambda is built on top of apollo-server-express, you can specify the same options that apollo-server-express accepts in getMiddleware (or applyMiddleware, other than app) as the expressGetMiddlewareOptions option to createHandler. The default value of this option is {path: '/'} (and this value of path will be used unless you explicitly override it). For example:

1
exports.handler = server.createHandler({
2
  expressGetMiddlewareOptions: {
3
    disableHealthCheck: true,
4
  }
5
});

Getting request info

Your ApolloServer's context function can read information about the current operation from both the original Lambda data structures and the Express request and response created by @vendia/serverless-express. These are provided to your context function as event, context, and express options.

The event object contains the API Gateway event (HTTP headers, HTTP method, body, path, ...). The context object (not to be confused with the context function itself!) contains the current Lambda Context (Function Name, Function Version, awsRequestId, time remaining, ...). express contains req and res fields with the Express request and response. The object returned from your context function is provided to all of your schema resolvers in the third context argument.

1
const { ApolloServer, gql } = require('apollo-server-lambda');
2

3
// Construct a schema, using GraphQL schema language
4
const typeDefs = gql`
5
  type Query {
6
    hello: String
7
  }
8
`;
9

10
// Provide resolver functions for your schema fields
11
const resolvers = {
12
  Query: {
13
    hello: () => 'Hello world!',
14
  },
15
};
16

17
const server = new ApolloServer({
18
  typeDefs,
19
  resolvers,
20
  csrfPrevention: true,
21
  cache: 'bounded',
22
  context: ({ event, context, express }) => ({
23
    headers: event.headers,
24
    functionName: context.functionName,
25
    event,
26
    context,
27
    expressRequest: express.req,
28
  }),
29
});
30

31
exports.graphqlHandler = server.createHandler();