lambda on Barney Parker

Installing NPM Dependencies with Terraform

Tue, 23 Jun 2020 14:29:42 +0000

Terraform has the capability to create a zip file containing Function code, and for simpler functions that’s fine. For more complex functions it quickly becomes necessary to install dependencies to make avoid the need to write every line of code ourselves.

The problem with Terraform is that it only wants to do things that have a Provider resource. npm installing dependencies needs to be done outside of this, and while we could manually there is no way to guarantee we will remember to do it every time we apply.

In order to keep this inside out Terraform workflow we need to abuse some resources a little.

Triggering Dependency Installation

To convince Terraform to install our dependencies, we need to know

Has package.json changed?
Has package-lock.json changed?
Do we have all the files we expected?

We also need to store something in the state file that we can compare to in the future.

resource "null_resource" "lambda_dependencies" {
provisioner "local-exec" {
 command = "cd ${path.module}/src && npm install"
}
 triggers = {
 index = sha256(file("${path.module}/src/index.js"))
 package = sha256(file("${path.module}/src/package.json"))
 lock = sha256(file("${path.module}/src/package-lock.json"))
 node = sha256(join("",fileset(path.module, "src/**/*.js")))
}
}

a null_resource doesn’t do anything in itself, but it acts as a container that we can use to create one resource based on a set of trigger values.

local-exec allows us to run a system command, which in our case is to move in to the Lambda Function source directory and execute npm install.

We can set triggers based on our requirement, i.e. has index.js, package.json or package-lock.json changed by checking their sha256 signatures. We can also get a list of every .js file in the source directory, join them in to a single string and then get the sha256 of that string.

These trigger values will be stored in the state file, so even if we run this on another machine we’re going to be able to tell if anything doesn’t match between the previous deployment and this one. If something doesn’t match, then the local-exec command will be executed, and our dependencies installed!

Building the Bundle

So far so good, but we need to enforce Terraform ordering in the dependency graph. If we just add an archive_file data resource there’s no guarantee it will wait for the dependencies to be installed before creating the bundle.

To fix this we add an intermediate resource called a null_data_source. These resources take a bunch of inputs which can be computed form the outputs of other resources or variables. Until all of the inputs are satisfied Terraform wont allow anything depending on the null_data_source to be created or modified.

data "null_data_source" "wait_for_lambda_exporter" {
 inputs = {
 lambda_dependency_id = "${null_resource.lambda_dependencies.id}"
 source_dir = "${path.module}/src/"
}
}

The lambda_dependency_id input wont be known to Terraform until the previous null_resource has completed - which means our npm install has either been completed, or nothing had changed and it wasn’t required.

The source_dir input can be pre-computed by Terraform, and we will use this value to tell the archive_file what to add to the bundle.

Finally we create our archive_file:

data "archive_file" "lambda" {
 output_path = "${path.module}/lambda-bundle.zip"
 source_dir = "${data.null_data_source.wait_for_lambda_exporter.outputs["source_dir"]}"
 type = "zip"
}

So now we’re creating our archive_file.lambda from the path given to us by null_data_source.wait_for_lambda_exporter, which wont give us an answer until null_resource.lambda_dependencies is satisfied, which ensures the correct dependency ordering is maintained!

Less than ideal

There is one minor issue with this method. On the first run there is no node modules, so the null_resource.lambda_dependencies.trigger.node value gets an initial sha256 value, and that causes npm install to be executed. This will then change the sha256 that would be computed to the src directory, and a second run would also create a new bundle. subsequent runs wont do this, but in an ideal world a single run should be all that is needed to converge our required to actual states.

Its certainly not perfect, but if you can tolerate this one caveat, its a relatively simple way to include node dependencies without having to do anything more elaborate than a normal deployment.

HTTP APIs with Simple Lambda Functions

Fri, 19 Jun 2020 07:56:34 +0000

API Gateway has always been somewhat of a beast to configure, and while its incredibly flexible its also far more hassle than most people want or need. Terraform was also completely the wrong tool for deploying these because of the sheer number of resources required and the need to deploy APIs to a stage just didn’t quite fit with the way Terraform works.

The new HTTP APIs, whilst almost completely un-google-able, are an amazingly simple was to expose Lambda Functions to the outside world. They’re easy to deploy, simple to define, have great 404 handling, built in JWT authentication, and an easy CORS config. Apart from the (currently!) missing service integrations, there’s literally nothing to dislike about them!

About The $default Route

HTTP APIs allow you to add a special route called $default which will essentially capture anything that doesn’t already have a route handler attached to it. It sounds like an ideal fallback route, but there is one caveat in that it will also capture CORS OPTIONS requests in some situations, which is definitely not what what I was expecting to happen with it.

The documentation doesn’t state this particularly clearly, but instead of using a $default route, instead you should use a /{proxy+} route to capture anything without a handler, which still allows the CORS requests to hit the HTTP APIs built-in handler without you needing to write any code.

Defining the API

Creating an API is pretty simple and allows you to create the CORS config at the same time:

resource "aws_apigatewayv2_api" "api" {
 name = "v2-http-api"
 protocol_type = "HTTP"
cors_configuration {
 allow_credentials = false
 allow_headers = ["*"]
 allow_methods = ["*"]
 allow_origins = ["*"]
 expose_headers = ["*"]
 max_age = 3600
}
}

This resource creates an HTTP type API in API Gateway, and adds an extremely open CORS policy. You would likely want to tie this down a little more, but this policy makes the API open everywhere which is easy for testing.

The Stage (With Logging)

Its good to be able to get request log files, which in AWS terms means a CloudWatch Log Group. In out case that needs to be attached to the API Stage. Incidentally HTTP APIs can be configured to “auto-deploy”, i.e. you don’t have to tell it to update the stage, just updating the API routes is enough.

resource "aws_cloudwatch_log_group" "api_logs" {
 name = "/api/logs"
 retention_in_days = 30
}
resource "aws_apigatewayv2_stage" "stage" {
 api_id = aws_apigatewayv2_api.api.id
 name = "$default"
 auto_deploy = true
access_log_settings {
 destination_arn = aws_cloudwatch_log_group.api_logs.arn
 format = jsonencode(
{
 httpMethod = "$context.httpMethod"
 ip = "$context.identity.sourceIp"
 protocol = "$context.protocol"
 requestId = "$context.requestId"
 requestTime = "$context.requestTime"
 responseLength = "$context.responseLength"
 routeKey = "$context.routeKey"
 status = "$context.status"
}
)
}
lifecycle {
 ignore_changes = [
deployment_id,
default_route_settings
]
}
}

The lifecycle block at the bottom is necessary at the time of writing due to some slight oddities between the way HTTP APIs work and the way Terraform works. Basically it tells Terraform to ignore the deployment_id and default_route_settings fields if AWS says they don’t match whats in the state file.

The access_log_settings.format field specifies the log format. You can find more about that in the AWS Docs

There are some other resources available at this level to allow you to add a domain name and map this stage on to it, and to create a JWT Authorizer config, but for the sake of simplicity I will explore those in a separate article.

Adding a Route

Adding Routes in V1 of API Gateway required a lot of work. Multiple path segments, a resource to handle the incoming request, one for the Integration, another for the integration response and multiple resources for potential return codes. There is a lot to love about all that including VTL templates doing a lot of work for you, and being able to avoid calling Lambda Functions altogether, but it really was an awful lot of resources, and Terraform is very verbose. There were even some timing issues with AWS eventual consistency that made deployment of infra code changes quite painful.

HTTP APIs have done away with all of that in favour of a single resource for the route, and another one for the integration of the lambda function (with the option to add the JWT Authorizer)

resource "aws_apigatewayv2_route" "route" {
 api_id = aws_apigatewayv2_api.api.id
 route_key = "GET /{proxy+}"
 target = "integrations/${aws_apigatewayv2_integration.integration.id}"
}
resource "aws_apigatewayv2_integration" "integration" {
 api_id = aws_apigatewayv2_api.api.id
 integration_type = "AWS_PROXY"
 connection_type = "INTERNET"
 description = "This is our {proxy+} integration"
 integration_method = "POST"
 integration_uri = aws_lambda_function.lambda.invoke_arn
 passthrough_behavior = "WHEN_NO_MATCH"
lifecycle {
 ignore_changes = [
passthrough_behavior
]
}
}

The fields are fairly self-explanatory, the aws_apigatewayv2_route attached a specific route to an API, and directs it to an integration.

The aws_apigatewayv2_integration tells API Gateway to forward the request to a Lambda function as an AWS_PROXY integration type, using a POST request to the Lambda service.

At some point there will be more integrations (you can already pass through to another API via a VPC link for example) however Lambda is the only service currently integrated with HTTP APIs.

Again, due to time of writing oddities in Terraform we need to add a lifecycle block to ignore the passthrough_behaviour field if it changes in AWS.

The Lambda Function Handler

The Lambda Function is as simple as providing the ARN (shown above). Given this is a {proxy+} route it could capture multiple route requests, and in our case we will handle just the / route and 404’s for anything not defined:

module.exports.handler = async (event) => {
console.log('Event: ', event)
if (event.path === '/') {
return {
statusCode: 200,
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
message: 'Welcome',
}),
}
} else {
return {
statusCode: 404,
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
message: 'Not Found',
}),
}
}
}

You can drop this code in to the resources created in the article Deploying Lambda Functions with Terraform and drop it straight in here.

Accessing the API

We’ve not added a domain name to map the API to, but we can still use the default url provided by API Gateway. The easiest way to get this is by adding an output to the code to tell Terraform to tell us what URL has been assigned to it:

output "api_url" {
 value = aws_apigatewayv2_stage.stage.invoke_url
}

You should now be able to curl the api_url that Terraform gives you and see that for a GET request on the / route you see a welcome response, a 404 response on all other requests, and an OPTIONS request should return the CORS response to allow browsers to access the API!

Deploying Lambda Functions with Terraform

Tue, 16 Jun 2020 20:05:28 +0000

Serverless architectures are built from a collection of Managed service wired together to create a specific service. This could be anything from a shopping cart to a full ETL solution. The advantage of building applications this way is that each of the component parts are fully managed by AWS. That means you (either the developer or company) don’t have to worry about them functioning, you just need to make sure they’re wired together correctly.

Managed services are great, but these service only offer basic functionality such as queues or databases. What they can’t do is know how your business actually adds value to the world.

Lambda functions are the Serverless super-hero because they let you run your own code without ever having to worry about how the server operates (yes, there are servers!) or even how how to install the software that runs your code.

There are a lot of ways to deploy AWS infrastructure, and even more for Serverless infrastructure, but my personal favourite is Terraform. Its designed to allow you to write your infrastructure as code (IaC) and is surprisingly flexible. It also allows you to interact with non-AWS services which can really help tie everything together.

Terraform can be a little verbose, but its very easy to understand, and very simple to work with. On the face of it Terraform doesn’t obviously lend itself to Serverless, but that’s because it designed to give you extremely low-level access to APIs in the form of Resources.

In this article I will show you the minimal set of code required to deploy a lambda function. Its not going to be production-ready, or even do anything very impressive, but its going to introduce at an entry level the minimal components required.

About Terraform

Terraform works by creating a direct-graph of resources. The resource dependency order can be determined by using outputs from one resource as the inputs to another. Terraform can then deploy resources which have no outstanding dependencies recursively until all resources have been deployed with their dependencies satisfied.

Terraform then creates a state file which it uses on further deployments to identify which specific resources in AWS it should be adding, deleting or modifying. State files can be stored in local files or remotely, but for now we will just keep them locally.

Terraform Meta-Resources

Terraform is incredibly configurable, and to do that it happily eats it own dog-food by configuring with Terraform resources! This is the content of a file I like to call meta.tf:

terraform {
 required_version = "> 0.12"
}
provider "aws" {
 region = "eu-west-1"
 version = ">= 2.61.0"
}

The terraform block tells Terraform to use a version no less that 0.12.0. While older versions are available, this version added some functionality that makes it a little easier to code and so is a good base.

The provider block tells Terraform that we want to use AWS resources, we want to place them in the eu-west-1 region and we want to use a provider version no less than 2.61.0

Creating the Lambda Function Bundle

A Lambda Function needs some code to run. The code can be in a variety of languages but in this case we’re going to use Javascript. Here is some simple code that we’re going to deploy:

To supply the code to the Lambda Function it needs to be in a Zip file. Terraform can create these zip files for us, and for simplicity we’re going to define the Function code inline:

data "archive_file" "lambda" {
 type = "zip"
 output_path = "${path.module}/.terraform/lambda.zip"
source {
 filename = "index.js"
 content = <<-EOF
 module.exports.handler = async (event, context) => {
console.log("EVENT: \n" + JSON.stringify(event, null, 2))
console.log("CONTEXT: \n" + JSON.stringify(context, null, 2))
return Promise.resolve()
}
EOF
}
}

Lines 7-10 will be written to a file called index.js which will be added to a zip file called lambda.zip. ${path.module} will be interpolated as the local path during deployment. The code exports a function called handler. Keep these in mind as they will be useful when we actually deploy our function.

The code is extremely simple: it’s going to print out the Event and Context objects which will be passed to it upon execution. This is how the function will get information related to its execution.

The Log File

Since the Lambda Function is running inside of AWS, we need some way to capture its output. The Lambda service automatically captures anything which would normally be sent to stdin and stderr and store that in a CloudWatch Log Stream. Although the Lambda service will create the Log Group, its best practice to create this yourself and set an expiry period so that the logs are automatically cleared out after a period of time:

resource "aws_cloudwatch_log_group" "lambda_log_group" {
 name = "/aws/lambda/${aws_lambda_function.lambda.function_name}"
 retention_in_days = 30
}

All Lambda functions log to a log group called /aws/lambda/<lambda name> and so we’re creating that and capturing the name from the Lambda Function resource (created very soon!)

We also set the logs to expire after 30 days. Logs are pretty cheap, but if the function is called a lot or it generates a lot of log output the cost can quickly mount up so after a short period we want AWS to delete them on our behalf.

Permissions

In order to be able to interact with any other service, AWS resources need an IAM Role which can be “assumed” by the calling service. In our case that’s the Lambda service:

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

The role needs to have policies associated with it in order to define what its allowed to do. In our case the only thing we need permission to do is to create Log Streams within the Log Group, and write to them. Policies can be stand-alone, re-usable policies, or in-line policies specific to this function. For simplicity in this case we’re going to create an in-line policy:

resource "aws_iam_role_policy" "logging" {
 name = "Cloudwatch-Logs"
 role = aws_iam_role.lambda.name
 policy = <<-EOF
{
"Statement": [
{
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents"
],
"Effect": "Allow",
"Resource": "arn:aws:logs:*:*:*"
}
]
}
EOF
}

The Lambda Function

At last we have all the pieces in place to be able to create our Lambda Function resource. Here we will give it a name, point it to our code bundle, tell it what runtime to use and what exported function to execute and what Role it should be assuming to give itself the correct permissions:

resource "aws_lambda_function" "lambda" {
 function_name = "simplest_lambda_function"
 filename = data.archive_file.lambda.output_path
 source_code_hash = data.archive_file.lambda.output_base64sha256
 runtime = "nodejs12.x"
 handler = "index.handler"
 role = aws_iam_role.lambda.arn
}

Terraform hides some nasty internal values such as ARNs and file hashes by taking the outputs from some of the resources we created earlier as inputs to this resource. In doing so we have also implied the dependencies of resources and helped Terraform work out what order things should be deployed.

Deploying the Function

To start the deployment process, Terraform needs to be initialised with the command:

terraform init

This will ensure we’re using a valid version of Terraform and download the providers specified in meta.tf (or a default if we didn’t specify a version). All of its internal “stuff” will be stored in a directory called .terraform

To see what Terraform is going to do execute the following command:

terraform plan

You should get an output something like:

Refreshing Terraform state in-memory prior to plan...
The refreshed state will be used to calculate this plan, but will not be
persisted to local or remote state storage.
data.archive_file.lambda: Refreshing state...
------------------------------------------------------------------------
An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
+ create
Terraform will perform the following actions:

 # aws_cloudwatch_log_group.lambda_log_group will be created
 + resource "aws_cloudwatch_log_group" "lambda_log_group" {
 + arn = (known after apply)
 + id = (known after apply)
 + name = "/aws/lambda/simplest_lambda_function"
 + retention_in_days = 30
}

 # aws_iam_role.lambda will be created
 + resource "aws_iam_role" "lambda" {
 + arn = (known after apply)
 + assume_role_policy = jsonencode(
{
 + Statement = [
+ {
 + Action = "sts:AssumeRole"
 + Effect = "Allow"
 + Principal = {
 + Service = "lambda.amazonaws.com"
}
},
]
 + Version = "2012-10-17"
}
)
 + create_date = (known after apply)
 + force_detach_policies = false
 + id = (known after apply)
 + max_session_duration = 3600
 + name = "simplest_lambda_role"
 + path = "/"
 + unique_id = (known after apply)
}

 # aws_iam_role_policy.logging will be created
 + resource "aws_iam_role_policy" "logging" {
 + id = (known after apply)
 + name = "Cloudwatch-Logs"
 + policy = jsonencode(
{
 + Statement = [
+ {
 + Action = [
+ "logs:CreateLogGroup",
+ "logs:CreateLogStream",
+ "logs:PutLogEvents",
]
 + Effect = "Allow"
 + Resource = "arn:aws:logs:*:*:*"
},
]
}
)
 + role = "simplest_lambda_role"
}

 # aws_lambda_function.lambda will be created
 + resource "aws_lambda_function" "lambda" {
 + arn = (known after apply)
 + filename = "./.terraform/lambda.zip"
 + function_name = "simplest_lambda_function"
 + handler = "index.handler"
 + id = (known after apply)
 + invoke_arn = (known after apply)
 + last_modified = (known after apply)
 + memory_size = 128
 + publish = false
 + qualified_arn = (known after apply)
 + reserved_concurrent_executions = -1
 + role = (known after apply)
 + runtime = "nodejs12.x"
 + source_code_hash = "TFoUgCw/pW7Sy3/gY/TB3AtGzXoqRjN1L6YT066iPGg="
 + source_code_size = (known after apply)
 + timeout = 3
 + version = (known after apply)
+ tracing_config {
 + mode = (known after apply)
}
}
Plan: 4 to add, 0 to change, 0 to destroy.
------------------------------------------------------------------------
Note: You didn't specify an "-out" parameter to save this plan, so Terraform
can't guarantee that exactly these actions will be performed if
"terraform apply" is subsequently run.

This shows that Terraform will create 4 new resources:

The Log Group
An IAM Role
An Inline IAM Policy attached to the Role
Our Lambda Function

To actually create resources in AWS, execute:

terraform apply

When prompted, enter yes

Testing our Function

To invoke our function from the command line, execute:

`aws lambda invoke --function-name simplest_lambda_function /dev/null --log-type Tail --query 'LogResult' --output text | base64 -d`

which should respond with something similar to:

START RequestId: ab934699-7094-4829-8cee-aecd2c193583 Version: $LATEST
2020-06-16T16:58:46.098Z ab934699-7094-4829-8cee-aecd2c193583 INFO EVENT:
{}
2020-06-16T16:58:46.098Z ab934699-7094-4829-8cee-aecd2c193583 INFO CONTEXT:
{
"callbackWaitsForEmptyEventLoop": true,
"functionVersion": "$LATEST",
"functionName": "simplest_lambda_function",
"memoryLimitInMB": "128",
"logGroupName": "/aws/lambda/simplest_lambda_function",
"logStreamName": "2020/06/16/[$LATEST]759235165de84d3bbe7d3a87a7bd2db4",
"invokedFunctionArn": "arn:aws:lambda:eu-west-1:522711524578:function:simplest_lambda_function",
"awsRequestId": "ab934699-7094-4829-8cee-aecd2c193583"
}
END RequestId: ab934699-7094-4829-8cee-aecd2c193583
REPORT RequestId: ab934699-7094-4829-8cee-aecd2c193583 Duration: 2.86 ms Billed Duration: 100 ms Memory Size: 128 MB Max Memory Used: 63 MB Init Duration: 129.60 ms

While the command was a little long-winded, this is the log data you will also find in the CloudWatch Log Group. We can see the invocation id ab934699-7094-4829-8cee-aecd2c193583 and the content of the event and context objects. Finally we can see the REPORT line with tells us

The function took 2.86ms to run
It will be billed at 100ms (always rounded up to the nearest 100ms)
It was allocated 128MB of memory
At its peak, it actually used a total of 63MB of memory
It “Cold-Start” initialisation time was 129.6ms

You can use these values to tune the function which I will address in a future post.

Cleaning Up

Since this was just a simple demo, you probably want to remove all these resources at some point. To do so execute:

terraform destroy

Final Remarks

This function doesn’t do a great deal, and right now we can only invoke it from either the command line or from the AWS Lambda console, but it covers the basics of using Terraform to get it, and all its supporting resources deployed.

For more information see the official Terraform site.