Deploying with AWS Lambda

How to deploy Apollo Server with AWS Lambda

AWS Lambda is a serverless computing platform with a pay-for-use billing model that enables you to run code without worrying about provisioning or managing servers.

In this guide, we'll walk through how to deploy Apollo Server's AWS Lambda integration to AWS Lambda using the Serverless framework.

Prerequisites

Make sure you've completed the following before proceeding with this guide:

Create an AWS account
Install the AWS CLI
Create an IAM user
Configure the AWS CLI with your new IAM user's credentials

⚠️ AWS best practices warn against using your AWS account root user keys for any task where it's not required (e.g., don't use these keys to configure the AWS CLI). Instead, create an IAM user account with the least privilege required to deploy your application, and configure the AWS CLI to use that account.

Setting up your project

For this example, we'll start from scratch to show how all the pieces fit together.

Begin by installing the necessary packages for using Apollo Server and its integration for AWS Lambda:

1
npm install @apollo/server graphql @as-integrations/aws-lambda

1
npm install -D typescript

Next, we'll create a file with a basic Apollo Server setup. Note the file's name and location; we'll need those in a later step:

src/server.ts

1
import { ApolloServer } from '@apollo/server';
2

3
// The GraphQL schema
4
const typeDefs = `#graphql
5
  type Query {
6
    hello: String
7
  }
8
`;
9

10
// A map of functions which return data for the schema.
11
const resolvers = {
12
  Query: {
13
    hello: () => 'world',
14
  },
15
};
16

17
// Set up Apollo Server
18
const server = new ApolloServer({
19
  typeDefs,
20
  resolvers,
21
});

server.js

1
import { ApolloServer } from '@apollo/server';
2

3
// The GraphQL schema
4
const typeDefs = `#graphql
5
  type Query {
6
    hello: String
7
  }
8
`;
9

10
// A map of functions which return data for the schema.
11
const resolvers = {
12
  Query: {
13
    hello: () => 'world',
14
  },
15
};
16

17
// Set up Apollo Server
18
const server = new ApolloServer({
19
  typeDefs,
20
  resolvers,
21
});

Now we can import the startServerAndCreateLambdaHandler function from @as-integrations/aws-lambda, passing in our ApolloServer instance:

src/server.ts

1
import { ApolloServer } from '@apollo/server';
2
import { startServerAndCreateLambdaHandler } from '@as-integrations/aws-lambda'; 
3

4
const typeDefs = `#graphql
5
  type Query {
6
    hello: String
7
  }
8
`;
9

10
const resolvers = {
11
  Query: {
12
    hello: () => 'world',
13
  },
14
};
15

16
const server = new ApolloServer({
17
  typeDefs,
18
  resolvers,
19
});
20

21
// This final export is important!
22
export const graphqlHandler = startServerAndCreateLambdaHandler(server);

server.js

1
import { ApolloServer } from '@apollo/server';
2
import { startServerAndCreateLambdaHandler } from '@as-integrations/aws-lambda'; 
3

4
const typeDefs = `#graphql
5
  type Query {
6
    hello: String
7
  }
8
`;
9

10
const resolvers = {
11
  Query: {
12
    hello: () => 'world',
13
  },
14
};
15

16
const server = new ApolloServer({
17
  typeDefs,
18
  resolvers,
19
});
20

21
// This final export is important!
22
export const graphqlHandler = startServerAndCreateLambdaHandler(server);

The final line in the code snippet above creates an export named graphqlHandler with a Lambda function handler. We'll get back to this function in a moment!

Deploying using the Serverless framework

Serverless is a framework that helps make deploying serverless applications to platforms like AWS Lambda easier.

Installing the CLI

We'll use the Serverless CLI to deploy our application. You can either install the Serverless package into your project directly or install the Serverless CLI globally:

1
npm install -g serverless

The Serverless CLI can access the credentials of the AWS CLI, which you configured earlier. So now we just need to tell Serverless which service we want to deploy.

AWS best practices recommend rotating your access keys for use cases that require long-term credentials (e.g., hosting an application).

Configuring services

You can configure Serverless using a serverless.yml file, letting it know which services to deploy and where the handlers are.

If you are using TypeScript, download the serverless-plugin-typescript package to enable Serverless to use your TS file:

1
npm install -D serverless-plugin-typescript

You use the example serverless.yml configuration below; take care to ensure the file path you use is pointing to the file where you export your handler:

serverless.yml

1
service: apollo-lambda
2
provider:
3
  name: aws
4
  runtime: nodejs16.x
5
  httpApi:
6
    cors: true
7
functions:
8
  graphql:
9
    # Make sure your file path is correct!
10
    # (e.g., if your file is in the root folder use server.graphqlHandler )
11
    # The format is: <FILENAME>.<HANDLER>
12
    handler: src/server.graphqlHandler 
13
    events:
14
      - httpApi:
15
          path: /
16
          method: POST
17
      - httpApi:
18
          path: /
19
          method: GET
20
# Omit the following lines if you aren't using TS!
21
plugins:
22
  - serverless-plugin-typescript

Running locally

Before deploying, we can use the Serverless CLI to invoke our handler locally to ensure everything is working. We'll do this by mocking an HTTP request with a GraphQL operation.

You can store a mock HTTP requests locally by creating a query.json file, like so:

query.json

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

Now we can use serverless to invoke our handler using the query above:

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

Your response should look something like this:

1
{
2
  "statusCode": 200,
3
  "headers": {
4
    "cache-control": "no-store",
5
    "content-type": "application/json; charset=utf-8",
6
    "content-length": "27"
7
  },
8
  "body": "{\"data\":{\"hello\":\"world\"}}\n"
9
}

With everything working locally, we can move on to deployment!

Deploying

As we mentioned earlier, Serverless already has access to your AWS CLI credentials, so to deploy, all you need to do is run the following command:

1
serverless deploy

If successful, serverless should output something like this:

1
> serverless deploy
2
> Deploying apollo-lambda to stage dev (us-east-1)
3
> ✔ Service deployed to stack apollo-lambda-dev (187s)
4
> ..............
5
> endpoints:
6
> POST - https://ujt89xxyn3.execute-api.us-east-1.amazonaws.com/dev/
7
> GET - https://ujt89xxyn3.execute-api.us-east-1.amazonaws.com/dev/
8
> functions:
9
> graphql: apollo-lambda-dev-graphql
10
> Monitor all your API routes with Serverless Console: run "serverless --console"

You can now navigate to your endpoints and query your newly hosted server using Apollo Sandbox.

What does `serverless` do?

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

Managing the resulting services

The resulting S3 buckets and Lambda functions are accessible from the AWS Console. The AWS Console also lets you view the IAM user you created earlier.

To find the S3 bucket that Serverless created, search in Amazon's listed services for S3, then look for the name of your bucket (e.g., apollo-lambda-dev-serverlessdeploymentbucket-1s10e00wvoe5f is the name of our bucket).

To find the Lambda function that Serverless created, search in Amazon's listed services for Lambda. Double-check the region at the top right of the screen if your list of Lambda functions is empty or missing your new function. The default region for Serverless deployments is us-east-1 (N. Virginia).

If you ever want to remove the S3 bucket or Lambda functions that Serverless created, you can run the following command:

1
serverless remove

Customizing HTTP behavior

The @as-integrations/aws-lambda package is compatible with the following event types APIGatewayProxyEvent, APIGatewayProxyEventV2, ALBEvent. This supports a wide range of services like API Gateway HTTP Proxy APIs, API Gateway REST Proxy APIs, Lambda Function URLs, and Application Load Balancers. However, it does not let you customize HTTP behavior directly or support other AWS products that invoke Lambda functions (e.g., S3 or DynamoDB).

If you want to customize your HTTP behavior, you can couple Apollo Server's Express integration (i.e., expressMiddleware) with the @vendia/serverless-express package. The @vendia/serverless-express library translates between Lambda events and Express requests. Despite their similar names, the Serverless CLI and the @vendia/serverless-express package are unrelated.

You can update your Apollo Server setup to the following to have a fully functioning Lambda server that works in a variety of AWS features:

1
const { ApolloServer } = require('@apollo/server');
2
const { expressMiddleware } = require('@apollo/server/express4');
3
const serverlessExpress = require('@vendia/serverless-express');
4
const express = require('express');
5
const { json } = require('body-parser');
6
const cors = require('cors');
7

8
const server = new ApolloServer({
9
  typeDefs: 'type Query { x: ID }',
10
  resolvers: { Query: { x: () => 'hi!' } },
11
});
12

13
server.startInBackgroundHandlingStartupErrorsByLoggingAndFailingAllRequests();
14

15
const app = express();
16
app.use(cors(), json(), expressMiddleware(server));
17

18
exports.graphqlHandler = serverlessExpress({ app });

1
const { ApolloServer } = require('@apollo/server');
2
const { expressMiddleware } = require('@apollo/server/express4');
3
const serverlessExpress = require('@vendia/serverless-express');
4
const express = require('express');
5
const { json } = require('body-parser');
6
const cors = require('cors');
7

8
const server = new ApolloServer({
9
  typeDefs: 'type Query { x: ID }',
10
  resolvers: { Query: { x: () => 'hi!' } },
11
});
12

13
server.startInBackgroundHandlingStartupErrorsByLoggingAndFailingAllRequests();
14

15
const app = express();
16
app.use(cors(), json(), expressMiddleware(server));
17

18
exports.graphqlHandler = serverlessExpress({ app });

The setup enables you to customize your HTTP behavior as needed.

Using request information

You can use the context function to get information about the current operation from the original Lambda data structures.

Your context function can access this information from its argument containing event and context objects:

1
const server = new ApolloServer<MyContext>({
2
  typeDefs,
3
  resolvers,
4
});
5

6
// This final export is important!
7
export const graphqlHandler = startServerAndCreateLambdaHandler(server, {
8
  context: async ({ event, context }) => {
9
    return {
10
      lambdaEvent: event,
11
      lambdaContext: context,
12
    };
13
  },
14
});

1
const server = new ApolloServer({
2
  typeDefs,
3
  resolvers,
4
});
5

6
// This final export is important!
7
export const graphqlHandler = startServerAndCreateLambdaHandler(server, {
8
  context: async ({ event, context }) => {
9
    return {
10
      lambdaEvent: event,
11
      lambdaContext: context,
12
    };
13
  },
14
});

The event object contains the API Gateway event (HTTP headers, HTTP method, body, path, etc.). The context object (not to be confused with the context function) contains the current Lambda Context (function name, function version, awsRequestId, time remaining, etc.).

If you've changed your setup to use @vendia/serverless-express your context function receives req and res options which are express.Request and express.Response objects:

1
const { ApolloServer } = require('@apollo/server');
2
const { expressMiddleware } = require('@apollo/server/express4');
3
const serverlessExpress = require('@vendia/serverless-express');
4
const express = require('express');
5
const { json } = require('body-parser');
6
const cors = require('cors');
7

8
const server = new ApolloServer({
9
  typeDefs: 'type Query { x: ID }',
10
  resolvers: { Query: { x: () => 'hi!' } },
11
});
12

13
server.startInBackgroundHandlingStartupErrorsByLoggingAndFailingAllRequests();
14

15
const app = express();
16
app.use(
17
  cors(),
18
  json(),
19
  expressMiddleware(server, {
20
    // The Express request and response objects are passed into
21
    // your context initialization function
22
    context: async ({ req, res }) => {
23
      // Here is where you'll have access to the
24
      // API Gateway event and Lambda Context
25
      const { event, context } = serverlessExpress.getCurrentInvoke();
26
      return {
27
        expressRequest: req,
28
        expressResponse: res,
29
        lambdaEvent: event,
30
        lambdaContext: context,
31
      };
32
    },
33
  }),
34
);
35

36
exports.handler = serverlessExpress({ app });

1
const { ApolloServer } = require('@apollo/server');
2
const { expressMiddleware } = require('@apollo/server/express4');
3
const serverlessExpress = require('@vendia/serverless-express');
4
const express = require('express');
5
const { json } = require('body-parser');
6
const cors = require('cors');
7

8
const server = new ApolloServer({
9
  typeDefs: 'type Query { x: ID }',
10
  resolvers: { Query: { x: () => 'hi!' } },
11
});
12

13
server.startInBackgroundHandlingStartupErrorsByLoggingAndFailingAllRequests();
14

15
const app = express();
16
app.use(
17
  cors(),
18
  json(),
19
  expressMiddleware(server, {
20
    // The Express request and response objects are passed into
21
    // your context initialization function
22
    context: async ({ req, res }) => {
23
      // Here is where you'll have access to the
24
      // API Gateway event and Lambda Context
25
      const { event, context } = serverlessExpress.getCurrentInvoke();
26
      return {
27
        expressRequest: req,
28
        expressResponse: res,
29
        lambdaEvent: event,
30
        lambdaContext: context,
31
      };
32
    },
33
  }),
34
);
35

36
exports.handler = serverlessExpress({ app });

Edit on GitHub

Proxy configuration

Heroku