AWS Lambda with CDK

Deploying Restate services as AWS Lambda functions

You can deploy your Restate service handlers as AWS Lambda Functions. The Restate CDK support library provides convenient constructs for managing Restate service deployments on AWS Lambda.

The AWS Cloud Development Kit (CDK) provides an elegant way to define your cloud application infrastructure in a familiar programming language. Currently, we support CDK projects built in TypeScript, but you can deploy Restate handlers in any language supported by a Restate SDK. CDK is often used to manage serverless application stacks, and the Restate CDK constructs are the easiest method to deploy and manage Restate services on AWS Lambda.

If you don't have an existing CDK project, follow the CDK Getting started page to set one up.

Adding the Restate CDK support library

Add the Restate CDK support library to your project:

npm install @restatedev/restate-cdk

Deploy your handlers to AWS Lambda

Define one or more Lambda functions in your CDK stack to model the service handlers in your chosen language. Depending on the SDK and programming language, you may need an additional build process such as Gradle, to bundle your business logic in a Lambda-deployable artifact. To deploy Restate services we use the standard CDK Lambda constructs.

For more information about setting up an IAM role that works with Restate Cloud, please see the section on AWS Lambda services.

TypeScript

For TypeScript/JavaScript services, you can use the NodejsFunction construct to transpile and bundle all the required dependencies.

import * as lambda from "aws-cdk-lib/aws-lambda";
import { NodejsFunction } from "aws-cdk-lib/aws-lambda-nodejs";

const service = new NodejsFunction(scope, "RestateService", {
  runtime: lambda.Runtime.NODEJS_LATEST,
  architecture: lambda.Architecture.ARM_64,
  entry: "handler", // use the path to your service handler
});

Java

For Java/Kotlin services, you can use the regular function construct with a supported JVM runtime. This example assumes that some build process has already produced a "fat JAR" artifact containing all the required dependencies. For an example of how to do this in Gradle, refer to the hello-world-lambda-cdk project.

import * as lambda from "aws-cdk-lib/aws-lambda";

const serviceHandler: lambda.Function = new lambda.Function(scope, "RestateService", {
  runtime: lambda.Runtime.JAVA_21,
  architecture: lambda.Architecture.ARM_64,
  code: lambda.Code.fromAsset(".../lambda-all.jar"), // path to the "fat JAR" artifact
  handler: "com.example.service.LambdaHandler", // fully qualified handler class name
  timeout: cdk.Duration.seconds(10), // the default timeout of 3s may not be enough for initialization!
});

Optional: Deploy a self-hosted Restate server

Restate is very easy to deploy, and we provide a CDK construct to make it super simple to deploy a self-hosted development server on Amazon EC2. See Deploying Restate on Amazon EC2 with CDK for more information on how to deploy Restate using CDK. Alternatively, you can deploy and register services by targeting an existing Restate admin endpoint.

Deploy Restate services to a Restate environment

To enable Lambda handlers to receive Restate requests, we need to create a deployment in the desired Restate environment. To automate Lambda endpoint registration, use the ServiceDeployer construct in your stack which will take care of creating/updating Restate Deployments any time you deploy changes. Restate uses Lambda versioning to consistently target the same function configuration from a given deployment revision. This is a quiescent component: it deploys a custom CloudFormation resource provider which is handles deployment events only if any related resources in your CDK stack change.

Use the deployService method to tell the deployer about each service endpoint that you want to register. If the target Restate environment is only accessible in a VPC, you will need to configure the service deployer with the appropriate details.

Implicit permission grant

Calling deployService grants lambda:InvokeFunction to the environment's invoker role by default. You can disable this behavior using the skipInvokeFunctionGrant option.

Self-hosted Restate construct

The SingleNodeRestateDeployment deploys Restate environment backed by a single EC2 instance and is suitable for development and testing purposes.

EC2 instance creation

The EC2 instance will be created in the default VPC unless otherwise specified. The instance will be assigned a public IP address.

import * as restate from "@restatedev/restate-cdk";

const restateEnvironment = new restate.SingleNodeRestateDeployment(scope, "Restate", {});

const deployer = new restate.ServiceDeployer(stack, "ServiceDeployer");
deployer.deployService("RestateService", serviceHandler.currentVersion, restateEnvironment);

Custom environment

You can specify the target Restate environment explicitly:

import * as restate from "@restatedev/restate-cdk";

const restateEnvironment = RestateEnvironment.fromAttributes({
  adminUrl: environment.adminUrl,
  invokerRole: restateHandlerInvokerRole, // deployService grants invoke permissions for each registered handler
  authTokenSecretArn: restateAdminAuthToken.secretFullArn, // optional
});

const deployer = new restate.ServiceDeployer(stack, "ServiceDeployer");
deployer.deployService("RestateService", serviceHandler.currentVersion, restateEnvironment);

Complete examples

You can use the following examples as references for your own CDK projects:

• hello-world-lambda-cdk (Kotlin) - provides a simple example of a Lambda-deployed Kotlin handler with a CDK stack modeled in TypeScript
• hello-world-lambda-cdk (TypeScript) - provides a simple example of a Lambda-deployed TypeScript handler with a CDK stack modeled in TypeScript
• Restate Holiday - a more complex example of a fictional reservation service demonstrating the Saga orchestration pattern across multiple Restate services implemented in TypeScript