Add lambda worker sample (#286)

Author: Sushisource

.gitignore

@@ -4,3 +4,6 @@ __pycache__
 .vscode
 .DS_Store
 .claude
+.mypy_cache/
+**/client.key
+**/client.pem

lambda_worker/.gitignore

@@ -0,0 +1,2 @@
+package/
+temporal-sdk.toml

lambda_worker/README.md

@@ -0,0 +1,109 @@
+# Lambda Worker
+
+This sample demonstrates how to run a Temporal Worker inside an AWS Lambda function using
+the [`lambda_worker`](https://python.temporal.io/temporalio.contrib.aws.lambda_worker.html)
+contrib package. It includes optional OpenTelemetry instrumentation that exports traces
+and metrics through AWS Distro for OpenTelemetry (ADOT).
+
+The sample registers a simple greeting Workflow and Activity, but the pattern applies to
+any Workflow/Activity definitions.
+
+## Prerequisites
+
+- A [Temporal Cloud](https://temporal.io/cloud) namespace (or a self-hosted Temporal
+  cluster accessible from your Lambda)
+- AWS CLI configured with permissions to create Lambda functions, IAM roles, and
+  CloudFormation stacks
+- mTLS client certificate and key for your Temporal namespace (place as `client.pem` and
+  `client.key` in this directory)
+- Python 3.10+
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `lambda_function.py` | Lambda entry point -- configures the worker, registers Workflows/Activities, and exports the handler |
+| `workflows.py` | Sample Workflow that executes a greeting Activity |
+| `activities.py` | Sample Activity that returns a greeting string |
+| `starter.py` | Helper program to start a Workflow execution from a local machine |
+| `temporal.toml` | Temporal client connection configuration (update with your namespace) |
+| `otel-collector-config.yaml` | OpenTelemetry Collector sidecar configuration for ADOT |
+| `deploy-lambda.sh` | Packages and deploys the Lambda function |
+| `mk-iam-role.sh` | Creates the IAM role that allows Temporal Cloud to invoke the Lambda |
+| `iam-role-for-temporal-lambda-invoke-test.yaml` | CloudFormation template for the IAM role |
+| `extra-setup-steps` | Additional IAM and Lambda configuration for OpenTelemetry support |
+
+## Setup
+
+The instructions here are a slimmed down version of the more complete getting started guide which
+you can find [here](https://docs.temporal.io/production-deployment/worker-deployments/serverless-workers/aws-lambda).
+
+### 1. Create a lambda function for your Python worker
+
+Use either the AWS web UI or CLI to create a Python runtime Lambda function. Ex:
+
+```bash
+aws lambda create-function \
+  --function-name my-temporal-worker \
+  --runtime python3.13 \
+  --handler lambda_function.lambda_handler \
+  --role arn:aws:iam::<YOUR_ACCOUNT_ID>:role/my-temporal-worker-execution \
+  --timeout 600 \
+  --memory-size 256
+```
+
+### 2. Configure Temporal connection
+
+Edit `temporal.toml` with your Temporal Cloud namespace address and credentials. In production,
+we'd recommend reading your credentials from a secret store, but to keep this example simple
+the toml file defaults to reading them from keys bundled along with the Lambda code.
+
+### 3. Create the IAM role
+
+This creates the IAM role that Temporal Cloud assumes to invoke your Lambda function:
+
+```bash
+./mk-iam-role.sh <stack-name> <external-id> <lambda-arn>
+```
+
+The External ID is provided by Temporal Cloud in your namespace's serverless worker
+configuration.
+
+### 4. (Optional) Enable OpenTelemetry
+
+If you want traces, metrics, and logs, you'll have to attach the ADOT layet to your Lambda function.
+You will need to add the appropriate layer for your runtime and region. See [this page
+](https://aws-otel.github.io/docs/getting-started/lambda#getting-started-with-aws-lambda-layers)
+for more info.
+
+Then run the extra setup to grant the Lambda role the necessary permissions:
+
+```bash
+./extra-setup-steps <role-name> <function-name> <region> <account-id>
+```
+
+Update `otel-collector-config.yaml` with your function name and region as needed.
+
+### 5. Deploy the Lambda function
+
+```bash
+./deploy-lambda.sh <function-name>
+```
+
+This installs Python dependencies, bundles them with your code and configuration files,
+and uploads to AWS Lambda.
+
+### 6. Configure Temporal to be able to invoke your lambda function
+
+Refer to the docs [here](https://docs.temporal.io/production-deployment/worker-deployments/serverless-workers/aws-lambda#create-worker-deployment-version).
+
+### 7. Start a Workflow
+
+Use the starter program to execute a Workflow on the Lambda worker, using
+the same config file the Lambda uses for connecting to the server:
+
+From inside this directory:
+
+```bash
+TEMPORAL_CONFIG_FILE=temporal.toml uv run python starter.py
+```

lambda_worker/activities.py

@@ -0,0 +1,7 @@
+from temporalio import activity
+
+
+@activity.defn
+async def hello_activity(name: str) -> str:
+    activity.logger.info("HelloActivity started with name: %s", name)
+    return f"Hello, {name}!"

lambda_worker/deploy-lambda.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+set -euo pipefail
+
+FUNCTION_NAME="${1:?Usage: deploy-lambda.sh <function-name>}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Install the published temporalio package (Linux wheels) with the OTel extras
+# needed by the lambda_worker contrib module
+uv pip install --target "$SCRIPT_DIR/package" --python-platform x86_64-unknown-linux-gnu \
+    --only-binary=:all: "temporalio[lambda-worker-otel]"
+
+# Copy application code into the package directory (all at zip root)
+cp "$SCRIPT_DIR/lambda_function.py" "$SCRIPT_DIR/workflows.py" \
+   "$SCRIPT_DIR/activities.py" "$SCRIPT_DIR/package/"
+
+# Bundle with configuration files
+cd "$SCRIPT_DIR/package"
+zip -r "$SCRIPT_DIR/function.zip" .
+cd "$SCRIPT_DIR"
+zip function.zip client.pem client.key temporal.toml otel-collector-config.yaml
+
+aws lambda update-function-code --function-name "$FUNCTION_NAME" --zip-file fileb://function.zip
+
+rm -rf "$SCRIPT_DIR/package" "$SCRIPT_DIR/function.zip"

lambda_worker/extra-setup-steps

@@ -0,0 +1,48 @@
+#!/bin/bash
+set -euo pipefail
+
+# Additional setup steps for OpenTelemetry support.
+# These are needed if you want metrics, logs, and traces from your Lambda worker.
+
+ROLE_NAME="${1:?Usage: extra-setup-steps <role-name> <function-name> <region> <account-id>}"
+FUNCTION_NAME="${2:?Usage: extra-setup-steps <role-name> <function-name> <region> <account-id>}"
+REGION="${3:?Usage: extra-setup-steps <role-name> <function-name> <region> <account-id>}"
+ACCOUNT_ID="${4:?Usage: extra-setup-steps <role-name> <function-name> <region> <account-id>}"
+
+# Needed to allow metrics/logs/traces to be published
+aws iam put-role-policy \
+     --role-name "$ROLE_NAME" \
+     --policy-name ADOT-Telemetry-Permissions \
+     --policy-document "{
+       \"Version\": \"2012-10-17\",
+       \"Statement\": [
+         {
+           \"Effect\": \"Allow\",
+           \"Action\": [
+             \"logs:CreateLogGroup\",
+             \"logs:CreateLogStream\",
+             \"logs:PutLogEvents\"
+           ],
+           \"Resource\": \"arn:aws:logs:${REGION}:${ACCOUNT_ID}:log-group:/aws/lambda/${FUNCTION_NAME}:*\"
+         },
+         {
+           \"Effect\": \"Allow\",
+           \"Action\": [
+             \"xray:PutTraceSegments\",
+             \"xray:PutTelemetryRecords\"
+           ],
+           \"Resource\": \"*\"
+         },
+         {
+           \"Effect\": \"Allow\",
+           \"Action\": [
+             \"cloudwatch:PutMetricData\"
+           ],
+           \"Resource\": \"*\"
+         }
+       ]
+     }"
+
+# Needed to make traces show up with type: `"AWS::Lambda::Function"` filter
+aws lambda update-function-configuration \
+ --function-name "$FUNCTION_NAME" --tracing-config Mode=Active

lambda_worker/iam-role-for-temporal-lambda-invoke-test.yaml

@@ -0,0 +1,97 @@
+# CloudFormation template for creating an IAM role that Temporal Cloud can assume to invoke Lambda functions.
+AWSTemplateFormatVersion: "2010-09-09"
+Description: Creates an IAM role that Temporal Cloud can assume to invoke multiple Lambda functions for Serverless Workers.
+
+Parameters:
+  AssumeRoleExternalId:
+    Type: String
+    Description: The External ID provided by Temporal Cloud
+    AllowedPattern: "[a-zA-Z0-9_+=,.@-]*"
+    MinLength: 5
+    MaxLength: 45
+
+  LambdaFunctionARNs:
+    Type: CommaDelimitedList
+    Description: >-
+      Comma-separated list of Lambda function ARNs to invoke (e.g.,
+      arn:aws:lambda:us-west-2:123456789012:function:worker-1,arn:aws:lambda:us-west-2:123456789012:function:worker-2)
+
+  RoleName:
+    Type: String
+    Default: "Temporal-Cloud-Serverless-Worker"
+
+Metadata:
+  AWS::CloudFormation::Interface:
+    ParameterGroups:
+      - Label:
+          default: "Temporal Cloud Configuration"
+        Parameters:
+          - AssumeRoleExternalId
+      - Label:
+          default: "Lambda Configuration"
+        Parameters:
+          - LambdaFunctionARNs
+          - RoleName
+    ParameterLabels:
+      AssumeRoleExternalId:
+        default: "External ID (provided by Temporal Cloud)"
+      LambdaFunctionARNs:
+        default: "Lambda Function ARNs (comma-separated list)"
+      RoleName:
+        default: "IAM Role Name"
+
+Resources:
+  TemporalCloudServerlessWorker:
+    Type: AWS::IAM::Role
+    Properties:
+      RoleName: !Sub "${RoleName}-${AWS::StackName}"
+      AssumeRolePolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Effect: Allow
+            Principal:
+              AWS:
+                [
+                  arn:aws:iam::902542641901:role/wci-lambda-invoke,
+                  arn:aws:iam::160190466495:role/wci-lambda-invoke,
+                  arn:aws:iam::819232936619:role/wci-lambda-invoke,
+                  arn:aws:iam::829909441867:role/wci-lambda-invoke,
+                  arn:aws:iam::354116250941:role/wci-lambda-invoke,
+                ]
+            Action: sts:AssumeRole
+            Condition:
+              StringEquals:
+                "sts:ExternalId": [!Ref AssumeRoleExternalId]
+      Description: "The role Temporal Cloud uses to invoke Lambda functions for Serverless Workers"
+      MaxSessionDuration: 3600 # 1 hour
+
+  TemporalCloudLambdaInvokePermissions:
+    Type: AWS::IAM::Policy
+    DependsOn: TemporalCloudServerlessWorker
+    Properties:
+      PolicyName: "Temporal-Cloud-Lambda-Invoke-Permissions"
+      PolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Effect: Allow
+            Action:
+              - lambda:InvokeFunction
+              - lambda:GetFunction
+            Resource: !Ref LambdaFunctionARNs
+      Roles:
+        - !Sub "${RoleName}-${AWS::StackName}"
+
+Outputs:
+  RoleARN:
+    Description: The ARN of the IAM role created for Temporal Cloud
+    Value: !GetAtt TemporalCloudServerlessWorker.Arn
+    Export:
+      Name: !Sub "${AWS::StackName}-RoleARN"
+
+  RoleName:
+    Description: The name of the IAM role
+    Value: !Ref RoleName
+
+  LambdaFunctionARNs:
+    Description: The Lambda function ARNs that can be invoked
+    Value: !Join [", ", !Ref LambdaFunctionARNs]

lambda_worker/lambda_function.py

@@ -0,0 +1,18 @@
+from activities import hello_activity
+from temporalio.common import WorkerDeploymentVersion
+from temporalio.contrib.aws.lambda_worker import LambdaWorkerConfig, run_worker
+from temporalio.contrib.aws.lambda_worker.otel import apply_defaults
+from workflows import TASK_QUEUE, SampleWorkflow
+
+
+def configure(config: LambdaWorkerConfig) -> None:
+    config.worker_config["task_queue"] = TASK_QUEUE
+    config.worker_config["workflows"] = [SampleWorkflow]
+    config.worker_config["activities"] = [hello_activity]
+    apply_defaults(config)
+
+
+lambda_handler = run_worker(
+    WorkerDeploymentVersion(deployment_name="my-app", build_id="build-1"),
+    configure,
+)

lambda_worker/mk-iam-role.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+set -euo pipefail
+
+# Creates the IAM role that allows Temporal Cloud to invoke your Lambda function.
+# You can find the External ID in your Temporal Cloud namespace settings.
+
+STACK_NAME="${1:?Usage: mk-iam-role.sh <stack-name> <external-id> <lambda-arn>}"
+EXTERNAL_ID="${2:?Usage: mk-iam-role.sh <stack-name> <external-id> <lambda-arn>}"
+LAMBDA_ARN="${3:?Usage: mk-iam-role.sh <stack-name> <external-id> <lambda-arn>}"
+
+aws cloudformation create-stack \
+  --stack-name "$STACK_NAME" \
+  --template-body file://iam-role-for-temporal-lambda-invoke-test.yaml \
+  --parameters \
+    ParameterKey=AssumeRoleExternalId,ParameterValue="$EXTERNAL_ID" \
+    ParameterKey=LambdaFunctionARNs,ParameterValue="$LAMBDA_ARN" \
+  --capabilities CAPABILITY_NAMED_IAM

lambda_worker/otel-collector-config.yaml

@@ -0,0 +1,35 @@
+receivers:
+    otlp:
+        protocols:
+            grpc:
+                endpoint: "localhost:4317"
+            http:
+                endpoint: "localhost:4318"
+
+exporters:
+    debug:
+    awsxray:
+        region: us-west-2
+    awsemf:
+        # AWS EMF exporter for metrics
+        # These are example configurations
+        namespace: TemporalWorkerMetrics
+        log_group_name: /aws/lambda/<your-function-name>
+        region: us-west-2
+        dimension_rollup_option: NoDimensionRollup
+        resource_to_telemetry_conversion:
+            enabled: true
+
+service:
+    pipelines:
+        traces:
+            receivers: [otlp]
+            exporters: [awsxray, debug]
+        metrics:
+            receivers: [otlp]
+            exporters: [awsemf]
+    telemetry:
+        logs:
+            level: debug
+        metrics:
+            address: localhost:8888