Durable Workflow Orchestration
How do we get started with Temporal locally (dev server) and then deploy workers to Kubernetes?
8 min read
What if you could debug Temporal on your laptop, then run the exact same Workflows in Kubernetes without rewriting anything? That’s the point of Temporal’s model: your code is just code. The Temporal Service coordinates execution; Workers run wherever you deploy them—localhost today, a K8s cluster tomorrow.
Quick Answer: Start by running the Temporal dev server with the Temporal CLI, build and test your Workflows/Workers locally, then point those same Workers at a Temporal Cluster reachable from Kubernetes (self-hosted or Temporal Cloud) and deploy them as standard Deployments. Temporal orchestrates; your Workers scale in K8s like any other stateless service.
Quick Answer: To get started locally, install the Temporal CLI, run
temporal server start-dev, choose an SDK, run a sample Workflow, and inspect it in the Temporal Web UI athttp://127.0.0.1:8233.
Frequently Asked Questions
How do I get Temporal running locally in dev mode?
Short Answer: Install the Temporal CLI, start the dev server with temporal server start-dev, run a sample Workflow with your preferred SDK, and open the Web UI on http://127.0.0.1:8233 to see it live.
Expanded Explanation:
Local is where you should learn Temporal’s mental model—Workflows, Activities, task queues, retries, and replay. The Temporal CLI bundles a lightweight “all-in-one” dev server so you don’t have to stand up multiple services, databases, or queues just to try it.
Once the CLI is installed and on your PATH, you can spin up a fully functional Temporal development server with a single command. From there, you choose an SDK (Go, Java, TypeScript, Python, or .NET), run a sample Workflow, and then inspect its full execution history in the Web UI. That execution history—durable events plus deterministic replay—is what lets Workflows resume after crashes, timeouts, or restarts without losing progress.
Key Takeaways:
- Use the Temporal CLI for a one-command dev server:
temporal server start-dev. - Use the Web UI at
http://127.0.0.1:8233to see Workflow state, events, and retries in real time.
What’s the step‑by‑step process to go from local dev server to Workers in Kubernetes?
Short Answer: First, develop and test your Workflows/Workers against the local dev server. Next, provision a real Temporal Cluster (self-hosted or Temporal Cloud), update Worker config to point to that Cluster, then deploy Workers as Kubernetes Deployments with proper task queues and credentials.
Expanded Explanation:
The local dev server is for learning, iteration, and integration tests. It is not meant for production. The migration path is intentionally simple: Temporal’s contract with your code doesn’t change. A Worker process you run with go run on your laptop is the same binary you’ll run in a container inside Kubernetes. All you change is the host:port for the Temporal Service and the credentials you use to connect.
The high‑level flow looks like this: build Workflows and Activities locally, verify that failure semantics (retries, timeouts, cancellation) behave the way you expect, then create a Temporal Cluster (via Helm charts, operator, or Temporal Cloud). Once that Cluster exists, you point your Worker(s) at it and deploy them as K8s Deployments with the right environment variables and config maps. Temporal doesn’t run your code—it only dispatches tasks over gRPC—so this is just “another stateless service” from Kubernetes’ perspective.
Steps:
- Local build and test
- Install Temporal CLI and start dev server:
temporal server start-dev. - Choose an SDK and run a sample Workflow and Worker locally.
- Confirm Workflows complete correctly and recover from simulated failures.
- Install Temporal CLI and start dev server:
- Provision a Temporal Cluster
- Self‑host using Helm/operator, or create a Namespace in Temporal Cloud.
- Configure TLS and auth as needed.
- Confirm connectivity from your target cluster (e.g., simple gRPC health check).
- Deploy Workers to Kubernetes
- Containerize your Worker service.
- Configure it to use the production Cluster endpoint and Namespace.
- Deploy as a Kubernetes Deployment with appropriate resource requests and scaling.
What changes when I move from the Temporal dev server to a full Cluster (self‑hosted or Cloud)?
Short Answer: Your code stays the same; the Temporal Service changes from a single‑process dev server to a multi‑service, highly durable Cluster (self‑hosted or Temporal Cloud) with real persistence, multi‑region options, and production‑grade security.
Expanded Explanation:
The dev server (temporal server start-dev) is great for quick feedback loops. It runs everything in a single process, backed by an ephemeral database. You wipe and restart it freely. A real Cluster—whether you deploy it yourself to Kubernetes or use Temporal Cloud—splits the Service into dedicated components (Frontend, Matching, History, persistence backends) with strong durability guarantees, scale, and observability.
For your Workers and client code, the mechanics are identical: they talk to a Temporal frontend via gRPC, send Workflow and Activity tasks, and receive decisions and work. The main differences are around deployment, state durability, and operational posture (backups, metrics, alarms). That’s why moving from dev to Cluster is mostly configuration changes, not a refactor.
Comparison Snapshot:
- Dev Server (
start-dev):
Single process, ephemeral storage, runs locally for development and tests, quick reset. - Full Temporal Cluster / Cloud:
Multi‑service, durable storage, horizontally scalable, production‑grade security, metrics, and SLAs. - Best for:
Use dev server for local loops and CI; use a real Cluster for any shared, staging, or production environment.
How do I actually deploy Temporal Workers on Kubernetes?
Short Answer: Package your Worker as a container, configure it to connect to your Temporal Cluster, then run it as a Deployment that listens on one or more task queues. Kubernetes handles scaling; Temporal handles routing, retries, and durable execution.
Expanded Explanation:
A Temporal Worker is just a long‑running process that: (1) connects to the Temporal Service, (2) polls task queues, (3) executes Workflows and Activities, and (4) records progress to the Service. This is a perfect fit for Kubernetes Deployments: stateless containers that you can scale up or down as needed. The “state” of your Workflows lives in Temporal’s event histories, not in the Worker pods.
To deploy, you containerize your Worker binary or app, embed configuration (Cluster address, Namespace, task queue names, TLS certs) via environment variables or ConfigMaps, and let Kubernetes keep the desired number of replicas running. When a pod dies, Temporal simply hands the next task to another Worker. No lost progress, no manual recovery.
What You Need:
- A containerized Worker service built in your chosen SDK (Go, Java, TypeScript, Python, .NET) that registers your Workflows/Activities and polls a task queue.
- Kubernetes manifests or Helm charts defining a Deployment (and optional Horizontal Pod Autoscaler) with environment variables pointing to your Temporal Cluster and Namespace.
How should we think strategically about starting local, then scaling Temporal on Kubernetes?
Short Answer: Treat the dev server as your reliability playground, design Workflows around failure semantics from day one, and then let Kubernetes handle Worker scale while Temporal guarantees no lost progress and full visibility across environments.
Expanded Explanation:
The biggest mistake teams make is treating Temporal as “just another orchestrator” they bolt on late. That’s where you end up with a hybrid of brittle state machines, ad‑hoc retries, and half‑migrated flows. Instead, start by modeling critical flows in Temporal locally: moving money, order fulfillment, CI/CD rollbacks, human‑in‑the‑loop approvals, AI training or agentic pipelines. Break them into Workflows (long‑lived, durable) and Activities (failure‑prone operations with policy‑based retries and timeouts).
Once the model is right locally, moving to Kubernetes is just a deployment concern. You can have multiple Worker Deployments listening on different task queues, each written in different languages, all talking to the same Temporal Cluster. Operators get a single Web UI to see every execution, replay failures, and even “rewind” business logic by replaying history with new code. Either way—self‑hosted or Temporal Cloud—we never see your code. Workers stay in your environment; the Service coordinates over unidirectional, encrypted connections.
Why It Matters:
- Reliability becomes a primitive, not an afterthought: You gain durable state, replay, and policy‑driven retries from day one instead of scattered, hand‑rolled resilience in each microservice.
- Kubernetes focuses on compute, Temporal focuses on correctness: K8s scales your Worker pods up and down; Temporal ensures every Workflow eventually completes or fails explicitly, with no orphaned processes and no manual recovery.
Quick Recap
Start with the Temporal CLI and the dev server (temporal server start-dev) to learn the model and iterate quickly. Use the Web UI at http://127.0.0.1:8233 to inspect and replay Workflows so you understand how durable execution works. When you’re ready, provision a real Temporal Cluster—self‑hosted or Temporal Cloud—point your Workers at it, and deploy them as standard Kubernetes Deployments. The same code you trusted locally will now run at cluster scale, with Temporal guaranteeing no lost progress while Kubernetes manages compute.