workers/basics

378 notes in this subject, read out of this brain and free to use. This is page 4 of 7.

Worker configuration options in Python

The Worker constructor accepts keyword arguments that control concurrency limits, pollers, timeouts, and caching. Key options include `max_concurrent_activities`, `max_concurrent_workflow_tasks`, and `max_cached_workflows`. The defaults work for most cases. To tune these values against real load, see Worker performance and the Worker tuning reference.

Shut down a Worker gracefully in Python

Shut down a Worker by leaving the `async with` block, which calls shutdown() automatically. To keep the Worker running until process interruption, create an `asyncio.Event` and wait on it inside the async with block. Set the event from the entry point that catches KeyboardInterrupt. The Worker stops polling for new Tasks and waits for in-flight Tasks to finish up to the `graceful_shutdown_timeout` value (default or specified).

Worker graceful shutdown with timeout example in Python

Example of Worker graceful shutdown with timeout: worker = Worker( client, task_queue="my-task-queue", workflows=[HelloWorkflow], activities=[some_activity], graceful_shutdown_timeout=timedelta(seconds=30), ) async with worker: await interrupt_event.wait()

Worker graceful shutdown event handling example in Python

Example of handling KeyboardInterrupt to trigger graceful shutdown: interrupt_event = asyncio.Event() if __name__ == "__main__": loop = asyncio.new_event_loop() try: loop.run_until_complete(main()) except KeyboardInterrupt: interrupt_event.set() loop.run_until_complete(loop.shutdown_asyncgens())

Basic Worker creation example in Python

Example of basic Worker creation in Python: client = await Client.connect("localhost:7233") worker = Worker( client, task_queue="my-task-queue", workflows=[HelloWorkflow], activities=[some_activity], ) await worker.run()

Cloud Run Worker uses ClientConfig.load_client_connect_config for environment configuration

The temporalio.envconfig package loads Temporal Client configuration from environment variables and an optional TOML config file. Use ClientConfig.load_client_connect_config() to load configuration without storing credentials in Worker code. Set non-secret values as environment variables on the Worker Pool and mount the Temporal Cloud API key or TLS material from Secret Manager.

Cloud Run Worker ClientConfig.load_client_connect_config alternative

To inspect or change ClientConfig values before connecting, load the profile instead and convert it manually: from temporalio.envconfig import ClientConfigProfile; profile = ClientConfigProfile.load(); connect_config = profile.to_client_connect_config(); client = await Client.connect(**connect_config)

Cloud Run Worker requires WorkerDeploymentConfig

When running a Temporal Worker on GCP Cloud Run, you must pass a deployment_config parameter to Worker() that includes WorkerDeploymentConfig with version and use_worker_versioning=True. The deployment_config accepts a WorkerDeploymentVersion with deployment_name and build_id, which together identify the Worker Deployment Version.

Cloud Run Worker deployment_name and build_id must match temporal worker deployment create-version

The deployment_name and build_id values passed to WorkerDeploymentVersion must exactly match the version created with the temporal worker deployment create-version command. If they do not match, the Worker polls under a version that the WCI does not manage.

Cloud Run Worker Python code example with WorkerDeploymentConfig

import asyncio import os from temporalio.client import Client from temporalio.common import VersioningBehavior, WorkerDeploymentVersion from temporalio.envconfig import ClientConfig from temporalio.worker import Worker, WorkerDeploymentConfig from my_activities import my_activity from my_workflows import MyWorkflow async def main() -> None: client = await Client.connect(**ClientConfig.load_client_connect_config()) worker = Worker( client, task_queue=os.environ["TEMPORAL_TASK_QUEUE"], workflows=[MyWorkflow], activities=[my_activity], deployment_config=WorkerDeploymentConfig( version=WorkerDeploymentVersion( deployment_name="my-app", build_id="build-1", ), use_worker_versioning=True, default_versioning_behavior=VersioningBehavior.PINNED, ), ) await worker.run() if __name__ == "__main__": asyncio.run(main())

Python SDK serverless workers supported providers

The Python SDK supports two serverless compute providers: AWS Lambda (in Public Preview) using the lambda_worker contrib package, and GCP Cloud Run (in Pre-release) running a standard Worker on a Cloud Run worker pool.

GCP Cloud Run support status

GCP Cloud Run support for Temporal serverless workers is in Pre-release and its APIs may change in backwards-incompatible ways. A standard Worker runs on a Cloud Run worker pool, covering versioned Worker setup, connection configuration, and handling scale-in.

AWS Lambda support status

AWS Lambda support for Temporal serverless workers is in Public Preview. The lambda_worker contrib package is used to run a Worker as a Lambda function, covering setup, configuration, Lambda-tuned defaults, and observability.

LambdaWorkerConfig configure callback receives pre-populated defaults

The configure callback receives a LambdaWorkerConfig dataclass with fields pre-populated with Lambda-appropriate defaults. Set the Task Queue, Workflows, and Activities through worker_config, which accepts the same keyword arguments as the Worker constructor.

lambda_worker package provides serverless worker support

The lambda_worker contrib package lets you run a Temporal Serverless Worker on AWS Lambda. Deploy your Worker code as a Lambda function, and Temporal Cloud invokes it when Tasks arrive. Each invocation starts a Worker, polls for Tasks, then gracefully shuts down before a configurable invocation deadline.

shutdown_deadline_buffer controls graceful shutdown timing

shutdown_deadline_buffer is specific to the lambda_worker package and controls how much time before the Lambda deadline the Worker begins its graceful shutdown. The default is graceful_shutdown_timeout plus 2 seconds.

Lambda serverless worker example configuration

Example Lambda handler using run_worker: from activities import hello_activity; from temporalio.common import WorkerDeploymentVersion; from temporalio.contrib.aws.lambda_worker import LambdaWorkerConfig, run_worker; 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]; lambda_handler = run_worker(WorkerDeploymentVersion(deployment_name="my-app", build_id="build-1"), configure)

Enable worker versioning with build_id parameter

To enable Worker Versioning in Python, pass the build_id parameter and set use_worker_versioning=True when creating a Worker. The build_id can be passed from an environment variable. The build_id and use_worker_versioning parameters are set on the Worker constructor.

Worker setup for Standalone Activities

Running a Worker for Standalone Activities is the same as running a Worker for Workflow Activities — you create a Temporalio::Worker, register the Activity class with the activities parameter, and call worker.run. The Worker does not need to know whether the Activity will be invoked from a Workflow or as a Standalone Activity.

Ruby SDK Standalone Activity Worker example

Example of running a Worker with Standalone Activities: ```ruby args, kwargs = Temporalio::EnvConfig::ClientConfig.load_client_connect_options args[0] ||= 'localhost:7233' args[1] ||= 'default' client = Temporalio::Client.connect(*args, **kwargs) worker = Temporalio::Worker.new( client:, task_queue: 'standalone-activity-sample', activities: [StandaloneActivity::MyActivities::ComposeGreeting] ) puts 'Starting worker (ctrl+c to exit)' worker.run(shutdown_signals: ['SIGINT']) ```

Ruby SDK installation and quickstart

Detailed installation instructions for the Ruby SDK are available in the Quickstart guide. The guide includes a walkthrough of how to use Temporal primitives (Activities, Workflows, and Workers) to build and run a Temporal application. After setting up a local Temporal Service, developers should start with Workflow basics, Activity basics, Activity execution, and Worker processes.

Workers documentation structure for Ruby SDK

The Ruby SDK workers documentation includes guidance on worker processes. This is located in the workers section of the Ruby SDK development documentation.

Install Temporal Ruby SDK with Bundler

Create a new Ruby project directory and initialize it with Bundler using 'bundle init'. Then add the Temporal SDK gem with 'bundle add temporalio' and install dependencies with 'bundle install'.

Ruby SDK system requirements

Ruby 3.2 or higher is required. Ruby 3.4.3 is recommended. Fibers and async are only supported on Ruby 3.3 and higher. Only macOS ARM/x64 and Linux ARM/x64 are supported. Windows (MinGW) is not supported.

Start local Temporal Service

Use the command 'temporal server start-dev' to start a local development server. The Temporal Service will be available on localhost:7233. The Temporal Web UI will be available at http://localhost:8233. Use the '--ui-port' option to change the Web UI port, for example 'temporal server start-dev --ui-port 8080'.

Create and run a Worker in Ruby

Create a Worker using Temporalio::Worker.new with parameters: client (Temporalio::Client), task_queue (string), workflows (array of workflow classes), and activities (array of activity classes). Run the worker with worker.run(shutdown_signals: ['SIGINT']) to run until interrupted. Example: worker = Temporalio::Worker.new(client:, task_queue: 'my-task-queue', workflows: [SayHelloWorkflow], activities: [SayHelloActivity]); worker.run(shutdown_signals: ['SIGINT'])

Connect to Temporal Service in Ruby

Create a client connection using Temporalio::Client.connect(address, namespace). Example: client = Temporalio::Client.connect('localhost:7233', 'default')

Worker registration with class vs instance for activities

When registering Activities, pass either the class or an instance. Passing a class makes the Worker instantiate it for each Activity Execution. Passing an instance reuses that object for every execution, which allows Activities to share state such as a database client. A shared instance must be thread-safe.

Create a Worker with task queue and register types

Create a Temporalio::Worker by passing a client, task_queue name, workflows array, and activities array. Call worker.run to start polling for tasks. The run method blocks until the Worker shuts down.

Ruby Worker shutdown signal example

```rb worker.run(shutdown_signals: %w[SIGINT SIGTERM]) ``` This example shows how to pass shutdown signals to the run method to gracefully stop the Worker when SIGINT or SIGTERM signals are received.

Ruby Worker creation example

```rb worker = Temporalio::Worker.new( client: client, task_queue: 'my-task-queue', workflows: [GreetingWorkflow], activities: [SayHello] ) worker.run ``` This example shows how to create a Worker with a client, task queue, workflows, and activities, then start it with run.

Ruby Worker graceful shutdown

Pass the signals that should stop the Worker to run via the shutdown_signals parameter. The Worker stops polling for new Tasks and waits for in-flight Tasks to finish. You can also pass a block to run, which shuts the Worker down when the block completes, or stop the Worker with a Temporalio::Cancellation. Temporalio::Worker.run_all takes the same shutdown_signals, cancellation, and block parameters, and applies them to every Worker it was given.

Worker configuration options

Temporalio::Worker.new takes keyword arguments that control concurrency limits, pollers, timeouts, and caching, including max_concurrent_activities, max_concurrent_workflow_tasks, and max_cached_workflows. The defaults work for most cases. To tune these values against real load, see Worker performance and the Worker tuning reference.

Run multiple Workers in one process

Use Temporalio::Worker.run_all to run several Workers in one process. This method returns once every Worker it was given has stopped.

Ruby Worker registration with multiple Workflow versions

client = Temporalio::Client.connect('localhost:7233', 'default') worker = Temporalio::Worker.new( client:, task_queue: 'my-task-queue', workflows: [MyWorkflow, MyWorkflowV2] ) This example shows how to register multiple Workflow versions with a Worker so that both can be executed.

Temporal CLI installation on macOS

The Temporal CLI can be installed on macOS using either Homebrew or by downloading from CDN. For Homebrew, run 'brew install temporal'. For CDN download, select Darwin amd64 at https://temporal.download/cli/archive/latest?platform=darwin&arch=amd64 or Darwin arm64 at https://temporal.download/cli/archive/latest?platform=darwin&arch=arm64, extract the archive, and add the temporal binary to your PATH.

Temporal CLI installation on Windows

The Temporal CLI can be installed on Windows by downloading from CDN. Select Windows amd64 at https://temporal.download/cli/archive/latest?platform=windows&arch=amd64 or Windows arm64 at https://temporal.download/cli/archive/latest?platform=windows&arch=arm64, extract the archive, and add the temporal.exe binary to your PATH.

Customize development server startup

The Temporal development server's startup configuration can be customized using command line options. Run 'temporal server start-dev --help' to see a full list of available options.

Temporal CLI what it includes

The Temporal CLI is a tool for interacting with a Temporal Service from the command line. It includes a distribution of the Temporal Server and Web UI. The local development Temporal Service runs as a single process with zero runtime dependencies and supports persistence to disk and in-memory mode through SQLite.

Temporal CLI installation on Linux

The Temporal CLI can be installed on Linux using either Homebrew or by downloading from CDN. For Homebrew, run 'brew install temporal'. For CDN download, select Linux amd64 at https://temporal.download/cli/archive/latest?platform=linux&arch=amd64 or Linux arm64 at https://temporal.download/cli/archive/latest?platform=linux&arch=arm64, extract the archive, and add the temporal binary to your PATH.

Rust SDK developer guide main topics

The Rust SDK developer guide covers workflows, activities, workers, Temporal Client, and Temporal Nexus. Main learning paths include developing workflows (with child workflows, continue-as-new, message passing, cancellation, timers, and timeouts), developing activities (with execution and timeouts), running worker processes, and using the Temporal Client.

mTLS certificate rotation requires Worker restart in Rust SDK

Rotating an mTLS client certificate without restarting the Worker is not currently supported by the Rust SDK because the certificate in TlsOptions is read once and baked into the connection at Connection::connect. To rotate a certificate, stage the new certificate alongside the old one on your Temporal Cloud Namespace, then restart your Worker with the new certificate before removing the old one.

Temporal Cloud namespace format with account ID

Your Namespace and Account ID combination should be in the format <namespace_id>.<account_id>, and the recommended gRPC endpoint is <namespace>.<account>.tmprl.cloud:7233.

Connect to Temporal Cloud with mTLS in code

Use ConnectionOptions with .tls_options(TlsOptions { ... }) to specify TLS configuration for mTLS authentication. The TlsOptions can include CA certificate, client certificate, and client key paths.

Connect to Temporal Cloud with API key in code

Use ConnectionOptions::new(Url::from_str("your-namespace.a1b2c.tmprl.cloud:7233")?) with .api_key("your_api_key") method to specify API key authentication directly in code.

Environment variables for Temporal Cloud connection

Common environment variables for Temporal Cloud connections: TEMPORAL_NAMESPACE, TEMPORAL_ADDRESS, TEMPORAL_API_KEY, TEMPORAL_TLS_CLIENT_CERT_DATA or TEMPORAL_TLS_CLIENT_CERT_PATH, and TEMPORAL_TLS_CLIENT_KEY_DATA or TEMPORAL_TLS_CLIENT_KEY_PATH.

Load Temporal Client configuration from environment variables in Rust

Use ClientOptions::load_from_config(LoadClientConfigProfileOptions::default())? to load configuration from environment variables. This applies default profile behavior which reads from environment variables like TEMPORAL_NAMESPACE, TEMPORAL_ADDRESS, TEMPORAL_API_KEY, etc.

Load Temporal Client configuration from profile in Rust

Use ClientOptions::load_from_config(LoadClientConfigProfileOptions { config_file_profile: "profile-name".to_string().into(), ..Default::default() })? to load configuration from a specific profile. Then create a Connection with Connection::connect(conn_opts).await? and Client with Client::new(connection, client_opts)?.

TOML profile configuration structure for Temporal Cloud

For a Temporal Cloud profile, specify address = "your-namespace.a1b2c.tmprl.cloud:7233", namespace = "your-namespace", and either api_key = "your-api-key-here" for API key authentication. For mTLS, use [profile.profile-name.tls] section with client_cert_path and client_key_path.

TOML profile configuration structure for local development

For a local development profile, use address = "localhost:7233" and namespace = "default". Optional custom gRPC headers can be added under [profile.profile-name.grpc_meta] with key-value pairs like my-custom-header = "development-value".

TOML configuration file for Temporal Client profiles

Create a temporal.toml configuration file with multiple profiles, each containing connection options. Each profile section is named [profile.profile-name]. The SDK looks in default OS-specific locations if no configuration file path is specified. Environment variables take precedence over values from the configuration file.

Create Temporal Client in Rust by establishing Connection

In Rust, create a Temporal Client by establishing a Connection and then constructing a Client. Connection options can be provided directly in code, loaded from environment variables, or read from a TOML configuration file.

Temporal Client purpose in Rust SDK

A Temporal Client lets your application communicate with the Temporal Service. Use it to start Workflow Executions, send Signals, run Queries, fetch Workflow results, and more. A Temporal Client cannot be created and used inside Workflow code, but using one inside an Activity is acceptable when you need to communicate with the Temporal Service.

Rust SDK Workers documentation overview

The Rust SDK documentation section on Workers explains how to implement Workers with the Rust SDK. The documentation includes a page on worker processes.

Worker setup in Rust

Workers are created using Worker::new() which takes a CoreRuntime, Client, and WorkerOptions. WorkerOptions specifies a task queue name and registers activities and workflows using .register_activities() and .register_workflow::<T>() methods. The worker is started with .run().await?. Example: let worker_options = WorkerOptions::new("my-task-queue").register_activities(MyActivities).register_workflow::<GreetingWorkflow>().build(); Worker::new(&runtime, client, worker_options)?.run().await?

Temporal CLI installation and setup

Temporal CLI is installed via brew on macOS with 'brew install temporal', downloaded as an archive on Windows and Linux from temporal.download/cli, and the binary is added to PATH. The development server starts with 'temporal server start-dev' command, which starts the Web UI on localhost:8233, creates the default namespace, uses in-memory database, and makes the Temporal Service available on localhost:7233. The Web UI port can be changed with the --ui-port option.

Temporal client initialization in Rust

The Temporal client is initialized by first creating a CoreRuntime using CoreRuntime::new_assume_tokio() with RuntimeOptions. Then ClientOptions::load_from_config() loads configuration from environment or config files. A Connection is established using Connection::connect() with connection options. Finally, Client::new() is called with the connection and client options.

Rust SDK dependencies versions

The core Temporal Rust SDK dependencies are: temporalio-sdk version 0.5.0, temporalio-client version 0.5.0, temporalio-common version 0.5.0, temporalio-macros version 0.5.0, temporalio-sdk-core version 0.5.0. Also required are tokio version 1 with full features, futures version 0.3.32, futures-util version 0.3.32, serde version 1 with derive feature, and serde_json version 1.

Rust SDK dependencies for Worker

To create a Worker in Rust SDK, include these dependencies in Cargo.toml: temporalio-sdk 0.5.0, temporalio-client 0.5.0, temporalio-sdk-core 0.5.0, temporalio-common 0.5.0, temporalio-macros 0.5.0, temporalio-workflow 0.5.0, futures 0.3, and tokio 1 with full features. The #[workflow] and #[activities] macros expand to code that requires temporalio-workflow and futures as direct dependencies even if your code does not directly reference them.

Worker shutdown example in Rust

Example of graceful Worker shutdown: ```rust let mut worker = Worker::new(&runtime, client, worker_options)?; let shutdown = worker.shutdown_handle(); tokio::spawn(async move { tokio::signal::ctrl_c().await.expect("failed to listen for ctrl-c"); shutdown(); }); worker.run().await?; ``` This obtains a shutdown handle before running the worker, spawns a task listening for Ctrl+C, and invokes shutdown when the signal is received.

Give your agent this brain