Deploy a Serverless Worker on AWS Lambda

This guide walks through deploying a Temporal Worker on AWS Lambda.

Prerequisites

A Temporal Cloud account or a self-hosted Temporal Service vx.xx.x or later.
- Your Temporal Service frontend must be reachable from the Lambda execution environment. For Temporal Cloud, no additional configuration is needed. For self-hosted deployments on a private network, configure the Lambda function with VPC access to reach the Temporal frontend.
An AWS account with permissions to create and invoke Lambda functions and create IAM roles.
The AWS-specific steps in this guide require the aws CLI installed and configured with your AWS credentials. You may use other tools to perform the steps, such as the AWS Console or the AWS SDKs.

The Go SDK (go.temporal.io/sdk)

1. Write the Worker code

Write a Worker that runs inside a Lambda function. The Worker handles the per-invocation lifecycle: connecting to Temporal, polling for tasks, and gracefully shutting down before the Lambda deadline.

Use the Go SDK's lambdaworker package.

package main

import (
	lambdaworker "go.temporal.io/sdk/contrib/aws/lambdaworker"
	"go.temporal.io/sdk/worker"
	"go.temporal.io/sdk/workflow"
)

func main() {
	lambdaworker.RunWorker(worker.WorkerDeploymentVersion{
		DeploymentName: "my-app",
		BuildID:        "build-1",
	}, func(opts *lambdaworker.Options) error {
		opts.TaskQueue = "my-task-queue"

		opts.RegisterWorkflowWithOptions(MyWorkflow, workflow.RegisterOptions{
			VersioningBehavior: workflow.VersioningBehaviorAutoUpgrade,
		})
		opts.RegisterActivity(MyActivity)

		return nil
	})
}

Each Workflow must declare a versioning behavior at registration time, either AutoUpgrade or Pinned.

For details on configuration options, Lambda-tuned defaults, and the invocation lifecycle, see Serverless Workers - Go SDK.

2. Deploy the Lambda function

Your Lambda function needs an execution role that grants it permission to run. If you don't already have one, create a role with lambda.amazonaws.com as the trusted principal before proceeding. This role is separate from the IAM role that Temporal uses to invoke the function.

i. Build and package

Cross-compile for Lambda's Linux runtime:

GOOS=linux GOARCH=amd64 go build -tags lambda.norpc -o bootstrap ./worker

Package the binary into a zip file:

zip function.zip bootstrap

ii. Deploy the Lambda function

Configure the Temporal connection using Lambda environment variables. The lambdaworker package reads these automatically at startup.

Variable	Description	Required
`TEMPORAL_ADDRESS`	Temporal frontend address (e.g., `<namespace>.<account>.tmprl.cloud:7233`).	Yes
`TEMPORAL_NAMESPACE`	Temporal Namespace.	Yes
`TEMPORAL_TASK_QUEUE`	Task Queue name. Overrides the value set in code.	No
`TEMPORAL_TLS_CERT`	TLS client certificate content for mTLS authentication.	For mTLS
`TEMPORAL_TLS_KEY`	TLS client key content for mTLS authentication.	For mTLS
`TEMPORAL_API_KEY`	API key for API key authentication.	For API key auth

For the full list of supported environment variables, see Client environment configuration.

Sensitive values like TLS keys and API keys should be encrypted at rest. See AWS documentation for options.

aws lambda create-function \
  --function-name my-temporal-worker \
  --runtime provided.al2023 \
  --handler bootstrap \
  --architectures x86_64 \
  --role arn:aws:iam::<YOUR_ACCOUNT_ID>:role/my-temporal-worker-execution \
  --zip-file fileb://function.zip \
  --timeout 60 \
  --memory-size 256 \
  --environment "Variables={TEMPORAL_ADDRESS=<your-temporal-address>:7233,TEMPORAL_NAMESPACE=<your-namespace>}"

To update an existing function with new code:

aws lambda update-function-code \
  --function-name my-temporal-worker \
  --zip-file fileb://function.zip

3. Configure IAM for Temporal invocation

Temporal needs permission to invoke your Lambda function. The Temporal server assumes an IAM role in your AWS account to call lambda:InvokeFunction. The trust policy on the role includes an External ID condition to prevent confused deputy attacks.

Deploy the following CloudFormation template to create the invocation role and its permissions.

Parameter	Description
`TemporalPrincipalArn`	The IAM principal that the Temporal server runs as. For Temporal Cloud, this is provided in your Namespace configuration. For self-hosted, this is the IAM identity of the server process (IAM user, EC2 instance role, EKS service account, etc.).
`ExternalId`	A unique identifier that Temporal presents when assuming the role. For Temporal Cloud, this is provided in your Namespace configuration. For self-hosted, this is the value you configure in the compute provider settings.
`LambdaFunctionArn`	The ARN of the Lambda function that Temporal will invoke.

# CloudFormation template coming soon

4. Create a Worker Deployment Version

Create a Worker Deployment Version with a compute provider that points to your Lambda function. The compute configuration tells Temporal how to invoke your Worker: the provider type (aws-lambda), the Lambda function ARN, and the IAM role to assume. The deployment name and build ID must match the values in your Worker code.

You can create the version using the Temporal UI, the Temporal CLI, or programmatically with an SDK.

Temporal UI

Use the UI for one-off setup and exploration.

When you create a version through the UI, the version is automatically set as current.

Temporal CLI

Use the CLI for manual setup, shell scripts, and CI/CD pipelines. When you create a version through the CLI, you must set the version as current as a separate step.

temporal worker deployment create-version \
  --namespace <YOUR_NAMESPACE> \
  --deployment-name my-app \
  --build-id build-1 \
  --aws-lambda-invoke arn:aws:lambda:<REGION>:<ACCOUNT_ID>:function:my-temporal-worker \
  --scaler-min-instances 0 \
  --scaler-max-instances 5

SDK

Use the SDK when the deployment registration is part of your application, for example a setup program that provisions infrastructure and registers the version together, or when you need to compute values dynamically. When you create a version through the SDK, you must set the version as current as a separate step.

// Create the worker deployment
client.CreateWorkerDeployment(ctx, &workflowservice.CreateWorkerDeploymentRequest{
    Namespace:      "default",
    DeploymentName: "my-app",
})

// Create a version with Lambda compute config
client.CreateWorkerDeploymentVersion(ctx, &workflowservice.CreateWorkerDeploymentVersionRequest{
    Namespace: "default",
    DeploymentVersion: &deploymentpb.WorkerDeploymentVersion{
        DeploymentName: "my-app",
        BuildId:        "build-1",
    },
    ComputeConfig: &computepb.ComputeConfig{
        ScalingGroups: map[string]*computepb.ComputeConfigScalingGroup{
            "default": {
                Provider: &computepb.ComputeProvider{
                    Type: "aws-lambda",
                    Details: /* Lambda ARN, role ARN, external ID */,
                },
            },
        },
    },
})

5. Set the version as current

If you created the version through the Temporal UI, the version is already current and you can skip this step.

If you used the CLI or SDK, set the version as current. Without this step, tasks on the Task Queue will not route to the version, and Temporal will not invoke the Lambda function.

temporal worker deployment set-current-version \
  --deployment-name my-app \
  --build-id build-1 \
  --ignore-missing-task-queues

The --ignore-missing-task-queues flag is needed because no Worker has polled the Task Queue yet. With Serverless Workers, the Worker only connects when Temporal invokes the Lambda function.

6. Verify the deployment

Start a Workflow on the same Task Queue to confirm that Temporal invokes your Lambda Worker.

temporal workflow start \
  --task-queue my-task-queue \
  --type MyWorkflow \
  --input '"Hello, serverless!"'

When the task lands on the Task Queue with no active pollers, Temporal detects the compute provider configuration and invokes your Lambda function. The Worker starts, connects to Temporal, picks up the task, and processes it.

You can verify the invocation by checking:

Temporal UI: The Workflow execution should show task completions in the event history.
AWS CloudWatch Logs: The Lambda function's log group (/aws/lambda/my-temporal-worker) should show invocation logs with the Worker startup, task processing, and graceful shutdown.

Prerequisites​

1. Write the Worker code​

2. Deploy the Lambda function​

i. Build and package​

ii. Deploy the Lambda function​

3. Configure IAM for Temporal invocation​

4. Create a Worker Deployment Version​

Temporal UI​

Temporal CLI​

SDK​

5. Set the version as current​

6. Verify the deployment​