Serverless computing is a cloud computing model in which a cloud provider automatically manages the provisioning and allocation of compute resources. This contrasts with traditional cloud computing where the user is responsible for directly managing virtual servers.

A popular approach to running "serverless" web applications is to implement the application functionality as one or more functions in AWS Lambda and then expose these for public consumption using Amazon API Gateway.

This tutorial will show how to deploy such an architecture using Terraform. The tutorial assumes some basic familiarity with Lambda and API Gateway but does not assume any pre-existing deployment.

This is a slightly opinionated tutorial, which chooses to ignore the built-in versioning and staged deployment mechanisms in AWS Lambda and API Gateway. In many cases these features are not necessary when using Terraform because changes can be tracked and deployed by keeping the Terraform configuration in a version-control repository. It also uses API Gateway in a very simple way, proxying all requests to a single AWS Lambda function that is expected to contain its own request routing logic.

As usual, there are other valid ways to use these services that make different tradeoffs. We encourage readers to consult the official documentation for the respective services for additional context and best-practices. This tutorial can still serve as an introduction to the main resources associated with these services, even if you choose a different architecture.

»Prerequisites

This tutorial assumes that you are familiar with the standard Terraform workflow. If you are new to Terraform, complete the Get Started tutorials first.

For this tutorial, you will need:

Terraform 0.15.2+ installed locally.
The AWS CLI installed locally.
An AWS account with credentials configured for Terraform.

Your IAM credentials should have permissions to create Lambda functions and work with API Gateway. The simplest approach to get started is to use credentials with full administrative access in an AWS account used only for development.

Warning: Some of the infrastructure in this tutorial does not qualify for the AWS free tier. Destroy the infrastructure at the end of the guide to avoid unnecessary charges. We are not responsible for any charges that you incur.

»Build the Lambda function package

To build a function using AWS Lambda, you must package it in an archive containing the function source code and any other static files needed for execution.

Terraform is not a build tool, so you must prepare the zip file using a separate build process prior to deploying it with Terraform. For a real application, we recommend automating your build via a CI system configured to run any necessary build actions (library installation, compilation, etc), produce the deployment zip file as a build artifact, and then upload that artifact into an Amazon S3 bucket. AWS Lambda can be configured to load artifacts from S3.

For the sake of this tutorial, you will build a very simple AWS Lambda function and perform these build steps manually.

To begin, create an a directory for your function code called example. You will use this directory to create the archive, and place in it a single source file.

$ mkdir example

Change into the directory.

$ cd example

The sample function in this tutorial uses the JavaScript runtime. Create a file called main.js and add the following code:

'use strict'

exports.handler = function (event, context, callback) {
  var response = {
    statusCode: 200,
    headers: {
      'Content-Type': 'text/html; charset=utf-8',
    },
    body: '<p>Hello world!</p>',
  }
  callback(null, response)
}

The above is the simplest possible Lambda function for use with API Gateway, returning a hard-coded "Hello world!" response in the object structure that API Gateway expects.

Next, zip up main.js and put the resulting file alongside your current working directory.

$ zip ../example.zip main.js
  adding: main.js (deflated 33%)

Navigate back to your original directory.

$ cd ..

In a real build and deploy scenario, you would use an S3 bucket to stage your archive and hand off artifacts between the build and deploy process. For the sake of this tutorial, you will create a temporary S3 bucket using the AWS CLI.

Create an environment variable for your bucket name, replacing a <UNIQUE_ID> with an unique identifier of your choice to ensure that your name is globally unique. Your name and date are a good option.

$ export S3_BUCKET="terraform-serverless-example-<UNIQUE_ID>"

Create the S3 bucket using the AWS CLI.

$ aws s3api create-bucket --bucket=$S3_BUCKET --region=us-east-1

You can now upload your build artifact into this S3 bucket.

$ aws s3 cp example.zip s3://$S3_BUCKET/v1.0.0/example.zip

The S3 object path includes a version number to identify this build. Later in this tutorial you will deploy a new version of your function and create a new object for it in the S3 bucket.

»Create the Lambda function

With the source code artifact built and uploaded to S3, you can now write our Terraform configuration to deploy it. Create a new directory for your configured called learn-terraform-lambda.

$ mkdir learn-terraform-lambda

Change into the directory.

$ cd learn-terraform-lambda

Create a file named main.tf containing the following configuration. Be sure to update the bucket_name argument of the aws_lambda_function resource to match the bucket you created earlier.

terraform {
  required_providers {
    aws = {
      source = "hashicorp/aws"
    }
  }
}

provider "aws" {
   region = "us-east-1"
}

resource "aws_lambda_function" "example" {
   function_name = "ServerlessExample"

   # The bucket name as created earlier with "aws s3api create-bucket"
   s3_bucket = var.s3_bucket
   s3_key    = "v1.0.0/example.zip"

   # "main" is the filename within the zip file (main.js) and "handler"
   # is the name of the property under which the handler function was
   # exported in that file.
   handler = "main.handler"
   runtime = "nodejs10.x"

   role = aws_iam_role.lambda_exec.arn
}

 # IAM role which dictates what other AWS services the Lambda function
 # may access.
resource "aws_iam_role" "lambda_exec" {
   name = "serverless_example_lambda"

   assume_role_policy = <<EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": "sts:AssumeRole",
      "Principal": {
        "Service": "lambda.amazonaws.com"
      },
      "Effect": "Allow",
      "Sid": ""
    }
  ]
}
EOF

}

Each Lambda function must have an associated IAM role which dictates what access it has to other AWS services. Since your sample application does not require access to any AWS services, the above configuration specifies a role with no access policy.

Next, create a file called variables.tf and paste in the configuration below. This defines an input variable for the S3 bucket name.

variable "s3_bucket" {}

Initialize your Terraform directory to download the AWS provider.

$ terraform init

Initializing the backend...

Initializing provider plugins...
- Finding latest version of hashicorp/aws...
- Installing hashicorp/aws v3.40.0...
## ...

Terraform has been successfully initialized!

## ...

Now apply the configuration, passing in the s3_bucket input variable as a command line flag. Respond to the prompt with a yes to confirm the operation.

$ terraform apply -var s3_bucket=$S3_BUCKET

## ...

aws_iam_role.lambda_exec: Creating...
  arn:                   "" => "<computed>"
  assume_role_policy:    "" => "{\n  \"Version\": \"2012-10-17\",\n  \"Statement\": [\n    {\n      \"Action\": \"sts:AssumeRole\",\n      \"Principal\": {\n        \"Service\": \"lambda.amazonaws.com\"\n      },\n      \"Effect\": \"Allow\",\n      \"Sid\": \"\"\n    }\n  ]\n}\n"
  create_date:           "" => "<computed>"
  force_detach_policies: "" => "false"
  name:                  "" => "serverless_example_lambda"
  path:                  "" => "/"
  unique_id:             "" => "<computed>"
aws_iam_role.lambda_exec: Creation complete after 1s (ID: serverless_example_lambda)
aws_lambda_function.example: Creating...
  arn:              "" => "<computed>"
  function_name:    "" => "ServerlessExample"
  handler:          "" => "main.handler"
  invoke_arn:       "" => "<computed>"
  last_modified:    "" => "<computed>"
  memory_size:      "" => "128"
  publish:          "" => "false"
  qualified_arn:    "" => "<computed>"
  role:             "" => "arn:aws:iam::123456:role/serverless_example_lambda"
  runtime:          "" => "nodejs6.10"
  s3_bucket:        "" => "terraform-serverless-example"
  s3_key:           "" => "v1.0.0/example.zip"
  source_code_hash: "" => "<computed>"
  timeout:          "" => "3"
  tracing_config.#: "" => "<computed>"
  version:          "" => "<computed>"
aws_lambda_function.example: Still creating... (10s elapsed)
aws_lambda_function.example: Creation complete after 11s (ID: ServerlessExample)

Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

Once Terraform creates the function, try invoking it using the AWS CLI.

$ aws lambda invoke --region=us-east-1 --function-name=ServerlessExample output.txt
{
    "StatusCode": 200,
    "ExecutedVersion": "$LATEST"
}

Check the contents of output.txt to confirm that the function is working as expected.

$ cat output.txt
{
  "statusCode":200,
  "headers":{
    "Content-Type":"text/html; charset=utf-8"
  },
  "body":"<p>Hello world!</pz>"
}

Now you will create the API Gateway REST API that will provide access to your function.

»Configure API Gateway

API Gateway's name reflects its original purpose as a public-facing frontend for REST APIs, but it was later extended with features that make it easy to expose an entire web application based on AWS Lambda. These newer features will be used in this tutorial. The term "REST API" is thus used loosely here, since API Gateway is serving as a generic HTTP frontend rather than necessarily serving an API.

Create a new file api_gateway.tf in the same directory as your main.tf file from the previous step.

Add the following to api_gateway.tf to configure the root "REST API" object.

resource "aws_api_gateway_rest_api" "example" {
  name        = "ServerlessExample"
  description = "Terraform Serverless Application Example"
}

The "REST API" is the container for all of the other API Gateway objects you will create.

All incoming requests to API Gateway must match with a configured resource and method in order to be handled. Append the following to the api_gateway.tf file to define a single proxy resource.

resource "aws_api_gateway_resource" "proxy" {
   rest_api_id = aws_api_gateway_rest_api.example.id
   parent_id   = aws_api_gateway_rest_api.example.root_resource_id
   path_part   = "{proxy+}"
}

resource "aws_api_gateway_method" "proxy" {
   rest_api_id   = aws_api_gateway_rest_api.example.id
   resource_id   = aws_api_gateway_resource.proxy.id
   http_method   = "ANY"
   authorization = "NONE"
}

The special path_part value "{proxy+}" activates proxy behavior, which means that this resource will match any request path. Similarly, the aws_api_gateway_method block uses a http_method of "ANY", which allows all request methods. Taken together, this means that all incoming requests will match this resource.

Each method on an API gateway resource has an integration which specifies how to route incoming requests. Add the following configuration to api_gateway.tf to specify that requests to this method should be sent to the Lambda function defined earlier.

resource "aws_api_gateway_integration" "lambda" {
   rest_api_id = aws_api_gateway_rest_api.example.id
   resource_id = aws_api_gateway_method.proxy.resource_id
   http_method = aws_api_gateway_method.proxy.http_method

   integration_http_method = "POST"
   type                    = "AWS_PROXY"
   uri                     = aws_lambda_function.example.invoke_arn
}

The AWS_PROXY integration type causes API gateway to call into the API of another AWS service. In this case, it will call the AWS Lambda API to create an "invocation" of the Lambda function.

Unfortunately the proxy resource cannot match an empty path at the root of the API. To handle that, add the following to api_gateway.tf to configure the REST API object's root resource.

resource "aws_api_gateway_method" "proxy_root" {
   rest_api_id   = aws_api_gateway_rest_api.example.id
   resource_id   = aws_api_gateway_rest_api.example.root_resource_id
   http_method   = "ANY"
   authorization = "NONE"
}

resource "aws_api_gateway_integration" "lambda_root" {
   rest_api_id = aws_api_gateway_rest_api.example.id
   resource_id = aws_api_gateway_method.proxy_root.resource_id
   http_method = aws_api_gateway_method.proxy_root.http_method

   integration_http_method = "POST"
   type                    = "AWS_PROXY"
   uri                     = aws_lambda_function.example.invoke_arn
}

Finally, add the following configuration to api_gateway.tf to create an API Gateway "deployment". This activates the configuration and exposes the API at a URL that can be used for testing.

resource "aws_api_gateway_deployment" "example" {
   depends_on = [
     aws_api_gateway_integration.lambda,
     aws_api_gateway_integration.lambda_root,
   ]

   rest_api_id = aws_api_gateway_rest_api.example.id
   stage_name  = "test"
}

With all of the above configuration changes in place, run terraform apply again to create these new objects:

$ terraform apply -var s3_bucket=$S3_BUCKET

## ...

aws_api_gateway_rest_api.example: Creating...
  created_date:     "" => "<computed>"
  description:      "" => "Terraform Serverless Application Example"
  name:             "" => "ServerlessExample"
  root_resource_id: "" => "<computed>"
aws_api_gateway_rest_api.example: Creation complete after 1s (ID: bkqhuuz8r8)

## ...

Apply complete! Resources: 7 added, 0 changed, 0 destroyed.

Once Terraform provisions the resources, AWS will display them in the API Gateway console.

The integration with the Lambda function is not functional yet because API Gateway does not have the necessary access to invoke the function. The next step will address this, making the application fully-functional.

»Allow API Gateway to Access Lambda

To enable AWS services to access one another, you must explicitly define the appropriate permissions. For Lambda functions, access is granted using the aws_lambda_permission resource. Add the following configuration to main.tf:

resource "aws_lambda_permission" "apigw" {
   statement_id  = "AllowAPIGatewayInvoke"
   action        = "lambda:InvokeFunction"
   function_name = aws_lambda_function.example.function_name
   principal     = "apigateway.amazonaws.com"

   # The "/*/*" portion grants access from any method on any resource
   # within the API Gateway REST API.
   source_arn = "${aws_api_gateway_rest_api.example.execution_arn}/*/*"
}

In order to test the created API, you will need to access its test URL. To make this easier to access, add the following output to api_gateway.tf:

output "base_url" {
  value = aws_api_gateway_deployment.example.invoke_url
}

Apply the latest changes with terraform apply:

$ terraform apply -var s3_bucket=$S3_BUCKET

## ...

aws_lambda_permission.apigw: Creating...
  statement_id:  "" => "AllowAPIGatewayInvoke"
  action:        "" => "lambda:InvokeFunction"
  function_name: "" => "ServerlessExample"
  ## ...
aws_lambda_permission.apigw: Creation complete after 1s

Apply complete! Resources: 1 added, 0 changed, 1 destroyed.

Outputs:

base_url = https://bkqhuuz8r8.execute-api.us-east-1.amazonaws.com/test

Load the URL given in the output from your run in your web browser. You should see the text "Hello world!". The API Gateway routes your request to the Lambda function you uploaded earlier, which returns this message.

This is a good milestone! The first version of the application is deployed and accessible. Next you will learn how to deploy a new version of the application.

»Deploy a new version of the Lambda function

As you continue to develop your applications, you will need to deploy new versions of your Lambda functions.

Navigate back to the example directory containing the main.js file.

cd ../example

Update the source code in main.js to change the message. For example:

'use strict'

exports.handler = function (event, context, callback) {
  var response = {
    statusCode: 200,
    headers: {
      'Content-Type': 'text/html; charset=utf-8',
    },
    body: '<p>Bonjour au monde!</p>',
  }
  callback(null, response)
}

Next, recreate the archive.

$ zip ../example.zip main.js
updating: main.js (deflated 33%)

Change to the directory that contains that zip file.

$ cd ..

Finally, upload a new version to the artifact S3 bucket you created earlier.

$ aws s3 cp example.zip s3://$S3_BUCKET/v1.0.1/example.zip

Notice that S3 object path uses a different version number, so the previous archive is retained. In order to allow easy switching between versions, you can define a variable to allow the version number to be configured dynamically.

Navigate back to your learn-terraform-lambda directory.

$ cd learn-terraform-lambda

Add the following input variable definition to varibles.tf.

variable "app_version" {}

Then locate the aws_lambda_function resource defined earlier and change its s3_key argument to include the version variable:

resource "aws_lambda_function" "example" {
  function_name = "ServerlessExample"

  # The bucket name as created earlier with "aws s3api create-bucket"
  s3_bucket = var.s3_bucket
- s3_key    = "v1.0.0/example.zip"
+ s3_key    = "v${var.app_version}/example.zip"
  # (leave the remainder unchanged)
}

The terraform apply command now requires a version number input variable as well.

$ terraform apply -var s3_bucket=$S3_BUCKET -var app_version="1.0.1"
## ...

Terraform will perform the following actions:

  ~ aws_lambda_function.example
      s3_key: "v1.0.0/example.zip" => "v1.0.1/example.zip"

Plan: 0 to add, 1 to change, 0 to destroy.

## ...

After Terraform applies the change, visit the URL in the output again to see the new greeting message.

»Rolling back to an older version

Sometimes new code does not work as expected and the simplest path is to revert to the previous version. Because all of the historical versions of the artifact are preserved on S3, you can revert to the original version with a single command:

$ terraform apply -var s3_bucket=$S3_BUCKET -var app_version="1.0.0"

After this apply completes, the test URL will return the original message again.

»Conclusion

In this tutorial you created an AWS Lambda function that produces a result compatible with Amazon API Gateway proxy resources and then configured API Gateway.

Although the AWS Lambda function used in this tutorial is very simple, in more practical applications it is possible to use helper libraries to map API Gateway proxy requests to standard HTTP application APIs in various languages, such as Python's WSGI or the NodeJS Express Framework.

When combined with an automated build process running in a CI system, Terraform can help to deploy applications as AWS Lambda functions, with suitable IAM policies to connect with other AWS services for persistent storage, access to secrets, etc.

»Cleaning Up

Once you are finished with this tutorial, you can destroy the example objects with Terraform. Since your configuration requires a version number as an input variable, provide a placeholder value to destroy:

$ terraform destroy -var s3_bucket=$S3_BUCKET -var app_version="1.0.0"

Since the artifact zip files and the S3 bucket itself were created outside of Terraform, they must also be cleaned up outside of Terraform. This can be done via the S3 console. Note that all of the objects in the bucket must be deleted before the bucket itself can be deleted.

»Further Reading

The following Terraform resource types are used in this tutorial:

The reference page for each resource type provides full details on all of its supported arguments and exported attributes.

»Custom Domain Names and TLS Certificates

For the sake of example, this tutorial uses the test URLs offered by default by API Gateway. In practice, most applications will be deployed at a custom hostname.

To use a custom domain name you must first register that domain and configure DNS hosting for it. You must also either create an Amazon Certificate Manager certificate or register a TLS certificate with a third-party certificate authority.

Configuring the domain name is beyond the scope of this tutorial, but if you already have a hostname and TLS certificate you wish to use then you can register it with API Gateway using the aws_api_gateway_domain_name resource type.

A registered domain name is then mapped to a particular "REST API" object using aws_api_gateway_base_path_mapping. The configured domain name then becomes an alias for a particular deployment stage.

»Making Changes to the API Gateway Configuration

This tutorial creates a very simple API Gateway Configuration with a single resource that passes through all requests to a single destination. The upgrade steps then modify only the AWS Lambda function, leaving the API Gateway configuration unchanged.

Due to API Gateway's staged deployment model, if you do need to make changes to the API Gateway configuration, you must explicitly request that Terraform replace the deployment resource.

Tip: The -replace flag was introduced in Terraform 0.15.2. Ensure you are using the correct version of Terraform for this next step.

$ terraform apply -replace="aws_api_gateway_deployment.example"

This command flags that this object must be re-created even if there are no changes to the Terraform configuration.

Please note that this "re-deployment" will cause some downtime, since Terraform will need to delete the stage and associated deployment before re-creating it. Downtime can be avoided by triggering the deployment action via the API Gateway console, outside of Terraform. The approach covered in this tutorial intentionally minimizes the need to amend the API Gateway configuration over time to mitigate this limitation. Better support for this workflow will be added to Terraform's AWS provider in a future release.

Infrastructure

Security

Networking

Applications