I’m presenting this write up in two segments.

1. The first chunk is on demonstrating how to deploy a web app, using various languages and frameworks, to AWS Lambda.
2. The second chunk, which is optional, is using HashiCorp’s waypoint to automate all of the previous steps, and release your app to the public in roughly 60 seconds. (YMMV)

It will also help to have some prior understanding of the following topics:

• AWS Lambda
• Docker

Referenced code examples can be found at my demo repo.

Deploying to Lambda

If it listens on a port, you can deploy it to AWS Lambda...

AWS Lambda is an event-driven, serverless computing platform provided by Amazon as a part of Amazon Web Services. It is a computing service that runs code in response to events and automatically manages the computing resources required by that code. ¹

I won’t go into details of Lambda vs. server-ful alternatives like EC2, Digital Ocean Droplets, Heroku, or Kubernetes, since that is a different topic altogether with a ton of historic relevance that many others can speak to from experience ². I’ll simply focus on Lambda as the platform of choice here.

Build

Let‘s say you have some code for a typical web app backend or API.

import express from "express";
import morgan from "morgan";

export const createApp = () => {
  const app = express();

  app.use(morgan("short"));
  /** bunch of other middleware */

  app.get("/", (req, res) => {
    res.status(200).send("Hello from Node.js & Express!");
  });
  /** bunch of other routers and controllers */
};

import { createApp } from "./app";

const app = createApp();
const port = process.env.PORT || 8080;

app.listen(port, () => {
  console.log(`Listening on port ${port}`);
});

The first step in deploying this to Lambda is to package it into an OCI image with a tool like Docker. This is because we’ll also be adding a lambda extension via the Dockerfile, as well as publishing the built image to ECR, which is the only image registry that Lambda supports.

Additionally, this allows you to write your application code in programming languages that don’t have an official AWS Lambda runtime, namely Rust and Swift.

AWS Lambda Adapter

The star of the show is this neat lambda extension called aws-lambda-adapter ³. It enables you to run your long-running server code — some app listening on a port — on AWS Lambda.

Why this is so great is that it does not require any special configuration or bespoke code paths to make your app compatible with an ephemeral environment like Lambda. If you can containerize and run it locally, the adapter will make it just work on Lambda.

Furthermore, using it requires only a few additional lines in your Dockerfile. Here are a few examples of what that may look like for a few different languages.

###########
# builder #
###########
FROM golang:1.18 as builder

WORKDIR /go/src/app
COPY *.go .

RUN go mod init
RUN go get -d -v ./...
RUN go vet -v
RUN go test -v
RUN CGO_ENABLED=0 go build -o /go/bin/app

FROM golang:1.18-alpine
COPY --from=builder /go/bin/app /

# READINESS_CHECK_PORT and PORT are used by https://github.com/aws-samples/aws-lambda-adapter/blob/main/src/main.rs
ENV READINESS_CHECK_PORT=7531
ENV PORT=7531
COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.3.2 /lambda-adapter /opt/extensions/lambda-adapter

CMD ["/app"]

Push

Getting your app’s Docker image to ECR involves a series of steps/commands:

• Build the image

  export ACCOUNT_ID=fixme
  export REPOSITORY=fixme
  export TAG=fixme
  
  docker build -t $REPOSITORY:$TAG .
  

• Authenticate with ECR

  aws ecr get-login-password | docker login -u AWS --password-stdin $ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com
  

• Create repository

  aws ecr create-repository --repository-name $REPOSITORY --image-scanning-configuration scanOnPush=true --image-tag-mutability MUTABLE
  

• Push the image to ECR

  docker push $ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/$REPOSITORY:$TAG
  

...but this will grow very tedious if you need to build and push many times.

See ECR docs for commands to authenticate and push images to ECR.

Release

With the ECR image published, the Lambda function can be created, using said image.

export FUNCTION_NAME=fixme
export ACCOUNT_ID=fixme
export REPOSITORY=fixme
export TAG=fixme

aws lambda create-function \
  --package-type Image \
  --function-name $FUNCTION_NAME \
  --code ImageUri=$ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/$REPOSITORY:$TAG \
  --role arn:aws:iam::$ACCOUNT_ID:role/some-role-assumable-by-lambda

To release the function to the public internet, a Lambda URL ⁴ can be created, which will look something like: https://qvomz3om452pulf5joiuyojwc40ekond.lambda-url.us-east-1.on.aws

aws lambda create-function-url-config --function-name $FUNCTION_NAME --auth-type NONE

{
    "FunctionUrl": "https://jpifawiw5voowv2a7t26kv52ny0knwwa.lambda-url.us-east-1.on.aws/",
    "FunctionArn": "arn:aws:lambda:us-east-1:<ACCOUNT_ID>:function:<FUNCTION_NAME>",
    "AuthType": "NONE",
    "CreationTime": "2022-04-25T03:04:32.385115Z"
}

At this point, your lambda should be fully invokable by the public internet.

Doing any of the previous steps via the AWS CLI is quite cumbersome. Doing this via the console is slightly less painful due to small things that get handled for you like various IAM roles and permissions. But all of this is already taken care of you by a nifty tool.

Automate with waypoint

All the previous steps, which could be handled via a series of CLI commands and/or manual console clicking, can be automated with a single command: waypoint up.

Waypoint allows developers to deploy, manage, and observe their applications through a consistent abstraction of underlying infrastructure.

But first, you need a few mostly trivial things...

• waypoint installed...

  brew tap hashicorp/tap
  brew install hashicorp/tap/waypoint
  

• A valid config file:

  # waypoint.hcl
  project = "go"
  app "gin" {
    build {
      use "docker" {
        buildkit   = true
        platform = "arm64"
        dockerfile = "${path.app}/Dockerfile"
      }
  
      registry {
        use "aws-ecr" {
          region     = var.region
          repository = "go-gin"
          tag        = var.tag
        }
      }
    }
  
    deploy {
      use "aws-lambda" {
        region = var.region
        memory = 512
      }
    }
  
    release {
      use "lambda-function-url" {
  
      }
    }
  }
  
  variable "tag" {
    default     = "latest"
    type        = string
    description = "A tag"
  }
  
  variable "region" {
    default     = "us-east-1"
    type        = string
    description = "AWS Region"
  }
  
  The highlighted stanza, which is a Lambda URL releaser component, is not yet available in waypoint. You can simply comment it out, and waypoint up will still automate all the previous steps, minus the Lambda URL creation.
  
  See: Open PR #3187

• A Waypoint server running; Running one on Docker on your local machine is easy peasy...

  waypoint install -platform=docker -accept-tos
  

• And a project initialized...

  waypoint init
  

...and you’re ready to go...

waypoint up

In the following terminal screenshot, you can see that Waypoint finished in 50 seconds. This example was using the Golang project, for which the Docker image builds quite fast on my M1 Macbook Pro. The Swift and Rust Docker images take significantly longer.

With that being said, your mileage may vary!

Result

Here’s a table of the languages and frameworks that I was able to containerize and deploy:

I attempted but failed to get working examples for the following languages and frameworks:

• Ruby + Rails
  • Rails is pretty stateful and writes to a local /tmp directory. This causes the container to crash since the Lambda environment treats that directory as read-only.
• PHP + symfony
  • I have yet to learn the build tools/steps for PHP/symfony. (I never touched it before!)
• Deno:
  • I was able to containerize and run a simple app locally. It just didn’t want to work on Lambda. Reason TBD.

Thanks for reading! If you have any quetions or feedback, please feel free to comment below.

Until next time!