From 553fc217f5af92b2f0e022b2b997dae7b225033c Mon Sep 17 00:00:00 2001 From: Lenny Chen Date: Thu, 27 Aug 2026 17:38:11 -0700 Subject: [PATCH] Document the per-Namespace Worker Controller Instance limit Adds a Max Worker Controller Instances entry to the Cloud limits page, covering the 100 default, that drained versions still count, and how it differs from the per-deployment version limit. Notes the limit in the serverless encyclopedia page and in both deploy guides at the step where a version is created. --- docs/encyclopedia/workers/serverless-workers/index.mdx | 5 +++++ docs/evaluate/temporal-cloud/limits.mdx | 10 ++++++++++ .../serverless-workers/aws-lambda/index.mdx | 4 ++++ .../serverless-workers/cloud-run/index.mdx | 4 ++++ 4 files changed, 23 insertions(+) diff --git a/docs/encyclopedia/workers/serverless-workers/index.mdx b/docs/encyclopedia/workers/serverless-workers/index.mdx index 64591073f8..072237c5b2 100644 --- a/docs/encyclopedia/workers/serverless-workers/index.mdx +++ b/docs/encyclopedia/workers/serverless-workers/index.mdx @@ -90,6 +90,11 @@ The Worker Controller Instance (WCI) is a system Workflow that scales Serverless One WCI Workflow runs per Worker Deployment Version that has a compute provider configured. The WCI runs in the same Namespace as your Worker Deployment. +A Namespace runs at most 100 WCI Workflows by default, which caps how many Worker Deployment Versions in the Namespace +can have a compute provider at once. A version's WCI runs until the version is deleted, so drained versions count +against the limit. See +[Max Worker Controller Instances limits](/cloud/limits#max-worker-controller-instances-limits). + The WCI adjusts the Worker count based on Task Queue conditions. Sync match failures and Task Queue backlog signal that more capacity is needed, and the WCI adds Workers by triggering the configured compute provider. It also removes capacity as work drains. How often the WCI re-evaluates the count, and how it sizes the pool, depends on the compute diff --git a/docs/evaluate/temporal-cloud/limits.mdx b/docs/evaluate/temporal-cloud/limits.mdx index 562542b3ed..3a6a86251e 100644 --- a/docs/evaluate/temporal-cloud/limits.mdx +++ b/docs/evaluate/temporal-cloud/limits.mdx @@ -398,3 +398,13 @@ The maximum number of versions that the server allows to be registered in a sing ### Max Task Queues In Deployment Version limits {/* #max-task-queues-in-deployment-version-limits */} The maximum number of Task Queues that the server allows to be registered in a single Worker Deployment Version. Defaults to 100. + +### Max Worker Controller Instances limits {/* #max-worker-controller-instances-limits */} + +The maximum number of [Worker Controller Instances](/serverless-workers#worker-controller-instance) that the server allows to run in a single Namespace. Defaults to 100. [Contact support](/cloud/support#support-ticket) to increase it. + +This limit applies only to [Serverless Workers](/serverless-workers). Temporal runs one Worker Controller Instance for each Worker Deployment Version that has a compute configuration, and the count covers every Worker Deployment in the Namespace. Drained versions still count, because the Worker Controller Instance runs until the version itself is deleted. + +Creating or updating a Worker Deployment Version with a compute configuration past the limit fails with `reached maximum worker controller instances in namespace`. To make room without raising the limit, delete Worker Deployment Versions you no longer need. + +This limit is separate from [Max versions in deployment limits](#max-versions-in-deployment-limits), which counts versions within one Worker Deployment rather than Worker Controller Instances across the Namespace. diff --git a/docs/production-deployment/worker-deployments/serverless-workers/aws-lambda/index.mdx b/docs/production-deployment/worker-deployments/serverless-workers/aws-lambda/index.mdx index c2e7bb3b9a..b8d1981f89 100644 --- a/docs/production-deployment/worker-deployments/serverless-workers/aws-lambda/index.mdx +++ b/docs/production-deployment/worker-deployments/serverless-workers/aws-lambda/index.mdx @@ -742,6 +742,10 @@ provider that points to your Lambda function. The compute configuration tells Te 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. +A Namespace runs at most 100 Worker Deployment Versions with a compute configuration by default. Creating a version +past that limit fails with `reached maximum worker controller instances in namespace`. See +[Max Worker Controller Instances limits](/cloud/limits#max-worker-controller-instances-limits). + You can create the version using the Temporal UI or the Temporal CLI. diff --git a/docs/production-deployment/worker-deployments/serverless-workers/cloud-run/index.mdx b/docs/production-deployment/worker-deployments/serverless-workers/cloud-run/index.mdx index 8e3e11b6d0..68689857ea 100644 --- a/docs/production-deployment/worker-deployments/serverless-workers/cloud-run/index.mdx +++ b/docs/production-deployment/worker-deployments/serverless-workers/cloud-run/index.mdx @@ -772,6 +772,10 @@ Create a [Worker Deployment Version](/production-deployment/worker-deployments/w configuration points at your Worker Pool. The compute configuration tells Temporal where the pool lives and which service account to impersonate to manage it. The deployment name and build ID must match the values in your Worker code. +A Namespace runs at most 100 Worker Deployment Versions with a compute configuration by default. Creating a version +past that limit fails with `reached maximum worker controller instances in namespace`. See +[Max Worker Controller Instances limits](/cloud/limits#max-worker-controller-instances-limits). +