From fb2a11cad936c1c7ed74db775b05fb91c6b00641 Mon Sep 17 00:00:00 2001 From: Brandon Chavis Date: Thu, 18 Jun 2026 09:12:41 -0400 Subject: [PATCH] docs: Worker Versioning with Serverless Workers on AWS Lambda Each Worker Deployment Version maps 1:1 to one Lambda function version via a qualified versioned ARN. The choice applies to both Pinned and Auto-Upgrade Workflows; Versioning Behavior controls only how Workflows move between Worker Deployment Versions in Temporal, not how a Worker Deployment Version targets Lambda. - encyclopedia: new section with a Mermaid diagram of the Build ID to Lambda function version mapping. Qualified versioned ARNs are framed as the production recommendation; unqualified ARNs are noted as acceptable for development and testing, with the trade-off (loss of Pinned's no-patching guarantee) called out explicitly. - aws-lambda guide: single procedure using `aws lambda publish-version`, qualified ARN as `--aws-lambda-function-arn`, and rollback via `temporal worker deployment set-current-version`. - worker-versioning: pointer from "Choosing a Versioning Behavior" to the new encyclopedia section. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../workers/serverless-workers.mdx | 66 ++++++++++++++++++- .../serverless-workers/aws-lambda.mdx | 47 +++++++++++-- .../worker-deployments/worker-versioning.mdx | 5 ++ 3 files changed, 110 insertions(+), 8 deletions(-) diff --git a/docs/encyclopedia/workers/serverless-workers.mdx b/docs/encyclopedia/workers/serverless-workers.mdx index 78b9e05e3f..9d89c3cdd8 100644 --- a/docs/encyclopedia/workers/serverless-workers.mdx +++ b/docs/encyclopedia/workers/serverless-workers.mdx @@ -241,7 +241,69 @@ With single-slot configuration, each Activity gets a dedicated execution environ | Activity duration | Must complete within the compute provider's invocation limit (minus shutdown deadline buffer). For AWS Lambda, the maximum is 15 minutes. | | Workflow duration | No limit. Workflows of any duration work, regardless of the invocation timeout. A Workflow runs across as many invocations as needed. | | Worker code | Same Temporal SDK Worker code, using the serverless Worker package for your SDK. | -| Versioning | [Worker Versioning](/worker-versioning) is required. Each Workflow must have an `AutoUpgrade` or `Pinned` behavior, set per-Workflow or as a Worker-level default. | +| Versioning | [Worker Versioning](/worker-versioning) is required. Each Workflow must have an `AutoUpgrade` or `Pinned` behavior, set per-Workflow or as a Worker-level default. See [Worker Versioning with Serverless Workers](#worker-versioning-with-serverless-workers). | + +## Worker Versioning with Serverless Workers {/* #worker-versioning-with-serverless-workers */} + +Serverless Workers require [Worker Versioning](/worker-versioning), and the compute provider must invoke a stable, +immutable build for each Worker Deployment Version. With AWS Lambda, this means aligning two versioning systems: + +- **Temporal Worker Deployment Versions** — identified by deployment name and Build ID. Each Workflow runs against a + specific Worker Deployment Version (Pinned) or moves between them on routing changes (Auto-Upgrade). +- **AWS Lambda function versions** — immutable numbered snapshots of your Lambda function code (`1`, `2`, `3`, ...). + +A Worker Deployment Version is an immutable build identifier. For production workloads, keep the Lambda function code +it invokes immutable as well: map each Worker Deployment Version to exactly one Lambda function version, and configure +the compute provider with the qualified +[versioned ARN](https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html) for that Lambda version (for +example, `arn:aws:lambda:us-east-1:123:function:my-worker:5`). + +```mermaid +flowchart LR + subgraph Temporal["Temporal · Worker Deployment 'my-app'"] + direction TB + b1["Build ID: v1"] + b2["Build ID: v2"] + b3["Build ID: v3
(Current)"] + end + subgraph AWS["AWS Lambda · my-temporal-worker"] + direction TB + l1["Lambda version 1
function:my-temporal-worker:1"] + l2["Lambda version 2
function:my-temporal-worker:2"] + l3["Lambda version 3
function:my-temporal-worker:3"] + end + b1 -- qualified ARN --> l1 + b2 -- qualified ARN --> l2 + b3 -- qualified ARN --> l3 +``` + +:::tip Use a qualified versioned ARN in production + +An unqualified ARN (no version suffix, such as `arn:aws:lambda:us-east-1:123:function:my-worker`) points at `$LATEST`, +which changes whenever you redeploy the Lambda. Workflows created against an older Build ID are then invoked against +newer code, so every code change must remain replay-compatible under standard [patching](/patching) rules — even for +Workflows you annotated as Pinned. In effect, an unqualified ARN gives up the "Pinned doesn't need patching" guarantee +and pushes the replay-safety burden onto your team for every Lambda redeploy. + +For development, testing, or non-critical workloads where this discipline is acceptable, an unqualified ARN is fine and +lets you iterate without publishing a new Lambda function version each time. For production, use a qualified versioned +ARN so that Pinned Workflows remain truly pinned to the code they started against. + +::: + +### How the Versioning Behavior changes rollout {/* #rollout-by-behavior */} + +The choice of Pinned or Auto-Upgrade controls how *Workflows* move between Worker Deployment Versions in Temporal. It +does not change how a Worker Deployment Version targets Lambda — both behaviors use a versioned ARN that points at one +immutable Lambda function version. + +| Versioning Behavior | What changes when you roll out new code | +| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Pinned** | Publish a new Lambda function version, then create a new Worker Deployment Version that points at it. Existing Workflows continue invoking their original Lambda function version until they complete. | +| **Auto-Upgrade** | Publish a new Lambda function version, create a new Worker Deployment Version that points at it, then move the Current Version. Existing Workflows move to the new Worker Deployment Version (and its new Lambda version) at Workflow Task boundaries. | + +For step-by-step instructions on publishing Lambda versions and configuring the compute provider with a versioned ARN, +see [Publish a Lambda function version](/production-deployment/worker-deployments/serverless-workers/aws-lambda#publish-lambda-version). ## Compute providers {/* #compute-providers */} @@ -253,7 +315,7 @@ For example, an AWS Lambda compute provider includes the Lambda function ARN and invoke the function. Compute providers are only needed for Serverless Workers. Traditional long-lived Workers do not require a compute -provider because the Worker process manages its own lifecycle. +provider because the Worker process lifecycle is not managed by the Temporal server. ### Supported providers diff --git a/docs/production-deployment/worker-deployments/serverless-workers/aws-lambda.mdx b/docs/production-deployment/worker-deployments/serverless-workers/aws-lambda.mdx index 92fd8a2a2a..194fa4a245 100644 --- a/docs/production-deployment/worker-deployments/serverless-workers/aws-lambda.mdx +++ b/docs/production-deployment/worker-deployments/serverless-workers/aws-lambda.mdx @@ -339,15 +339,50 @@ aws lambda update-function-code \ --zip-file fileb://function.zip ``` -:::caution Lambda versioning best practices +### iii. Publish a Lambda function version {/* #publish-lambda-version */} -Create a 1-to-1 mapping between each build ID in your Worker code and a -[Lambda function version](https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html). If you use an -unversioned Lambda, do not change the Build Id in your Worker code without also creating a new Worker Deployment -Version. +Serverless Workers require [Worker Versioning](/worker-versioning), and each Worker Deployment Version must invoke a +stable, immutable Lambda build. Publish a new +[Lambda function version](https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html) after each +`update-function-code`, then use the resulting qualified versioned ARN when you create the Worker Deployment Version in +[Step 4](#create-worker-deployment-version). + +```bash +aws lambda publish-version \ + --function-name my-temporal-worker \ + --description "Build ID build-5" +``` + +The command prints the `FunctionArn` for the new version, for example +`arn:aws:lambda:us-east-1:123456789012:function:my-temporal-worker:5`. Use that ARN as `--aws-lambda-function-arn`. + +For each new build, publish a new Lambda function version and create a new Temporal Worker Deployment Version with a +one-to-one mapping between Lambda function version and Build ID. This applies to both +[Pinned and Auto-Upgrade](/serverless-workers#rollout-by-behavior) Workflows: the choice of behavior controls how +Workflows move between Worker Deployment Versions in Temporal, not how a Worker Deployment Version targets Lambda. + +Roll back by reverting the Temporal Current Version with +[`temporal worker deployment set-current-version`](/cli/worker#set-current-version). The previous Worker Deployment +Version still points at its original Lambda function version and is ready to receive routing again. + +:::tip Use a qualified versioned ARN in production + +For production, use the qualified versioned ARN that `publish-version` prints. An unqualified ARN (no version suffix, +such as `arn:aws:lambda:...:function:my-temporal-worker`) routes every invocation to `$LATEST`, which changes whenever +you redeploy. Pinned Workflows invoked under an unqualified ARN run against whatever code is in `$LATEST` at the time +of the call, so every Lambda redeploy must remain replay-compatible under standard [patching](/patching) rules — even +for Workflows annotated as Pinned. Using a qualified versioned ARN preserves the "Pinned doesn't need patching" +guarantee. + +For development, testing, or non-critical workloads where that discipline is acceptable, you can skip +`publish-version` and use the unqualified ARN to iterate faster. ::: +When you configure the IAM role in [Step 3](#configure-iam), include the ARNs you intend to invoke in the +`LambdaFunctionARNs` parameter. To allow invocation of any version of a function, use a wildcard suffix such as +`arn:aws:lambda:...:function:my-temporal-worker:*`. + ## 3. Configure IAM for Temporal invocation (Cloud only) {/* #configure-iam */} This section applies to Temporal Cloud. For self-hosted Temporal Service deployments, see @@ -552,7 +587,7 @@ temporal worker deployment create-version \ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--deployment-name` | Worker Deployment name. Must match `DeploymentName` in your Worker code. | | `--build-id` | Worker Deployment Version build ID. Must match `BuildID` in your Worker code. | -| `--aws-lambda-function-arn` | ARN of the Lambda function Temporal invokes for this version. | +| `--aws-lambda-function-arn` | Qualified versioned ARN of the Lambda function Temporal invokes for this version (for example, `function:my-worker:5`). See [Step iii](#publish-lambda-version). | | `--aws-lambda-assume-role-arn` | IAM role Temporal assumes to invoke the function. This is the `RoleARN` output from the CloudFormation stack in [Step 3](#configure-iam). This is not the Lambda execution role from [Step 2](#deploy-lambda-function) or your own IAM user/role. | | `--aws-lambda-assume-role-external-id` | External ID configured in the IAM role trust policy. | diff --git a/docs/production-deployment/worker-deployments/worker-versioning.mdx b/docs/production-deployment/worker-deployments/worker-versioning.mdx index 8275210077..72e9f4e893 100644 --- a/docs/production-deployment/worker-deployments/worker-versioning.mdx +++ b/docs/production-deployment/worker-deployments/worker-versioning.mdx @@ -314,6 +314,11 @@ You also want to make sure you understand how your Activities are going to work Versions. Refer to the [Worker Versioning Activity behavior docs](/worker-versioning#activity-behavior-across-versions) for more details. +If you run [Serverless Workers](/serverless-workers), each Worker Deployment Version's compute provider points at a +specific Lambda function. In production, configure it with a qualified versioned ARN so Pinned Workflows remain truly +pinned to the code they started against, regardless of whether your default behavior is Pinned or Auto-Upgrade. See +[Worker Versioning with Serverless Workers](/serverless-workers#worker-versioning-with-serverless-workers). + ## Rolling out changes with the CLI Next, deploy your Worker with the additional configuration parameters. Before making any Workflow revisions, you can use