AWS Lambda

Run your Restate services on AWS Lambda.

Deploy your Restate services as serverless functions on AWS Lambda. This guide covers project setup, packaging, IAM permissions, service registration, and invocation.

There are two ways to deploy a Restate service on AWS Lambda:

• Use AWS CDK to start from a complete example that configures the Lambda deployment and its registration with Restate.
• Deploy manually and automate subsequent deployments and registration with GitHub Actions.

Deploy with AWS CDK

For a new Lambda deployment, we recommend starting from the TypeScript AWS CDK example:

restate example typescript-hello-world-lambda-cdk && cd typescript-hello-world-lambda-cdk

Then follow the example README to configure your AWS and Restate Cloud environment and deploy the stack.

The example uses the @restatedev/restate-cdk construct library to deploy the Lambda function, configure its execution and invoker roles, grant invocation permission, and register the published function version with Restate Cloud.

CDK examples are also available for Go, Java, and Kotlin.

Deploy manually

IAM roles used in the manual workflow

Three different IAM roles appear in the instructions. Each role has a separate purpose and is assumed by a different actor:

Role	Assumed by	Purpose	When you need it
Lambda execution role	The AWS Lambda service	Grants the function access to AWS services and resources while it runs	Every Lambda function
Restate invoker role	Restate Cloud, BYOC, or your self-hosted Restate deployment	Grants lambda:InvokeFunction for the deployed function	Always for Restate Cloud/BYOC; for Restate OSS when using an assumed role
CI/CD deploy role	GitHub Actions through OIDC	Uploads code, updates the function configuration, and publishes versions	Only when using the CI/CD workflow on this page

These roles are not interchangeable. In particular, Restate assumes the invoker role, while Lambda runs the function with the execution role.

1. Set up your project

   TypeScript

   Start from the TypeScript Lambda template.

   Create your Restate + TypeScript + Lambda repository

   Or convert your existing service to a Lambda handler.

   Python

   Start from the Python Lambda template.

   Create your Restate + Python + Lambda repository

   Or use an existing service.

   Java

   Download a quickstart template and convert the service to a Lambda handler.

   Kotlin

   Download a quickstart template and convert the service to a Lambda handler.

   Go

   Download a quickstart template and convert the service to a Lambda handler.

2. Package your function

   Build a deployment package containing your application code and dependencies.

   TypeScript

   Package your application as a zip file for Lambda:

   npm install
   npm run bundle
   

   Python

   Using uv, prepare a directory containing all the source and the dependencies, then zip it:

   mkdir -p dist
   # Install project and dependencies directly into dist using uv pip
   uv pip install --python 3.13 --target dist .
   # Copy source code
   cp *.py dist/
   # Zip the dist content
   cd dist && zip ../dist.zip -r * && cd ..
   

   When installing the dependencies, make sure the python version and your machine architecture match the one configured in the Lambda runtime. If you get an error like cannot import restate._internal, most likely you have a python version and/or architecture mismatch between the Lambda runtime and the machine where the packaging happens.

   Java

   Build an uber JAR with all dependencies using Gradle:

   ./gradlew shadowJar
   

   Or using Maven:

   mvn package
   

   The JAR file is written to build/libs/ or target/.

   Kotlin

   Build an uber JAR with all dependencies:

   ./gradlew shadowJar
   

   The JAR file is written to build/libs/.

   Go

   Build the Go binary for Lambda:

   GOOS=linux GOARCH=amd64 go build -o bootstrap main.go
   zip function.zip bootstrap
   

   This creates function.zip containing the bootstrap binary.

3. Deploy the Lambda function

   Create the function in the AWS Lambda console and upload the deployment package. For more details, follow the AWS Lambda documentation.

   When you create the function, AWS requires a Lambda execution role. Lambda assumes this role while your handler runs. Give it only the permissions the handler needs, such as permission to write logs or access application resources. This is not the role that Restate assumes to invoke the function.

   Configure the handler for your SDK:

   SDK	Lambda handler
   TypeScript	app.handler
   Python	handler.app
   Java or Kotlin	Your handler class, for example com.example.MyLambdaHandler
   Go	bootstrap

4. Allow Restate to invoke the function

   Configure how your Restate environment authenticates to AWS:

   Restate Cloud / BYOC

   Create a Restate invoker role in the same AWS account as your function. Restate assumes this role to call lambda:InvokeFunction. You can copy the IAM trust policy for your environment, in the Restate Cloud UI at Developers > Security > AWS Lambda.

   The role’s trust policy is configured so that only the Restate Cloud environments you specify can assume it. The role’s permissions policy should grant lambda:InvokeFunction only for the function you deployed.

   Restate OSS

   Give the AWS identity used by your self-hosted Restate deployment permission to call lambda:InvokeFunction on the function.

   You can grant that permission directly to Restate’s AWS identity, or create a separate Restate invoker role that trusts that identity. The registration command in the next step uses the separate-role approach.

   The invoker role is separate from the function’s execution role. The execution role grants permissions to the function while it runs; the invoker role grants Restate permission to invoke the function, and nothing else.

   An appropriately scoped AWS identity and IAM trust policy prevent unauthorized callers from invoking the function through AWS Lambda. You do not need request identity validation in this case, although request identity validation also works with Lambda endpoints if you want an additional check in the service itself.

5. Register the service with Restate

   Register the Lambda function with Restate using the CLI or UI:

   restate deployments register \
     arn:aws:lambda:region:account-id:function:function-name:version \
     --assume-role-arn <INVOKER_ROLE_ARN>
   

   <INVOKER_ROLE_ARN> is the Restate invoker role from the previous step, not the Lambda execution role. For Restate Cloud/BYOC, provide this role when registering the deployment. For Restate OSS, provide it if Restate assumes a separate invoker role; omit --assume-role-arn if the AWS identity used by Restate already has permission to invoke the function.

   Always register a specific Lambda version (not $LATEST) to ensure Restate routes requests to a stable deployment. Check the versioning documentation for more info.

6. Send your first request

   Restate Cloud / BYOC

   You’re set up! Go to the Overview page > Greeter > Playground and start sending requests to your service.

   Restate OSS

   You’re set up! Go to the Overview page > Greeter > Playground and start sending requests to your service.

CI/CD Automation

You can set up automation to upload a new Lambda version and register a new Restate service versions on every push to main.

If you’ve followed the steps above, then you already have the GitHub Actions workflow set up. All you need to do is to add the secrets below to your project.

Create the Lambda function before the first workflow run. The workflow publishes a new version of an existing function, it does not create one.

The workflow references two role ARNs for different operations. The AWS credentials step makes GitHub Actions assume AWS_DEPLOY_ROLE_TO_ASSUME. The registration step passes AWS_INVOKE_ROLE_TO_ASSUME to Restate so that Restate—not GitHub Actions—can assume it when invoking the function.

Restate Cloud / BYOC

TypeScript

.github/workflows/deploy.yml

name: Deploy to AWS Lambda

on:
  push:
    branches:
      - main

permissions:
  id-token: write   # This is required for OIDC authentication
  contents: read    # This is required to checkout the repository

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    environment: production
    env:
      AWS_REGION: us-east-1

    steps:
      - name: Checkout
        uses: actions/checkout@v5
      - uses: actions/setup-node@v5

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_TO_ASSUME }}
          aws-region: ${{ env.AWS_REGION }}

      - name: Install dependencies
        run: npm ci
      - name: Build
        run: npm run build

      - name: Deploy Lambda Function
        uses: aws-actions/aws-lambda-deploy@v1.1.0
        id: deploy
        with:
          function-name: my-greeter
          code-artifacts-dir: dist
          handler: app.handler
          runtime: nodejs22.x
          publish: true

      - name: Register Restate deployment
        env:
          RESTATE_ADMIN_URL: ${{ secrets.RESTATE_ADMIN_URL }}
          RESTATE_AUTH_TOKEN: ${{ secrets.RESTATE_AUTH_TOKEN }}
        run: npx -y @restatedev/restate deployment register -y ${{ steps.deploy.outputs.function-arn }}:${{ steps.deploy.outputs.version }} --assume-role-arn ${{ secrets.AWS_INVOKE_ROLE_TO_ASSUME }}

Python

.github/workflows/deploy.yml

name: Deploy to AWS Lambda

on:
  push:
    branches:
      - main

permissions:
  id-token: write   # This is required for OIDC authentication
  contents: read    # This is required to checkout the repository

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    environment: production
    env:
      AWS_REGION: us-east-1
      PYTHON_VERSION: 3.13
    steps:
      - name: Checkout
        uses: actions/checkout@v5

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_TO_ASSUME }}
          aws-region: ${{ env.AWS_REGION }}

      - name: Install uv
        uses: astral-sh/setup-uv@v5
        with:
          enable-cache: true

      - name: Set up Python
        run: uv python install ${{ env.PYTHON_VERSION }}

      - name: Build Lambda package
        run: |
          mkdir -p dist
          uv pip install --python ${{ env.PYTHON_VERSION }} --target dist .
          cp *.py dist/

      - name: Deploy Lambda Function
        uses: aws-actions/aws-lambda-deploy@v1.1.0
        id: deploy
        with:
          function-name: my-greeter
          code-artifacts-dir: dist
          handler: handler.app
          runtime: python${{ env.PYTHON_VERSION }}
          publish: true

      - name: Register Restate deployment
        env:
          RESTATE_ADMIN_URL: ${{ secrets.RESTATE_ADMIN_URL }}
          RESTATE_AUTH_TOKEN: ${{ secrets.RESTATE_AUTH_TOKEN }}
        run: npx -y @restatedev/restate deployment register -y ${{ steps.deploy.outputs.function-arn }}:${{ steps.deploy.outputs.version }} --assume-role-arn ${{ secrets.AWS_INVOKE_ROLE_TO_ASSUME }}

This workflow needs the following GitHub Actions repository secrets:

• RESTATE_ADMIN_URL: The Admin URL. You can find it in Developers > Admin URL
• RESTATE_AUTH_TOKEN: Your Restate Cloud auth token. To get one, go to Developers > API Keys > Create API Key, and make sure to select Admin for the role
• AWS_INVOKE_ROLE_TO_ASSUME: The Restate invoker role created in Allow Restate to invoke the function. Restate assumes this role when calling the published Lambda version
• AWS_DEPLOY_ROLE_TO_ASSUME: The CI/CD deploy role that GitHub Actions assumes to update and publish the function, as described below

Restate OSS

TypeScript

.github/workflows/deploy.yml

name: Deploy to AWS Lambda

on:
  push:
    branches:
      - main

permissions:
  id-token: write   # This is required for OIDC authentication
  contents: read    # This is required to checkout the repository

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    environment: production
    env:
      AWS_REGION: us-east-1

    steps:
      - name: Checkout
        uses: actions/checkout@v5
      - uses: actions/setup-node@v5

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_TO_ASSUME }}
          aws-region: ${{ env.AWS_REGION }}

      - name: Install dependencies
        run: npm ci
      - name: Build
        run: npm run build

      - name: Deploy Lambda Function
        uses: aws-actions/aws-lambda-deploy@v1.1.0
        id: deploy
        with:
          function-name: my-greeter
          code-artifacts-dir: dist
          handler: app.handler
          runtime: nodejs22.x
          publish: true

      - name: Register Restate deployment
        env:
          RESTATE_ADMIN_URL: ${{ secrets.RESTATE_ADMIN_URL }}
          RESTATE_AUTH_TOKEN: ${{ secrets.RESTATE_AUTH_TOKEN }}
        run: npx -y @restatedev/restate deployment register -y ${{ steps.deploy.outputs.function-arn }}:${{ steps.deploy.outputs.version }} --assume-role-arn ${{ secrets.AWS_INVOKE_ROLE_TO_ASSUME }}

Python

.github/workflows/deploy.yml

name: Deploy to AWS Lambda

on:
  push:
    branches:
      - main

permissions:
  id-token: write   # This is required for OIDC authentication
  contents: read    # This is required to checkout the repository

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    environment: production
    env:
      AWS_REGION: us-east-1
      PYTHON_VERSION: 3.13
    steps:
      - name: Checkout
        uses: actions/checkout@v5

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_TO_ASSUME }}
          aws-region: ${{ env.AWS_REGION }}

      - name: Install uv
        uses: astral-sh/setup-uv@v5
        with:
          enable-cache: true

      - name: Set up Python
        run: uv python install ${{ env.PYTHON_VERSION }}

      - name: Build Lambda package
        run: |
          mkdir -p dist
          uv pip install --python ${{ env.PYTHON_VERSION }} --target dist .
          cp *.py dist/

      - name: Deploy Lambda Function
        uses: aws-actions/aws-lambda-deploy@v1.1.0
        id: deploy
        with:
          function-name: my-greeter
          code-artifacts-dir: dist
          handler: handler.app
          runtime: python${{ env.PYTHON_VERSION }}
          publish: true

      - name: Register Restate deployment
        env:
          RESTATE_ADMIN_URL: ${{ secrets.RESTATE_ADMIN_URL }}
          RESTATE_AUTH_TOKEN: ${{ secrets.RESTATE_AUTH_TOKEN }}
        run: npx -y @restatedev/restate deployment register -y ${{ steps.deploy.outputs.function-arn }}:${{ steps.deploy.outputs.version }} --assume-role-arn ${{ secrets.AWS_INVOKE_ROLE_TO_ASSUME }}

This workflow needs the following GitHub Actions repository secrets:

• RESTATE_ADMIN_URL: The URL through which GitHub Actions can reach your Restate Admin API
• RESTATE_AUTH_TOKEN: Set this token if GitHub Actions reaches the Admin API through a reverse proxy that accepts bearer token authentication
• AWS_INVOKE_ROLE_TO_ASSUME: The Restate invoker role that your self-hosted Restate deployment assumes to invoke the Lambda function
• AWS_DEPLOY_ROLE_TO_ASSUME: The CI/CD deploy role that GitHub Actions assumes to update and publish the function, as described below

For either workflow, configure your AWS account for the GitHub OIDC provider.

GitHub OIDC setup

To configure your account for the GitHub OIDC provider, run:

aws iam create-open-id-connect-provider \
--url https://token.actions.githubusercontent.com \
--client-id-list sts.amazonaws.com

Deploy role set up

To create the CI/CD deploy role, head over to the AWS IAM console and create a new role. GitHub Actions assumes this role through OIDC; Restate never assumes it.

The role should have the following Trust policy:

{
    "Version": "2012-10-17",
    "Statement": [
{
    "Effect": "Allow",
    "Principal": {
    "Federated": "arn:aws:iam::<ACCOUNT_ID>:oidc-provider/token.actions.githubusercontent.com"
},
    "Action": "sts:AssumeRoleWithWebIdentity",
    "Condition": {
    "StringEquals": {
    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
},
    "StringLike": {
    "token.actions.githubusercontent.com:sub": "repo:<GITHUB_ORG>/<GITHUB_REPO>:*"
}
}
}
    ]
}

And the following permissions:

{
    "Version": "2012-10-17",
    "Statement": [
{
    "Sid": "LambdaDeployPermissions",
    "Effect": "Allow",
    "Action": [
    "lambda:GetFunctionConfiguration",
    "lambda:CreateFunction",
    "lambda:UpdateFunctionCode",
    "lambda:UpdateFunctionConfiguration",
    "lambda:PublishVersion"
    ],
    "Resource": "arn:aws:lambda:<REGION>:<ACCOUNT_ID>:function:<FUNCTION_NAME>"
},
{
    "Sid":"PassRolesDefinition",
    "Effect":"Allow",
    "Action":[
    "iam:PassRole"
    ],
    "Resource":[
    "arn:aws:iam::<ACCOUNT_ID>:role/<LAMBDA_EXECUTION_ROLE_NAME>"
    ]
}
    ]
}

The policy above follows the deployment action’s documented permission set. The iam:PassRole permission must be scoped to the Lambda execution role assigned to the function. The action needs it only when it creates a function or assigns a different execution role; the update-only workflow shown here does not normally exercise it. Do not grant iam:PassRole on the Restate invoker role.