From a094a82adf3eb1c0ea90d4ca9999d9795abf3c08 Mon Sep 17 00:00:00 2001 From: Lenny Chen Date: Wed, 22 Apr 2026 16:12:38 -0700 Subject: [PATCH 01/11] docs: add self-hosted setup page for serverless workers Covers enabling the Worker Controller via dynamic config, configuring AWS credentials for the Temporal server, and creating the Lambda invocation role with a CloudFormation template adapted for self-hosted. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../serverless-workers/self-hosted-setup.mdx | 188 ++++++++++++++++++ sidebars.js | 1 + ...al-self-hosted-serverless-worker-role.yaml | 74 +++++++ 3 files changed, 263 insertions(+) create mode 100644 docs/production-deployment/worker-deployments/serverless-workers/self-hosted-setup.mdx create mode 100644 static/files/temporal-self-hosted-serverless-worker-role.yaml diff --git a/docs/production-deployment/worker-deployments/serverless-workers/self-hosted-setup.mdx b/docs/production-deployment/worker-deployments/serverless-workers/self-hosted-setup.mdx new file mode 100644 index 0000000000..caec3ac67a --- /dev/null +++ b/docs/production-deployment/worker-deployments/serverless-workers/self-hosted-setup.mdx @@ -0,0 +1,188 @@ +--- +id: self-hosted-setup +title: Self-hosted setup for Serverless Workers +sidebar_label: Self-hosted setup +description: Configure a self-hosted Temporal Service to use Serverless Workers with AWS Lambda. +slug: /production-deployment/worker-deployments/serverless-workers/self-hosted-setup +toc_max_heading_level: 4 +keywords: + - serverless + - self-hosted + - lambda + - aws + - worker + - deployment +tags: + - Workers + - Deploy + - Serverless + - Self-hosted +--- + +Temporal Cloud handles Serverless Worker infrastructure automatically. +Self-hosted Temporal Service operators must enable the feature and configure the server to invoke compute providers. + +This page covers the prerequisites for running [Serverless Workers](/serverless-workers) on a self-hosted Temporal Service with AWS Lambda. +Once setup is complete, follow the [AWS Lambda deployment guide](/production-deployment/worker-deployments/serverless-workers/aws-lambda) to deploy your Worker. + +## Enable the Worker Controller {#enable-worker-controller} + +The Worker Controller is the server component that monitors Task Queues and invokes compute providers. +It is disabled by default and must be enabled through [dynamic configuration](/references/dynamic-configuration). + +Add the following keys to your dynamic config file: + +```yaml +workercontroller.enabled: + - value: true + +workercontroller.compute_providers.enabled: + - value: + - aws-lambda + +workercontroller.scaling_algorithms.enabled: + - value: + - no-sync +``` + +To enable the Worker Controller for specific Namespaces instead of globally: + +```yaml +workercontroller.enabled: + - value: true + constraints: + namespace: "your-namespace" +``` + +The Temporal Service watches the dynamic config file for changes and applies updates without a restart. + +### Worker Controller dynamic config reference {#dynamic-config-reference} + +| Key | Scope | Default | Description | +|---|---|---|---| +| `workercontroller.enabled` | Namespace | `false` | Enables the Worker Controller for a Namespace. | +| `workercontroller.compute_providers.enabled` | Global | none | List of enabled compute providers (e.g., `["aws-lambda"]`). | +| `workercontroller.scaling_algorithms.enabled` | Global | none | List of enabled scaling algorithms (e.g., `["no-sync"]`). | +| `workercontroller.maxInstances` | Namespace | `100` | Maximum number of Worker Controller instances per Namespace. | +| `workercontroller.compute_providers.aws.require_role_and_external_id` | Global | `true` | Whether AWS Lambda compute providers require a role ARN and external ID. | + +## Configure AWS credentials {#configure-aws-credentials} + +The Temporal Service needs AWS credentials to assume an IAM role that invokes Lambda functions. +How you provide credentials depends on where the Temporal Service runs. + +**On AWS infrastructure (EC2, ECS, EKS):** The server uses the attached instance role, task role, or pod role automatically. No additional credential configuration is needed. The attached role must have `sts:AssumeRole` permission for the Lambda invocation role created in the next step. + +**Outside AWS:** Configure AWS credentials in the server's environment: + +``` +AWS_ACCESS_KEY_ID= +AWS_SECRET_ACCESS_KEY= +AWS_REGION= +``` + +These credentials must belong to an IAM user or role that has `sts:AssumeRole` permission for the Lambda invocation role. + +## Create the Lambda invocation role {#create-invocation-role} + +Temporal invokes Lambda functions by assuming an IAM role in your AWS account. +This role needs `lambda:InvokeFunction` permission on your Worker Lambda functions, and a trust policy that allows the Temporal server's identity to assume it. + +Deploy the following CloudFormation template to create the role. [Download the template](/files/temporal-self-hosted-serverless-worker-role.yaml). + +| Parameter | Description | +|---|---| +| `TemporalIamRoleArn` | The ARN of the IAM role or user that the Temporal Service runs as. This is the identity the server uses to call `sts:AssumeRole`. | +| `AssumeRoleExternalId` | A unique string to prevent [confused deputy](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html) attacks. Choose any value and pass the same value when creating the Worker Deployment Version. | +| `LambdaFunctionARNs` | Comma-separated list of Lambda function ARNs that Temporal may invoke. | +| `RoleName` | Base name for the created IAM role. Defaults to `Temporal-Serverless-Worker`. | + +
+CloudFormation template + +```yaml +AWSTemplateFormatVersion: '2010-09-09' +Description: Creates an IAM role that a self-hosted Temporal Service can assume to invoke Lambda functions for Serverless Workers. + +Parameters: + TemporalIamRoleArn: + Type: String + Description: The ARN of the IAM role or user that the Temporal Service runs as. + + AssumeRoleExternalId: + Type: String + Description: A unique identifier to prevent confused deputy attacks. + 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-Serverless-Worker' + +Resources: + TemporalServerlessWorker: + Type: AWS::IAM::Role + Properties: + RoleName: !Sub '${RoleName}-${AWS::StackName}' + AssumeRolePolicyDocument: + Version: '2012-10-17' + Statement: + - Effect: Allow + Principal: + AWS: + [!Ref TemporalIamRoleArn] + Action: sts:AssumeRole + Condition: + StringEquals: + 'sts:ExternalId': [!Ref AssumeRoleExternalId] + Description: "The role the Temporal Service uses to invoke Lambda functions for Serverless Workers" + MaxSessionDuration: 3600 + + TemporalLambdaInvokePermissions: + Type: AWS::IAM::Policy + DependsOn: TemporalServerlessWorker + Properties: + PolicyName: 'Temporal-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 the Temporal Service + Value: !GetAtt TemporalServerlessWorker.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] +``` + +
+ +Deploy the template: + +```bash +aws cloudformation create-stack --stack-name temporal-serverless-worker --template-body file://temporal-self-hosted-serverless-worker-role.yaml --parameters ParameterKey=TemporalIamRoleArn,ParameterValue= ParameterKey=AssumeRoleExternalId,ParameterValue= ParameterKey=LambdaFunctionARNs,ParameterValue='""' --capabilities CAPABILITY_NAMED_IAM --region +``` + +The stack output `RoleARN` contains the IAM role ARN to use when creating the Worker Deployment Version. diff --git a/sidebars.js b/sidebars.js index 995dd27f9a..39fdc7a644 100644 --- a/sidebars.js +++ b/sidebars.js @@ -1219,6 +1219,7 @@ module.exports = { }, items: [ 'production-deployment/worker-deployments/serverless-workers/aws-lambda', + 'production-deployment/worker-deployments/serverless-workers/self-hosted-setup', ], }, ], diff --git a/static/files/temporal-self-hosted-serverless-worker-role.yaml b/static/files/temporal-self-hosted-serverless-worker-role.yaml new file mode 100644 index 0000000000..488fa1ad96 --- /dev/null +++ b/static/files/temporal-self-hosted-serverless-worker-role.yaml @@ -0,0 +1,74 @@ +AWSTemplateFormatVersion: '2010-09-09' +Description: Creates an IAM role that a self-hosted Temporal Service can assume to invoke Lambda functions for Serverless Workers. + +Parameters: + TemporalIamRoleArn: + Type: String + Description: The ARN of the IAM role or user that the Temporal Service runs as. + + AssumeRoleExternalId: + Type: String + Description: A unique identifier to prevent confused deputy attacks. + 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-Serverless-Worker' + +Resources: + TemporalServerlessWorker: + Type: AWS::IAM::Role + Properties: + RoleName: !Sub '${RoleName}-${AWS::StackName}' + AssumeRolePolicyDocument: + Version: '2012-10-17' + Statement: + - Effect: Allow + Principal: + AWS: + [!Ref TemporalIamRoleArn] + Action: sts:AssumeRole + Condition: + StringEquals: + 'sts:ExternalId': [!Ref AssumeRoleExternalId] + Description: "The role the Temporal Service uses to invoke Lambda functions for Serverless Workers" + MaxSessionDuration: 3600 + + TemporalLambdaInvokePermissions: + Type: AWS::IAM::Policy + DependsOn: TemporalServerlessWorker + Properties: + PolicyName: 'Temporal-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 the Temporal Service + Value: !GetAtt TemporalServerlessWorker.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] From 6935886432171d58bef8be80bf08e9102069413e Mon Sep 17 00:00:00 2001 From: Lenny Chen Date: Wed, 22 Apr 2026 18:05:29 -0700 Subject: [PATCH 02/11] docs: add describe-stacks command to retrieve role ARN Co-Authored-By: Claude Opus 4.6 (1M context) --- .../serverless-workers/self-hosted-setup.mdx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/production-deployment/worker-deployments/serverless-workers/self-hosted-setup.mdx b/docs/production-deployment/worker-deployments/serverless-workers/self-hosted-setup.mdx index caec3ac67a..33a4afce8d 100644 --- a/docs/production-deployment/worker-deployments/serverless-workers/self-hosted-setup.mdx +++ b/docs/production-deployment/worker-deployments/serverless-workers/self-hosted-setup.mdx @@ -185,4 +185,10 @@ Deploy the template: aws cloudformation create-stack --stack-name temporal-serverless-worker --template-body file://temporal-self-hosted-serverless-worker-role.yaml --parameters ParameterKey=TemporalIamRoleArn,ParameterValue= ParameterKey=AssumeRoleExternalId,ParameterValue= ParameterKey=LambdaFunctionARNs,ParameterValue='""' --capabilities CAPABILITY_NAMED_IAM --region ``` -The stack output `RoleARN` contains the IAM role ARN to use when creating the Worker Deployment Version. +After the stack finishes creating, retrieve the IAM role ARN from the stack outputs: + +```bash +aws cloudformation describe-stacks --stack-name temporal-serverless-worker --query 'Stacks[0].Outputs[?OutputKey==`RoleARN`].OutputValue' --output text --region +``` + +Use this role ARN when creating the Worker Deployment Version. From 349520e1b2f8db3e229e84b4b2815860e754d213 Mon Sep 17 00:00:00 2001 From: Lenny Chen Date: Wed, 22 Apr 2026 19:15:45 -0700 Subject: [PATCH 03/11] docs: add WCI verification steps and ARN discovery tip Add how to view WCI workflows using TemporalNamespaceDivision filter to both the self-hosted setup page and the deploy guide. Add aws sts get-caller-identity tip for finding the server's IAM ARN. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../serverless-workers/aws-lambda.mdx | 6 ++++++ .../serverless-workers/self-hosted-setup.mdx | 18 +++++++++++++++++- 2 files changed, 23 insertions(+), 1 deletion(-) 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 505e274207..5118a148ef 100644 --- a/docs/production-deployment/worker-deployments/serverless-workers/aws-lambda.mdx +++ b/docs/production-deployment/worker-deployments/serverless-workers/aws-lambda.mdx @@ -370,3 +370,9 @@ 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. + +To view the Worker Controller Instance (WCI) workflow that manages scaling for your deployment, filter workflows in the Temporal UI or CLI with: + +```bash +temporal workflow list --query 'TemporalNamespaceDivision = "TemporalWorkerControllerInstance"' +``` diff --git a/docs/production-deployment/worker-deployments/serverless-workers/self-hosted-setup.mdx b/docs/production-deployment/worker-deployments/serverless-workers/self-hosted-setup.mdx index 33a4afce8d..e922868ca8 100644 --- a/docs/production-deployment/worker-deployments/serverless-workers/self-hosted-setup.mdx +++ b/docs/production-deployment/worker-deployments/serverless-workers/self-hosted-setup.mdx @@ -92,7 +92,7 @@ Deploy the following CloudFormation template to create the role. [Download the t | Parameter | Description | |---|---| -| `TemporalIamRoleArn` | The ARN of the IAM role or user that the Temporal Service runs as. This is the identity the server uses to call `sts:AssumeRole`. | +| `TemporalIamRoleArn` | The ARN of the IAM role or user that the Temporal Service runs as. This is the identity the server uses to call `sts:AssumeRole`. To find the ARN, run `aws sts get-caller-identity` in the server's environment. | | `AssumeRoleExternalId` | A unique string to prevent [confused deputy](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html) attacks. Choose any value and pass the same value when creating the Worker Deployment Version. | | `LambdaFunctionARNs` | Comma-separated list of Lambda function ARNs that Temporal may invoke. | | `RoleName` | Base name for the created IAM role. Defaults to `Temporal-Serverless-Worker`. | @@ -192,3 +192,19 @@ aws cloudformation describe-stacks --stack-name temporal-serverless-worker --que ``` Use this role ARN when creating the Worker Deployment Version. + +## Verify the Worker Controller {#verify-worker-controller} + +After you complete the [AWS Lambda deployment guide](/production-deployment/worker-deployments/serverless-workers/aws-lambda) and create a Worker Deployment Version with a compute provider, the Temporal Service starts a Worker Controller Instance (WCI) workflow to manage scaling for that version. + +To confirm the WCI is running, list workflows with the `TemporalNamespaceDivision` search attribute filter: + +```bash +temporal workflow list --query 'TemporalNamespaceDivision = "TemporalWorkerControllerInstance"' +``` + +The WCI workflow is hidden from the default workflow list. +In the Temporal UI, add the same filter in the Workflows tab to view it. + +To verify end-to-end, start a Workflow on the Task Queue configured for the deployment. +The WCI should detect the task, invoke the Lambda function, and the Workflow should complete. From 6d7db592b04c751834dc0ea667d9f62aa5b203bc Mon Sep 17 00:00:00 2001 From: Lenny Chen Date: Thu, 23 Apr 2026 10:58:04 -0700 Subject: [PATCH 04/11] docs: remove WCI filter tip from deploy guide Co-Authored-By: Claude Opus 4.6 (1M context) --- .../worker-deployments/serverless-workers/aws-lambda.mdx | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) 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 5118a148ef..626a59e19e 100644 --- a/docs/production-deployment/worker-deployments/serverless-workers/aws-lambda.mdx +++ b/docs/production-deployment/worker-deployments/serverless-workers/aws-lambda.mdx @@ -369,10 +369,4 @@ 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. - -To view the Worker Controller Instance (WCI) workflow that manages scaling for your deployment, filter workflows in the Temporal UI or CLI with: - -```bash -temporal workflow list --query 'TemporalNamespaceDivision = "TemporalWorkerControllerInstance"' -``` +- **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. \ No newline at end of file From 6ac6aa3ca3d7d0efd0aa24d601d13c0bd4126e0e Mon Sep 17 00:00:00 2001 From: Lenny Chen Date: Thu, 23 Apr 2026 10:59:45 -0700 Subject: [PATCH 05/11] docs: mark IAM section as Cloud-only, link to self-hosted setup Co-Authored-By: Claude Opus 4.6 (1M context) --- .../worker-deployments/serverless-workers/aws-lambda.mdx | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) 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 626a59e19e..2630578a54 100644 --- a/docs/production-deployment/worker-deployments/serverless-workers/aws-lambda.mdx +++ b/docs/production-deployment/worker-deployments/serverless-workers/aws-lambda.mdx @@ -158,11 +158,8 @@ The trust policy on the role includes an External ID condition to prevent [confu Deploy the following CloudFormation template to create the invocation role and its permissions. [Download the template](/files/temporal-cloud-serverless-worker-role.yaml). -:::note - -This template is scoped to Temporal Cloud. Self-hosted configuration guidance is in progress. - -::: +This section applies to Temporal Cloud. +For self-hosted Temporal Service deployments, see [Self-hosted setup](/production-deployment/worker-deployments/serverless-workers/self-hosted-setup#create-invocation-role) for IAM configuration with a different CloudFormation template. | Parameter | Description | |---|---| From 11fff48e2bbb02f1ac9b49b0c47c5599748c1d49 Mon Sep 17 00:00:00 2001 From: Lenny Chen Date: Thu, 23 Apr 2026 11:00:37 -0700 Subject: [PATCH 06/11] docs: add (Cloud only) to IAM heading Co-Authored-By: Claude Opus 4.6 (1M context) --- .../worker-deployments/serverless-workers/aws-lambda.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 2630578a54..f42b6177fc 100644 --- a/docs/production-deployment/worker-deployments/serverless-workers/aws-lambda.mdx +++ b/docs/production-deployment/worker-deployments/serverless-workers/aws-lambda.mdx @@ -150,7 +150,7 @@ aws lambda update-function-code \ --zip-file fileb://function.zip ``` -## 3. Configure IAM for Temporal invocation {#configure-iam} +## 3. Configure IAM for Temporal invocation (Cloud only) {#configure-iam} Temporal needs permission to invoke your Lambda function. The Temporal server assumes an IAM role in your AWS account to call `lambda:InvokeFunction`. From 3b68f71bf75a7b55f9917aee4156cf2a2d46cd14 Mon Sep 17 00:00:00 2001 From: Lenny Chen Date: Thu, 23 Apr 2026 11:02:07 -0700 Subject: [PATCH 07/11] docs: move Cloud-only callout to top of IAM section Co-Authored-By: Claude Opus 4.6 (1M context) --- .../worker-deployments/serverless-workers/aws-lambda.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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 f42b6177fc..1dd7f22963 100644 --- a/docs/production-deployment/worker-deployments/serverless-workers/aws-lambda.mdx +++ b/docs/production-deployment/worker-deployments/serverless-workers/aws-lambda.mdx @@ -152,15 +152,15 @@ aws lambda update-function-code \ ## 3. Configure IAM for Temporal invocation (Cloud only) {#configure-iam} +This section applies to Temporal Cloud. +For self-hosted Temporal Service deployments, see [Self-hosted setup](/production-deployment/worker-deployments/serverless-workers/self-hosted-setup#create-invocation-role) for IAM configuration with a different CloudFormation template. + 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html) attacks. Deploy the following CloudFormation template to create the invocation role and its permissions. [Download the template](/files/temporal-cloud-serverless-worker-role.yaml). -This section applies to Temporal Cloud. -For self-hosted Temporal Service deployments, see [Self-hosted setup](/production-deployment/worker-deployments/serverless-workers/self-hosted-setup#create-invocation-role) for IAM configuration with a different CloudFormation template. - | Parameter | Description | |---|---| | `AssumeRoleExternalId` | A unique identifier that Temporal Cloud presents when assuming the role. Provided in your Namespace configuration. | From 657536566eb62489db273e44ab8085018bc70809 Mon Sep 17 00:00:00 2001 From: Lenny Chen Date: Thu, 23 Apr 2026 11:52:12 -0700 Subject: [PATCH 08/11] docs: address PR review feedback on self-hosted setup page - Remove first paragraph (Cloud comparison) - Add brief overview of the three setup steps - Use "Worker Controller Instance (WCI)" instead of "Worker Controller" - Move dynamic config reference table out (belongs on dynamic config page) - Replace verify section with Next steps linking to deploy guide Co-Authored-By: Claude Opus 4.6 (1M context) --- .../serverless-workers/self-hosted-setup.mdx | 37 +++++-------------- 1 file changed, 9 insertions(+), 28 deletions(-) diff --git a/docs/production-deployment/worker-deployments/serverless-workers/self-hosted-setup.mdx b/docs/production-deployment/worker-deployments/serverless-workers/self-hosted-setup.mdx index e922868ca8..6a4c6d4bb6 100644 --- a/docs/production-deployment/worker-deployments/serverless-workers/self-hosted-setup.mdx +++ b/docs/production-deployment/worker-deployments/serverless-workers/self-hosted-setup.mdx @@ -19,15 +19,18 @@ tags: - Self-hosted --- -Temporal Cloud handles Serverless Worker infrastructure automatically. -Self-hosted Temporal Service operators must enable the feature and configure the server to invoke compute providers. - This page covers the prerequisites for running [Serverless Workers](/serverless-workers) on a self-hosted Temporal Service with AWS Lambda. Once setup is complete, follow the [AWS Lambda deployment guide](/production-deployment/worker-deployments/serverless-workers/aws-lambda) to deploy your Worker. +To set up your self-hosted Temporal Service for Serverless Workers: + +1. Enable the Worker Controller Instance (WCI) on the server through dynamic configuration. +2. Provide the server with AWS credentials to assume IAM roles. +3. Create an IAM role in your AWS account that grants Temporal permission to invoke Lambda functions. + ## Enable the Worker Controller {#enable-worker-controller} -The Worker Controller is the server component that monitors Task Queues and invokes compute providers. +The Worker Controller Instance (WCI) is the server component that monitors Task Queues and invokes compute providers. It is disabled by default and must be enabled through [dynamic configuration](/references/dynamic-configuration). Add the following keys to your dynamic config file: @@ -56,16 +59,6 @@ workercontroller.enabled: The Temporal Service watches the dynamic config file for changes and applies updates without a restart. -### Worker Controller dynamic config reference {#dynamic-config-reference} - -| Key | Scope | Default | Description | -|---|---|---|---| -| `workercontroller.enabled` | Namespace | `false` | Enables the Worker Controller for a Namespace. | -| `workercontroller.compute_providers.enabled` | Global | none | List of enabled compute providers (e.g., `["aws-lambda"]`). | -| `workercontroller.scaling_algorithms.enabled` | Global | none | List of enabled scaling algorithms (e.g., `["no-sync"]`). | -| `workercontroller.maxInstances` | Namespace | `100` | Maximum number of Worker Controller instances per Namespace. | -| `workercontroller.compute_providers.aws.require_role_and_external_id` | Global | `true` | Whether AWS Lambda compute providers require a role ARN and external ID. | - ## Configure AWS credentials {#configure-aws-credentials} The Temporal Service needs AWS credentials to assume an IAM role that invokes Lambda functions. @@ -193,18 +186,6 @@ aws cloudformation describe-stacks --stack-name temporal-serverless-worker --que Use this role ARN when creating the Worker Deployment Version. -## Verify the Worker Controller {#verify-worker-controller} - -After you complete the [AWS Lambda deployment guide](/production-deployment/worker-deployments/serverless-workers/aws-lambda) and create a Worker Deployment Version with a compute provider, the Temporal Service starts a Worker Controller Instance (WCI) workflow to manage scaling for that version. - -To confirm the WCI is running, list workflows with the `TemporalNamespaceDivision` search attribute filter: - -```bash -temporal workflow list --query 'TemporalNamespaceDivision = "TemporalWorkerControllerInstance"' -``` - -The WCI workflow is hidden from the default workflow list. -In the Temporal UI, add the same filter in the Workflows tab to view it. +## Next steps {#next-steps} -To verify end-to-end, start a Workflow on the Task Queue configured for the deployment. -The WCI should detect the task, invoke the Lambda function, and the Workflow should complete. +Follow the [AWS Lambda deployment guide](/production-deployment/worker-deployments/serverless-workers/aws-lambda) to write your Worker code, deploy it to Lambda, and create a Worker Deployment Version with the IAM role from the previous step. From c70e028ced4b78f6b1b02b0539c1e9b8960a3e92 Mon Sep 17 00:00:00 2001 From: Lenny Chen Date: Thu, 23 Apr 2026 12:01:19 -0700 Subject: [PATCH 09/11] prettier --- .../serverless-workers/self-hosted-setup.mdx | 68 +++++++++++-------- 1 file changed, 38 insertions(+), 30 deletions(-) diff --git a/docs/production-deployment/worker-deployments/serverless-workers/self-hosted-setup.mdx b/docs/production-deployment/worker-deployments/serverless-workers/self-hosted-setup.mdx index 6a4c6d4bb6..dbb7875f9c 100644 --- a/docs/production-deployment/worker-deployments/serverless-workers/self-hosted-setup.mdx +++ b/docs/production-deployment/worker-deployments/serverless-workers/self-hosted-setup.mdx @@ -19,19 +19,21 @@ tags: - Self-hosted --- -This page covers the prerequisites for running [Serverless Workers](/serverless-workers) on a self-hosted Temporal Service with AWS Lambda. -Once setup is complete, follow the [AWS Lambda deployment guide](/production-deployment/worker-deployments/serverless-workers/aws-lambda) to deploy your Worker. - -To set up your self-hosted Temporal Service for Serverless Workers: +This page covers the prerequisites for running [Serverless Workers](/serverless-workers) on a self-hosted Temporal +Service with AWS Lambda: 1. Enable the Worker Controller Instance (WCI) on the server through dynamic configuration. 2. Provide the server with AWS credentials to assume IAM roles. 3. Create an IAM role in your AWS account that grants Temporal permission to invoke Lambda functions. +Once setup is complete, follow the +[AWS Lambda deployment guide](/production-deployment/worker-deployments/serverless-workers/aws-lambda) to deploy your +Worker. + ## Enable the Worker Controller {#enable-worker-controller} -The Worker Controller Instance (WCI) is the server component that monitors Task Queues and invokes compute providers. -It is disabled by default and must be enabled through [dynamic configuration](/references/dynamic-configuration). +The Worker Controller Instance (WCI) is the server component that monitors Task Queues and invokes compute providers. It +is disabled by default and must be enabled through [dynamic configuration](/references/dynamic-configuration). Add the following keys to your dynamic config file: @@ -41,11 +43,11 @@ workercontroller.enabled: workercontroller.compute_providers.enabled: - value: - - aws-lambda + - aws-lambda workercontroller.scaling_algorithms.enabled: - value: - - no-sync + - no-sync ``` To enable the Worker Controller for specific Namespaces instead of globally: @@ -54,17 +56,19 @@ To enable the Worker Controller for specific Namespaces instead of globally: workercontroller.enabled: - value: true constraints: - namespace: "your-namespace" + namespace: 'your-namespace' ``` The Temporal Service watches the dynamic config file for changes and applies updates without a restart. ## Configure AWS credentials {#configure-aws-credentials} -The Temporal Service needs AWS credentials to assume an IAM role that invokes Lambda functions. -How you provide credentials depends on where the Temporal Service runs. +The Temporal Service needs AWS credentials to assume an IAM role that invokes Lambda functions. How you provide +credentials depends on where the Temporal Service runs. -**On AWS infrastructure (EC2, ECS, EKS):** The server uses the attached instance role, task role, or pod role automatically. No additional credential configuration is needed. The attached role must have `sts:AssumeRole` permission for the Lambda invocation role created in the next step. +**On AWS infrastructure (EC2, ECS, EKS):** The server uses the attached instance role, task role, or pod role +automatically. No additional credential configuration is needed. The attached role must have `sts:AssumeRole` permission +for the Lambda invocation role created in the next step. **Outside AWS:** Configure AWS credentials in the server's environment: @@ -74,28 +78,31 @@ AWS_SECRET_ACCESS_KEY= AWS_REGION= ``` -These credentials must belong to an IAM user or role that has `sts:AssumeRole` permission for the Lambda invocation role. +These credentials must belong to an IAM user or role that has `sts:AssumeRole` permission for the Lambda invocation +role. ## Create the Lambda invocation role {#create-invocation-role} -Temporal invokes Lambda functions by assuming an IAM role in your AWS account. -This role needs `lambda:InvokeFunction` permission on your Worker Lambda functions, and a trust policy that allows the Temporal server's identity to assume it. +Temporal invokes Lambda functions by assuming an IAM role in your AWS account. This role needs `lambda:InvokeFunction` +permission on your Worker Lambda functions, and a trust policy that allows the Temporal server's identity to assume it. -Deploy the following CloudFormation template to create the role. [Download the template](/files/temporal-self-hosted-serverless-worker-role.yaml). +Deploy the following CloudFormation template to create the role. +[Download the template](/files/temporal-self-hosted-serverless-worker-role.yaml). -| Parameter | Description | -|---|---| -| `TemporalIamRoleArn` | The ARN of the IAM role or user that the Temporal Service runs as. This is the identity the server uses to call `sts:AssumeRole`. To find the ARN, run `aws sts get-caller-identity` in the server's environment. | +| Parameter | Description | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `TemporalIamRoleArn` | The ARN of the IAM role or user that the Temporal Service runs as. This is the identity the server uses to call `sts:AssumeRole`. To find the ARN, run `aws sts get-caller-identity` in the server's environment. | | `AssumeRoleExternalId` | A unique string to prevent [confused deputy](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html) attacks. Choose any value and pass the same value when creating the Worker Deployment Version. | -| `LambdaFunctionARNs` | Comma-separated list of Lambda function ARNs that Temporal may invoke. | -| `RoleName` | Base name for the created IAM role. Defaults to `Temporal-Serverless-Worker`. | +| `LambdaFunctionARNs` | Comma-separated list of Lambda function ARNs that Temporal may invoke. | +| `RoleName` | Base name for the created IAM role. Defaults to `Temporal-Serverless-Worker`. |
CloudFormation template ```yaml AWSTemplateFormatVersion: '2010-09-09' -Description: Creates an IAM role that a self-hosted Temporal Service can assume to invoke Lambda functions for Serverless Workers. +Description: + Creates an IAM role that a self-hosted Temporal Service can assume to invoke Lambda functions for Serverless Workers. Parameters: TemporalIamRoleArn: @@ -112,8 +119,8 @@ Parameters: 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) + 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 @@ -129,13 +136,12 @@ Resources: Statement: - Effect: Allow Principal: - AWS: - [!Ref TemporalIamRoleArn] + AWS: [!Ref TemporalIamRoleArn] Action: sts:AssumeRole Condition: StringEquals: 'sts:ExternalId': [!Ref AssumeRoleExternalId] - Description: "The role the Temporal Service uses to invoke Lambda functions for Serverless Workers" + Description: 'The role the Temporal Service uses to invoke Lambda functions for Serverless Workers' MaxSessionDuration: 3600 TemporalLambdaInvokePermissions: @@ -159,7 +165,7 @@ Outputs: Description: The ARN of the IAM role created for the Temporal Service Value: !GetAtt TemporalServerlessWorker.Arn Export: - Name: !Sub "${AWS::StackName}-RoleARN" + Name: !Sub '${AWS::StackName}-RoleARN' RoleName: Description: The name of the IAM role @@ -167,7 +173,7 @@ Outputs: LambdaFunctionARNs: Description: The Lambda function ARNs that can be invoked - Value: !Join [", ", !Ref LambdaFunctionARNs] + Value: !Join [', ', !Ref LambdaFunctionARNs] ```
@@ -188,4 +194,6 @@ Use this role ARN when creating the Worker Deployment Version. ## Next steps {#next-steps} -Follow the [AWS Lambda deployment guide](/production-deployment/worker-deployments/serverless-workers/aws-lambda) to write your Worker code, deploy it to Lambda, and create a Worker Deployment Version with the IAM role from the previous step. +Follow the [AWS Lambda deployment guide](/production-deployment/worker-deployments/serverless-workers/aws-lambda) to +write your Worker code, deploy it to Lambda, and create a Worker Deployment Version with the IAM role from the previous +step. From 4db0b5a6fa7ecb50df1ebe059a5ab9fb1de6cde8 Mon Sep 17 00:00:00 2001 From: Lenny Chen Date: Thu, 23 Apr 2026 12:12:40 -0700 Subject: [PATCH 10/11] docs: reference self-hosted setup page in deploy guide prerequisites Co-Authored-By: Claude Opus 4.6 (1M context) --- .../worker-deployments/serverless-workers/aws-lambda.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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 1dd7f22963..fd2f2aa44a 100644 --- a/docs/production-deployment/worker-deployments/serverless-workers/aws-lambda.mdx +++ b/docs/production-deployment/worker-deployments/serverless-workers/aws-lambda.mdx @@ -27,7 +27,8 @@ This guide walks through deploying a Temporal [Serverless Worker](/serverless-wo ## Prerequisites {#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](https://docs.aws.amazon.com/lambda/latest/dg/configuration-vpc.html) to reach the Temporal frontend. + - For self-hosted deployments, complete the [self-hosted setup](/production-deployment/worker-deployments/serverless-workers/self-hosted-setup) before following this guide. + - The 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](https://docs.aws.amazon.com/lambda/latest/dg/configuration-vpc.html) 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](https://aws.amazon.com/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. From a04352b3d7e62f09d2faf46d6ed548c4f287ac25 Mon Sep 17 00:00:00 2001 From: Lenny Chen <55669665+lennessyy@users.noreply.github.com> Date: Fri, 24 Apr 2026 17:12:55 -0700 Subject: [PATCH 11/11] Apply suggestions from code review Co-authored-by: Stefan Richter --- .../serverless-workers/self-hosted-setup.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/production-deployment/worker-deployments/serverless-workers/self-hosted-setup.mdx b/docs/production-deployment/worker-deployments/serverless-workers/self-hosted-setup.mdx index dbb7875f9c..2b13a63efa 100644 --- a/docs/production-deployment/worker-deployments/serverless-workers/self-hosted-setup.mdx +++ b/docs/production-deployment/worker-deployments/serverless-workers/self-hosted-setup.mdx @@ -70,7 +70,7 @@ credentials depends on where the Temporal Service runs. automatically. No additional credential configuration is needed. The attached role must have `sts:AssumeRole` permission for the Lambda invocation role created in the next step. -**Outside AWS:** Configure AWS credentials in the server's environment: +**Outside AWS:** Use [IAM Roles Anywhere](https://aws.amazon.com/iam/roles-anywhere/), or configure static AWS credentials in the server's environment (not recommended): ``` AWS_ACCESS_KEY_ID= @@ -83,7 +83,7 @@ role. ## Create the Lambda invocation role {#create-invocation-role} -Temporal invokes Lambda functions by assuming an IAM role in your AWS account. This role needs `lambda:InvokeFunction` +Temporal invokes Lambda functions by assuming an IAM role in your AWS account. This role needs `lambda:GetFunction` and `lambda:InvokeFunction` permission on your Worker Lambda functions, and a trust policy that allows the Temporal server's identity to assume it. Deploy the following CloudFormation template to create the role.